Page header
The top of an app page, with its title, an optional value and the page's actions.
A page header is the top of an app page: breadcrumbs when the page is nested, the title with an optional badge or value, one line about the page, and the page's actions at the end. Use PageHeader on every app page, so pages read the same way from one to the next.
The page grammar
Every page in an app shell follows one order, from the top:
- Breadcrumbs, only on a nested page.
- The title and its actions, one of them primary.
- A one-line description.
- Tabs and filters.
- The page's content.
PageHeader builds the top of it. When its actions don't fit, they fold into a "More page actions" menu.
This header shows a count, with what it counts behind an info button, and two actions. priority={1} keeps New order, the primary action, in the row after Export has folded away.
import type { ReactElement } from "react";
import { Download, Plus } from "lucide-react";
import { PageHeader } from "@butteryui/react";
export function OrdersHeader(): ReactElement {
return (
<PageHeader
title="Orders"
value="1,284"
valueInfo="Orders placed in the last 30 days."
actions={
<>
<PageHeader.Action
icon={Download}
label="Export"
onSelect={() => undefined}
/>
<PageHeader.Action
variant="primary"
icon={Plus}
label="New order"
priority={1}
onSelect={() => undefined}
/>
</>
}
/>
);
}PageHeader
When to use it
Use it for
- The top of every app page: its title, a headline figure and its actions
- Over a page's Tabs and QuickActions, which go in as its children
Not for
- A marketing page's opening: use SplitHero or CenteredHero
- The app's top bar with search: use TopBar
Examples
Bags this week
A header whose value comes from state: each batch added puts 12 more bags in the week.
Roasts
148 bagsPlan the week's batches by coffee and by day.
Header with tabs
A header with its tabs and quick actions under it, 16px apart, over the tab's panel.
Subscriptions
312312 subscriptions on 2 plans
Orders header
An orders page's header: the count after the title, and New order as the main action with its key, N.
Orders
1,284Last: Nothing yet
Variants and states
Title, value and actions
Narrow the page: the actions fold into … before the title truncates, the primary one last.
Orders
1,284Props
PageHeader
| Prop | Type | Default | Description |
|---|---|---|---|
titlerequired | string | The page's title, its h1. Long titles truncate once the actions have folded away. | |
breadcrumbs | ReactNode | The trail of pages above this one, a Breadcrumbs, over the title. Only a nested page has one. | |
badge | ReactNode | A ScopeBadge after the title, saying what the page's settings apply to. | |
description | ReactNode | One line under the title's row saying what the page is for, in body and text-secondary. | |
value | ReactNode | A figure after the title, such as a count or a balance, in the title's size at regular weight. | |
valueInfo | string | What the value means, behind an InfoButton after it: a tooltip on hover and focus, a popover on a press or a tap. | |
actions | ReactNode | The page's actions at the end of the row: PageHeader.Actions, which fold into "…" when they don't fit. | |
moreLabel | string | "More page actions" | Names the button that lists the actions that don't fit. Defaults to "More page actions". |
children | ReactNode | Rows under the header, 16px apart, such as Tabs or QuickActions. |
It also takes Omit<ComponentPropsWithRef<"div">, "title">.
PageHeader.Action
| Prop | Type | Default | Description |
|---|---|---|---|
labelrequired | string | What it does, such as "Export". The row shows it as text unless iconOnly; the menu always does. | |
onSelectrequired | () => void | Runs the action, from the row or from the "…" menu. | |
icon | ComponentType<IconComponentProps> | An icon for it: before the label, alone with iconOnly, and in the menu. | |
iconOnly | boolean | Shows only the icon, with the label as its tooltip and name. Needs icon. | |
variant | Extract<ButtonVariant, "primary" | "secondary"> | "secondary" | "secondary" (the default) or "primary" for the page's one main action. |
shortcut | Shortcut | A shortcut for it, written as useShortcut takes it, such as "n": shown after the label (and in the "…" menu) and bound while the action can run. | |
disabled | boolean | Keeps it from being chosen; its button stays focusable (aria-disabled). | |
priority | number | 0 | Higher stays in the row longer. Defaults to 0; give the primary action the highest. |
Accessibility
The title is the page's h1. The info button is named by the explanation, which its tooltip shows and a press opens in a popover. Actions are buttons; a disabled one stays focusable, and those folded into the menu stay reachable from the More page actions button. An action's shortcut is bound, and announced through aria-keyshortcuts in the row and in the menu. Breadcrumbs go before the h1 as their own navigation landmark; a scope badge is a button after the title; the description is a paragraph under the title's row.
| Keys | What they do |
|---|---|
| Enter or Space | Runs the focused action, opens the value's explanation from its info button, or opens More page actions with the actions that don't fit |
| An action's shortcut, such as N | Runs that action from anywhere on the page, unless it's disabled or focus is in a text field, a menu or a modal dialog |
| Arrow keys | Move through More page actions while it's open |
| Escape | Closes More page actions or the value's explanation |
Motion
It doesn't move.
With reduced motion: Nothing changes.
Layout
It takes its container's width. The title's row is at least 36px tall with the actions at its end, 8px apart; as it narrows the actions fold into More page actions, the lowest priority first, and only then does the title truncate, with its full text in its title. The value keeps its width in tabular figures, the description wraps under the row, and rows passed as children sit 16px below.
Related
See it in the roastery demo's customers, orders, overview, payouts, roast plan, settings, stock, subscriptions and wholesale.
Related
- App shell
The frame of a whole app, as an editor or a dashboard, and the page that goes in it.
- Breadcrumbs
The trail of pages above a nested page, as links above its title.