# Page Header

Introduce a page with its title, breadcrumb, actions and search.

Page header with breadcrumb and actions

**Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing).

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

This Pattern is part of [Siteplane UI Pro](/pricing), and its source comes with a [Pro license](/docs/license/#patterns). Its previews are free to view and try.

## Installation

**Pro** — Installs with a Siteplane UI Pro license key. Complete the one-time [Pro setup](/docs/installation/#siteplane-ui-pro) first. Get a license on the [Pro page](/pricing).

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

With npm: `npx shadcn@4.18.0 add @siteplane-pro/page-header`.

## Usage

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

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

## Composition

```text
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.

Page header with an avatar

**Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing).

```bash
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.

Page header with a banner

**Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing).

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

Page header with a banner and a verified avatar

**Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing).

```bash
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.

Centered page header with a banner

**Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing).

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

Centered page header with a banner and a verified avatar

**Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing).

```bash
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.

Section heading with an icon, a count and a link over two cards

**Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing).

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

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| PageHeader.title | ReactNode | required | Page title, rendered as a heading: the page's h1 in the strong weight, --sp-rw-font-weight-strong (600), unless titleLevel sets another level. The section stage renders an h2 in the title weight, --sp-rw-font-weight-title (450). |
| PageHeader.variant | page \| section | page | page introduces a page on the primary surface. section is the smaller stage for a heading over a group of cards, without surface, margins or divider. |
| PageHeader.titleLevel | 1 \| 2 \| 3 \| 4 \| 5 \| 6 | 1, 2 in the section stage | Heading level of the title, with the same look at every level. Use it for a header inside a page section. |
| PageHeader.titleId | string | unset | Id of the title's heading, so the surrounding section can name itself with aria-labelledby. id reaches the root element. |
| PageHeader.description | ReactNode | unset | Supporting text below the title. |
| PageHeader.icon | ReactNode | unset | Decorative icon before the title, 20 px in the accent color and centered on the title's first line. It is hidden from assistive technology. |
| PageHeader.iconTone | accent \| neutral | accent | Color of the icon: the accent, or the secondary text color, --sp-rw-fg-secondary, for a module icon that leaves color to states. |
| PageHeader.count | ReactNode | unset | Count beside the title in an info badge, as part of the heading. 0 shows; an empty string, null or false shows nothing. |
| PageHeader.breadcrumbs | ReactNode | unset | Navigation above the title. Use PageHeaderBreadcrumbs or your own Breadcrumb. Page stage only. |
| PageHeader.actions | ReactNode | unset | Buttons beside the title in a header at least 48rem wide while they fit beside the title's minimum width of 20rem, below it otherwise and in a narrower header. In the section stage they sit beside the title while both fit. |
| PageHeader.search | ReactNode | unset | Search field next to the actions; full width in a narrow header and 16 rem in a header at least 40rem wide. Page stage only. |
| PageHeader.banner | ReactNode | unset | Cover above the header. true shows the cover surface alone; an image or other media replaces it. Page stage only. |
| PageHeader.avatar | { src?: string; initials: string; alt: string; badge?: ReactNode } | unset | Avatar beside the title, or overlapping the banner when there is one. badge sits on the avatar's bottom end. Page stage only. |
| PageHeader.centered | boolean | false | Centers the content and stacks the actions and the search. Page stage only. |
| PageHeaderBreadcrumbs.items | readonly { label: string; href?: string }[] | required | Levels after home. The last one is the current page and is not a link. |
| PageHeaderBreadcrumbs.homeHref | string | required | Destination of the home icon. |
| PageHeaderBreadcrumbs.homeLabel | string | Home | Accessible name of the home link. |
| PageHeaderBreadcrumbs.backLabel | string | Back | Text of the Back link in a header narrower than 40rem. It points to the previous level, or to home when there is none. |
| PageHeaderBreadcrumbs.expandLabel | string | Show all levels | Accessible name of the ellipsis button that reveals the collapsed levels. |
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](/docs/components/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.