pnpm dlx shadcn@4.18.0 add @siteplane-pro/page-header-demo

This Pattern is part of Siteplane UI Pro, and its source comes with a Pro license. Its previews are free to view and try.

Installation

pnpm dlx shadcn@4.18.0 add @siteplane-pro/page-header

Usage

import { PageHeader } from "@/siteplane/components/page-header";

<PageHeader
  description="Manage your team and its access permissions."
  title="Team members"
/>;

Composition

PageHeader
├── banner (optional cover)
├── avatar (optional, with an optional badge)
├── breadcrumbs → PageHeaderBreadcrumbs
├── icon, title and count (optional icon and count)
├── description
├── actions
└── search

Breadcrumbs

Pass PageHeaderBreadcrumbs as breadcrumbs. In a header at least 40rem (640 px) wide it shows the trail with a home icon; when there are more than two levels, the middle ones collapse behind an ellipsis button that reveals them and moves focus to the first one. In a narrower header it shows a Back link to the previous level instead, whose arrow points to the right in a right-to-left page. The first example shows both behaviors.

Actions

In a header at least 48rem (768 px) wide, the actions and the search share the title's row while they fit beside the title's minimum width of 20rem (320 px). When they need more room, they move below the title and wrap within the header, so the title never narrows below that width. The header decides this by its own width, not the viewport's. In a narrower header the actions always sit below the title.

Avatar

Set avatar to introduce a person or an organization. Without a banner it sits beside the title.

pnpm dlx shadcn@4.18.0 add @siteplane-pro/page-header-avatar-example

Banner

Set banner for a cover above the header. true shows the cover surface alone, and an image or other media replaces it. With an avatar, the avatar overlaps the cover and keeps a ring in the header color; badge places a mark such as a verified check on its bottom end.

pnpm dlx shadcn@4.18.0 add @siteplane-pro/page-header-banner-example

pnpm dlx shadcn@4.18.0 add @siteplane-pro/page-header-banner-avatar-example

Centered

Set centered to center the content. The actions and the search stack below the title, and with a banner and an avatar the breadcrumb trail moves to the start edge in a header at least 48rem (768 px) wide.

pnpm dlx shadcn@4.18.0 add @siteplane-pro/page-header-centered-example

pnpm dlx shadcn@4.18.0 add @siteplane-pro/page-header-centered-avatar-example

Section heading

Set variant="section" for the smaller stage of the header: a heading over a group of cards. It draws no surface, margins or divider, and its title is an h2 in the type of a Card title, 18 px on a 27 px line in the title weight, --sp-rw-font-weight-title. icon leads the title with a 20 px icon in the accent color, centered on the title's first line, and count sets a count beside the title in an info badge. The actions share the title's row while both fit and move below it otherwise. Beside a title alone they center on it; with a description they start at its top.

Set iconTone="neutral" to draw the icon in the secondary text color, --sp-rw-fg-secondary, instead of the accent. A neutral icon suits a module or section icon and leaves color to states, as the neutral tone of a Card's CardMedia does.

titleId gives the heading an id, so the section around the header can name itself with aria-labelledby. The count is part of the heading, so give it a contextual name where the number alone is unclear, such as the visually hidden text in the example. icon, iconTone and count work in the page stage too. Breadcrumbs, search, a banner, an avatar and centered belong to the page stage.

pnpm dlx shadcn@4.18.0 add @siteplane-pro/page-header-section-example

API reference

PageHeaderProps extends native div props without the native title, so className, id and aria-* reach its root element. It is a union of the two stages, so TypeScript rejects the page stage's breadcrumbs, search, banner, avatar and centered on a section heading. The root is a plain block rather than a landmark, so it adds nothing to the landmarks of your page. The page stage paints the primary surface and draws the cover in the accent tint. Exported types: PageHeaderProps.

Usage notes

Use one page header per page: its title is the page's h1. A header that introduces a section inside a page sets titleLevel to its place in the outline, and a heading over a group of cards takes the section stage. PageHeader does not fetch data, route or own the actions; your application supplies the content and the handlers. PageHeaderBreadcrumbs renders plain anchors, so with a client router, build the trail from Breadcrumb parts and pass it as breadcrumbs.

PageHeader lays out by its own width, not the viewport's, so it holds up in a column beside a sidebar as in a narrow window. From 40rem (640 px) of header width the banner, the avatar and the margins take their wide sizes and the full breadcrumb trail shows; from 48rem (768 px) the actions and the search share the title's row while they leave the title at least 20rem (320 px), and wrap below it otherwise. Three actions and the search field take about 460 px, so they share the row from a header width of about 54rem (864 px). The previews on this page are narrower than a page, so the non-centered examples leave out the search field.

Give the avatar a meaningful alt, and describe a badge in text, such as the visually hidden Verified in the examples. The examples use fragment destinations to keep the preview local.