Page Header
ProThe title row at the top of a page or section, with a line of context and, at the end, buttons or a text link.
Playground
Workspace settings
Manage members, billing and integrations for WunderUI.
Workspace settings
Manage members, billing and integrations for WunderUI.
Workspace settings
Manage members, billing and integrations for WunderUI.
Workspace settings
Manage members, billing and integrations for WunderUI.
Team members
6 people have access to WunderUI.
Team members
6 people have access to WunderUI.
Team members
6 people have access to WunderUI.
Team members
6 people have access to WunderUI.
Installation
Page Header comes with WunderUI Core and Pro, in the package from your plan. See the plans.
Then import what you need:
import { PageHeader, AuthHeading, PageHeaderProps } from "@wunderui/react"Then use it:
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 for
- Settings Row for one setting with its label, its description and its control
- Card for a titled surface that holds content, with its own header
Level
The page level is the one title of a view: 30 px, bold, an h1. The section level heads a part of the page: 16 px, semibold, an h2, and both take a description.
Workspace settings
Manage members, billing and integrations for WunderUI.
Team members
6 people have access to WunderUI.
Trailing
Actions holds your buttons, plain first and the call to action last. The link is one text action such as View all, centred on a section title.
Team members
6 people have access to WunderUI.
Team members
6 people have access to WunderUI.
Team members
6 people have access to WunderUI.
Team members
6 people have access to WunderUI.
Long content
A long title and description wrap and nothing is cut off. The row stacks by the width of its own container, below 40rem, so a header in a narrow side panel puts the actions under the text.
Content
Workspace settings
Manage members, billing and integrations for WunderUI.
Quarterly revenue, churn and customer growth across all regions and plans
Manage members, billing and integrations for WunderUI.
Workspace settings
Every figure is calculated from invoices that were paid between July 1 and September 30, in US dollars, and excludes refunds, credits and test payments.
Workspace settings
Manage members, billing and integrations for WunderUI.
Form heading
level="form" is the top of a sign-in, sign-up or onboarding form: a 24 px bold title with a 14 px description below, an h1 by default. align="center" centres both for a card, start keeps them on the left of a split layout. It replaces AuthHeading, whose subtitle is the description here.
Create your account
Start with your work email. You can invite your team later.
Create your account
Start with your work email. You can invite your team later.
Keyboard interactions
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.
- TaborShift+Tab
- Moves between the buttons of in reading order and to the . 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 and motion
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
The figure shows a page header with one button and a link. Actions and link are separate props and both render when both are set; most headers use one.
Workspace settings
Manage members, billing and integrations for WunderUI.
- 1data-slot="page-header"
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.
- 2
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.
- 3Optional
A 14 px paragraph in secondary text, 4 px under the title. It takes any node and wraps.
- 4Optional
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.
- 5Optional
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.
- Optional
Best practices
- 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.
- Do
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.
- Do
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.
- Do
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
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
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 is a plain component, so this table lists every prop. It does not pass other props on to its element.
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| title required | ReactNode | — | The heading. Any node; a string is the usual case. |
| description | ReactNode | — | One line of context under the title, in secondary text. Any node. Without it nothing is rendered. |
| level | "page" | "section" | "form" | "page" | is the 30 px title of a view, a 16 px heading, a 24 px bold title with a 14 px description for the top of a sign-in, sign-up or onboarding form. by default. |
| align | "start" | "center" | "start" | Where the title and description sit: (default) or . |
| as | "h1" | "h2" | "h3" | — | The heading element: , or . It changes the element, not the size. Default for the page level and for the section level. |
| actions | ReactNode | — | Buttons at the end of the row, 8 px apart, wrapping when there is no room. Any node, usually one or two elements. |
| link | ReactNode | — | The label of a text link at the end of the row. Any node. Without it no link is rendered. |
| href | string | "#" | Where goes. Default . |
| onLinkClick | MouseEventHandler<HTMLAnchorElement> | — | Called when the link is clicked. The default action is not prevented. |
| className | string | — | Extra classes for the container (the element the container query measures), for example , or . |
| Prop | Type | Default | Description |
|---|---|---|---|
| title required | 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. |
| subtitle | ReactNode | — |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("page-header")The full library index for assistants is at /llms.txt.