# Page Header

The title row at the top of a page or section, with an optional description, buttons or a text link.

- Category: Navigation & Layout
- Page: https://wunderui.com/components/page-header
- Tier: Core and Pro

## Install

Page Header ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { PageHeader, AuthHeading, PageHeaderProps } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { Button, PageHeader } from "@wunderui/react"

export function Settings() {
  return (
    <PageHeader
      title="Workspace settings"
      description="Manage members, billing and integrations for WunderUI."
      actions={
        <Button variant="gradient" size="sm">
          Save changes
        </Button>
      }
    />
  )
}
```

Expected result: You see a 30 px bold title with one grey line under it and a gradient button at the far end of the row. In a container narrower than 640 px the button moves under the text.

## When to use

### Use Page Header for

- The title of an app page, with one sentence of context and the actions for the whole page
- The heading of a section of a page, with a link such as View all or one or two buttons
- A header that must hold up with a long title, a long description and a narrow container

### Use something else

- [Settings Row](https://wunderui.com/components/settings-row) for one setting with its label, its description and its control
- [Card](https://wunderui.com/components/card) for a titled surface that holds content, with its own header

## Keyboard

The header is not interactive: the title and description are not tab stops and it handles no keys. The link and buttons in it are native elements and behave as the browser makes them.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves between the buttons of `actions` in reading order and to the `link`. The title and the description are skipped. |
| `Enter` | Follows the focused link, or presses the focused button. |
| `Space` | Presses the focused button. On the link it does nothing; the browser may scroll the page. |

A link follows on Enter only. Space does not follow a link, and the browser may scroll the page instead; a button answers to both.

## Behavior

What the header does with its content and its width, and what it leaves to you.

- **Heading element:** The page level renders an h1, the section level an h2. The as prop takes h1, h2 or h3 and changes only the element; size and weight still come from the level.
- **Layout:** Below 640 px of container width the text and the trailing group stack, above it they sit side by side. It follows its container, not the window, so a narrow side panel stacks on a wide screen.
- **Alignment:** The trailing group aligns with the top of the title. A section header with a link centres the link on the title row, so one line of text and one line of title line up.
- **Long text:** A long title wraps and so does the paragraph; nothing is cut off. The actions keep their width and wrap their own buttons when the group is wider than the row.
- **Description:** Without a description the header is the title alone and the 4 px gap is gone. Undefined, null, false and an empty string render nothing; the number 0 would render a 0, so pass undefined instead.
- **Link:** The link is a plain anchor with the standard focus ring. The click handler does not prevent the default, so an in-app route calls preventDefault itself.
- **States:** The header has no state of its own; hover only underlines the link. A disabled or busy button is your own Button in the actions, and the Examples tab shows Save and Discard that follow a field.
- **Semantics:** The header is a div, not a landmark: the title is the only heading it adds. Name the landmark yourself where it matters, for example with main and aria-labelledby.
- **Motion:** None. The only change is the underline of the link on hover, so reduced motion changes nothing.

## Anatomy

- `PageHeader`: A flex row with a 12 px gap that stacks when its container is narrower than 640 px: the text block at the start, the actions or link at the end. It has no border or background.
- `Title`: The heading: a 30 px bold h1 at page level, a 16 px semibold h2 at section level. The as prop changes the element, not the look.
- `Description`: A 14 px paragraph in secondary text, 4 px under the title. It takes any node and wraps.
- `Actions`: A group at the end that holds your buttons, 8 px apart. It keeps its width and wraps its own buttons when there is no room.
- `Link`: A text link at the end in the link colour, 14 px medium, underlined on hover. In a section header it is centred on the title; otherwise it sits at the top.
- `AuthHeading`

## Best practices

### When to use

- Use PageHeader at the top of an app page or section: title, one line of context and the page actions. A sign-in form has Auth Heading; a card has its own header.

### Do

- Keep one page-level header per view, since it renders the h1. Use the section level for parts below it, and as h2 on the page level only where the page already has its own h1.
- Put at most one call to action in the actions, last, as a gradient button, and make every other button plain. For a single text action such as View all, use the link.
- Write the description as one sentence that says what is on the page, not what the page is called. Two lines is the most a header should need.
- Give the link a real href, since the default only scrolls to the top. For in-app routing pass the route as the href and navigate in the click handler, calling preventDefault there.

### Don't

- Don't use the page level for a section title. It renders a second h1 at 30 px and breaks the outline of the page.
- Don't put a breadcrumb, tabs or filters inside the header. Put the breadcrumb above it and the tabs or filters below, so the header stays one title row.
- Don't put more than three buttons in the actions. They wrap onto a second line on a narrow screen; move the rest into a menu.

## API reference

### PageHeader

| Prop | Type | Default | Description |
|---|---|---|---|
| title* | React.ReactNode |  | The heading. Any node; a string is the usual case. |
| actions | React.ReactNode |  | Buttons at the end of the row, 8 px apart, wrapping when there is no room. Any node, usually one or two `Button` elements. |
| align | "start" \| "center" | "start" | Where the title and description sit: `start` (default) or `center`. |
| as | "h1" \| "h2" \| "h3" |  | The heading element: `h1`, `h2` or `h3`. It changes the element, not the size. Default `h1` for the page level and `h2` for the section level. |
| className | string |  | Extra classes for the container (the element the container query measures), for example `max-w-2xl`, `w-80` or `mb-8`. |
| description | React.ReactNode |  | One line of context under the title, in secondary text. Any node. Without it nothing is rendered. |
| href | string | "#" | Where `link` goes. Default `#`. |
| level | "page" \| "section" \| "form" | "page" | `page` is the 30 px title of a view, `section` a 16 px heading, `form` a 24 px bold title with a 14 px description for the top of a sign-in, sign-up or onboarding form. `page` by default. |
| link | React.ReactNode |  | The label of a text link at the end of the row. Any node. Without it no link is rendered. |
| onLinkClick | React.MouseEventHandler<HTMLAnchorElement> |  | Called when the link is clicked. The default action is not prevented. |

### AuthHeading

| Prop | Type | Default | Description |
|---|---|---|---|
| title* | React.ReactNode |  |  |
| align | "start" \| "center" | "start" |  |
| as | "h1" \| "h2" \| "h3" |  | The heading element: h1 on an auth page, a lower level when the heading sits inside a larger page. Looks the same either way. |
| className | string |  |  |
| subtitle | React.ReactNode |  |  |

## Examples

### Level: page title or section heading

### Trailing: nothing, a link, one button or two

### Content: long title, long description and a narrow container

### Form heading: the title and description above a form

## In context

### Settings page: breadcrumb, header and a field that turns Save on

The breadcrumb sits above the header, not in it. Discard and Save changes stay off until the name changes; Save says what happened in a status line and Discard puts the name back.

### Orders page: a page header and a section header with a link

The page header holds the title and one button. The section header below carries a View all link and stays in every list state, so the page keeps its shape.

## For AI agents

`get_component("page-header")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
