Page Header
A page-level header with title and optional description.
Installation
npx shadcn@latest add https://ui.mattdowney.com/r/page-header.jsonUsage
import { PageHeader } from "@/components/ui/page-header"Examples
Default
The title and description at the top of a page. It ships no bottom margin: put it in a Stack and let the container own the gap to whatever follows.
Dashboard
Overview of your workspace
Centred
A masthead for a page you browse, a blog or a shop, with nothing beside it. A centred heading takes no action; one with a call to action is a Lockup.
Signals
Notes on design, building with AI, and what is worth your attention this week.
Display headline
An article or essay masthead: the title at the display size over a lead-size summary. Bring your own headline face with titleClassName, never a size: the gap under the title is measured against it.
Shipping a design system your agents can read
What changed when the rules moved out of a wiki and into the repo the agents work in.
Eyebrow and meta
eyebrow names the series above the title; meta holds a date, byline or reading time between the title and the description. Both sit on the group's own gap, so a masthead sets no spacing.
Issue 42
Shipping a design system your agents can read
Oct 20 · 6 min read
What changed when the rules moved out of a wiki and into the repo the agents work in.
With an action
A control seated on the heading's right, for the one control the section is about: a view switcher, a range picker. When the row gets narrow, the control drops under the description. Filters and table-wide actions are a different row and belong in TableToolbar below.
Subscriber growth
Signups over the last 30 days.
Action on a phone
Under a 32rem header the action always drops under the title and description, whatever its width, so a short button never squeezes a long title into a narrow column. Above that it sits beside the title as before.
weekly-report-writer
Turns a week of notes into a short status update for your team.
API Reference
| Prop | Type | Default | Description |
|---|---|---|---|
| title* | ReactNode | None | The page title. A string, or inline content such as <code> or a link; it renders inside the heading, so keep it to phrasing content. |
| description | ReactNode | None | Optional supporting text below the title. A string, or inline content such as <code> or a link; it renders inside a <p>, so keep it to phrasing content. |
| eyebrow | ReactNode | None | A short label above the title that names the section or series. Its case, tracking and weight read the same --eyebrow-* tokens as LockupEyebrow, and it steps with size (11px at sm and md, 12px at lg and display). For a page or section intro, never every heading. |
| meta | ReactNode | None | One small muted line between the title and the description: a date, a byline, a reading time, a sample size. Tabular figures. Steps with size (11, 12, 13 and 14px). |
| action | ReactNode | None | A control seated on the heading's right, centred on the title's first line. Beside the title it adds no height, so the gap to children is the same with or without one; wrapped under the title it takes its own space. Under a 32rem header (a phone) it always wraps under. For the one control the section is about; filters and table-wide actions belong in TableToolbar under the heading instead. |
| align | "start" | "center" | "start" | center centres the title and description. It cannot take an action. |
| size | "sm" | "md" | "lg" | "xl" | "display" | "lg" | Ramp keyed to the type scale. sm: title text-sm, description text-1xs, 20px below. md: title text-lg, description text-base, 24px below. lg: title text-2xl, description text-base, 32px below. xl: title text-3xl, description text-base, 32px below, for a docs page or help article. display: title text-display, description text-lg, 40px below, and an inside gap of 8px plus a quarter of the title (17px at 36px). At every size the description caps at the reading measure (60ch). The below gap only applies when children are present. |
| titleClassName | string | None | The title's face: a project's own headline family, weight, tracking or leading. Never its size, which comes from size (retune --text-display for display), because the gap under the title is measured against it. |
| level | 1 | 2 | 3 | 4 | 5 | 6 | 1 | Heading level. A page has one h1; a section-level header should pass level={2}. |
| children | ReactNode | None | Content below the heading group. When present, PageHeader renders as a flex column and owns the gap between the group and this content via the size's below-gap token. |
title*ReactNodeThe page title. A string, or inline content such as <code> or a link; it renders inside the heading, so keep it to phrasing content. |
descriptionReactNodeOptional supporting text below the title. A string, or inline content such as <code> or a link; it renders inside a <p>, so keep it to phrasing content. |
eyebrowReactNodeA short label above the title that names the section or series. Its case, tracking and weight read the same --eyebrow-* tokens as LockupEyebrow, and it steps with size (11px at sm and md, 12px at lg and display). For a page or section intro, never every heading. |
metaReactNodeOne small muted line between the title and the description: a date, a byline, a reading time, a sample size. Tabular figures. Steps with size (11, 12, 13 and 14px). |
actionReactNodeA control seated on the heading's right, centred on the title's first line. Beside the title it adds no height, so the gap to children is the same with or without one; wrapped under the title it takes its own space. Under a 32rem header (a phone) it always wraps under. For the one control the section is about; filters and table-wide actions belong in TableToolbar under the heading instead. |
align"start" | "center" = "start"center centres the title and description. It cannot take an action. |
size"sm" | "md" | "lg" | "xl" | "display" = "lg"Ramp keyed to the type scale. sm: title text-sm, description text-1xs, 20px below. md: title text-lg, description text-base, 24px below. lg: title text-2xl, description text-base, 32px below. xl: title text-3xl, description text-base, 32px below, for a docs page or help article. display: title text-display, description text-lg, 40px below, and an inside gap of 8px plus a quarter of the title (17px at 36px). At every size the description caps at the reading measure (60ch). The below gap only applies when children are present. |
titleClassNamestringThe title's face: a project's own headline family, weight, tracking or leading. Never its size, which comes from size (retune --text-display for display), because the gap under the title is measured against it. |
level1 | 2 | 3 | 4 | 5 | 6 = 1Heading level. A page has one h1; a section-level header should pass level={2}. |
| childrenReactNodeContent below the heading group. When present, PageHeader renders as a flex column and owns the gap between the group and this content via the size's below-gap token. |
import { cn } from "@/registry/lib/utils"
const PAGE_HEADER_SIZE = {
sm: {
title: "text-sm",
description: "text-1xs",
eyebrow: "text-2xs",
meta: "text-2xs",
inside: "var(--spacing-rhythm-trim-pair)",
below: "var(--spacing-rhythm-heading-sm)",
},
md: {
title: "text-lg",
description: "text-base",
eyebrow: "text-2xs",
meta: "text-1xs",
inside: "var(--spacing-rhythm-trim-pair)",
below: "var(--spacing-rhythm-heading-md)",
},
lg: {
title: "text-2xl",
description: "text-base",
eyebrow: "text-1xs",
meta: "text-xs",
inside: "var(--spacing-rhythm-trim-pair)",
below: "var(--spacing-rhythm-heading-lg)",
},
// A reference page's title: a docs page, a help article, a long settings
// page someone reads top to bottom. One type step above `lg`. The below gap stays on the `lg`
// rung: 32px already beats a 16px description's line spacing by a wide
// margin, and only a masthead earns the 40px `display` takes.
xl: {
title: "text-3xl",
description: "text-base",
eyebrow: "text-1xs",
meta: "text-sm",
inside: "var(--spacing-rhythm-trim-pair)",
below: "var(--spacing-rhythm-heading-lg)",
},
// A display headline: an article's or an essay's masthead, set at the
// display size with a lead-size description under it. The inside gap is the
// one rung on this ramp written in `em`, because the descender it has to
// clear is a fraction of the title's own size (0.254em on Geist) and the
// flat 12px under a 36px title reads cramped. `em` resolves where the gap
// is applied, so the group carries the title's font-size and the rung
// measures against the title, not the body. 12px at 16px, 17px at 36px.
display: {
title: "text-display",
description: "text-lg",
eyebrow: "text-1xs",
meta: "text-sm",
inside: "var(--spacing-rhythm-trim-pair-display)",
below: "var(--spacing-rhythm-heading-display)",
},
} as const
type PageHeaderSize = keyof typeof PAGE_HEADER_SIZE
interface PageHeaderBaseProps extends Omit<React.ComponentProps<"div">, "children" | "title"> {
/** Text, or inline content such as `<code>` or a link. It renders inside
* the heading element, so keep it phrasing content. */
title: React.ReactNode
/** Text, or inline content such as `<code>` or a link. It renders inside a
* `<p>`, so keep it phrasing content. */
description?: React.ReactNode
/** A short label above the title that names the section or series. Caps
* and tracking read the same `--eyebrow-*` tokens as `LockupEyebrow`.
* Use it on a page or section intro, never on every heading. */
eyebrow?: React.ReactNode
/** One small line between the title and the description: a date, a byline,
* a reading time, a sample size. Muted, with tabular figures. */
meta?: React.ReactNode
size?: PageHeaderSize
/** Which heading element renders, `1` to `6`. Defaults to `1`. */
level?: 1 | 2 | 3 | 4 | 5 | 6
/** The title's face, for a project that brings its own headline style (a
* display family, a heavier weight, its own tracking or leading). Never its
* size: the size comes from `size`, and at `display` the inside gap is
* measured against it, so a size set here would leave the gap behind.
* Retune `--text-display` in `:root` to change the display size. */
titleClassName?: string
/** @deprecated Use `level`. */
as?: "h1" | "h2" | "h3"
children?: React.ReactNode
}
type PageHeaderProps = PageHeaderBaseProps &
(
| {
/** `start` (default) or `center`. Centre a masthead that opens a page
* you browse, a blog or a shop, with nothing beside it. */
align?: "start"
/** A control that belongs TO this heading, seated on its right: a view
* switcher, a range picker, the one action the section is for. Filters and
* table-wide actions are a different row and belong in `TableToolbar` under
* the heading, bound to the thing they scope rather than to the title. */
action?: React.ReactNode
}
| {
/** A centred heading takes no action: a call to action under a
* centred title is a `Lockup`. */
align: "center"
action?: never
}
)
// @use-when a heading group: a title with an optional line of description, for
// a page that is read. `align="center"` for a browse page's masthead with no
// action (a blog, a shop). `size="display"` for an article or essay masthead
// with a display headline. `size="xl"` for a reference page's title, a docs
// page or a help article, whose description is real prose. `eyebrow` for a
// label above the title, `meta` for a date, byline or reading time between
// title and description. Not PageTitleRow, which is an app page's title bar
// with controls, and not Lockup, which is a heading, text and call to action.
export function PageHeader({
title,
description,
eyebrow,
meta,
size = "lg",
align = "start",
level: levelProp,
as,
titleClassName,
action,
className,
style,
children,
...props
}: PageHeaderProps) {
const scale = PAGE_HEADER_SIZE[size]
const level = levelProp ?? (as ? (Number(as.slice(1)) as 1 | 2 | 3) : 1)
const Heading = `h${level}` as "h1" | "h2" | "h3" | "h4" | "h5" | "h6"
const group = (
<div
// A huge grow and `min-w-0` only under an action, so the group claims the
// row and pushes the control to the far edge (the action box below grows
// too, by a sliver, which is how it tells beside from wrapped), and so a long title wraps instead
// of shoving the control off the end. `basis-60` is the narrowest the
// group may get beside the control: below 240px a title breaks every
// word or two, so the row wraps and the control drops under the
// description, left-aligned, the way page headers stack on a phone.
// A wrap, not a breakpoint: it answers to the header's own width, which
// a viewport query cannot see in a sidebar or a split pane. Without an
// action the wrapper is the whole header and none of this is wanted.
// Under a 32rem header (`@max-lg`, a phone, a narrow pane) the group
// takes the full row, so the action ALWAYS drops under it. The basis
// alone let a narrow control (a "Manage" button) stay beside a long
// title and squeeze title and description to 240px, while a wide one
// wrapped under: two pages, two behaviours, decided by a label's
// length. A container query, not a viewport one, for the reason above.
// Centred, the description takes the reading measure: a centred line
// has no edge to return to, so a long one is hard to follow.
// At `display` the group takes the title's font-size too, so the inside
// rung's `em` resolves against the title; the description sets its own.
className={cn(
"flex flex-col",
size === "display" && "text-(length:--text-display)",
action && "min-w-0 basis-60 @max-lg/page-header:basis-full",
align === "center" && "items-center text-center"
)}
style={{ gap: scale.inside, flexGrow: action ? 9999 : undefined }}
>
{eyebrow && (
<p
data-slot="page-header-eyebrow"
className={cn(
scale.eyebrow,
"[text-transform:var(--eyebrow-case)] tracking-(--eyebrow-tracking) font-(--eyebrow-weight) text-muted-foreground"
)}
>
{eyebrow}
</p>
)}
<Heading
className={cn(
scale.title,
size !== "display" && "leading-snug",
"cap-trim font-medium text-pretty break-words",
titleClassName
)}
>
{title}
</Heading>
{meta && (
<p
data-slot="page-header-meta"
className={cn(scale.meta, "text-muted-foreground tabular-nums text-pretty")}
>
{meta}
</p>
)}
{description && (
<p
className={cn(
scale.description,
// Every size caps the description at the reading measure. It was
// capped only at xl, display and centred, on the guess that an lg
// or md description is one short line; on a wide page it was two
// or three lines run edge to edge. A line under 60ch is unchanged.
"max-w-measure leading-normal text-muted-foreground text-pretty break-words"
)}
>
{description}
</p>
)}
</div>
)
// The action must not set the gap below the title. A 32px control is taller
// than a trimmed md or sm title, so letting it size the row measured the gap
// to `children` from the control's foot and every section with an action sat
// ~18px lower than one without. So beside the title the control adds NO
// height: it centres on the title's first cap band (a `1cap` sizer in the
// title's own type size) and overhangs it evenly, about 11px each way, which
// every `below` rung clears.
//
// Wrapped under the title it must take its own space again, and a flex line
// cannot tell those two cases apart by itself, so the slot measures it: the
// group grows ~10000x faster than the action, so beside the title the action
// box is its own width plus a sliver, and alone on its line it fills the
// row. The row is an inline-size container, so `100cqi` is the row and the
// slot's `%` margins resolve against the action box. Their difference is
// zero only when wrapped; scaled and clamped it gives a -999px margin beside
// the title (the box contributes nothing to the row) and 0 under it (the box
// is its full height). The half pixel absorbs layout rounding.
//
// `items-start` keeps the action box's top on the cap top, so the cap band
// the sizer reproduces is the title's own. The row gap is the `cluster` rung
// in its arbitrary-property form, so it stays a real `var()`; a numbered
// utility would freeze the length at compile time.
const head = action ? (
<div className="@container/page-header flex flex-wrap items-start gap-(--spacing-rhythm-cluster)">
{group}
<div className="grid min-w-0" style={{ flexGrow: 1 }}>
<span aria-hidden className={cn(scale.title, "[grid-area:1/1]")} style={{ height: "1cap" }} />
<div
data-slot="page-header-action"
className="[grid-area:1/1] self-center justify-self-start"
style={{ marginBlock: "clamp(-999px, (100% - 100cqi + 0.5px) * 1000, 0px)" }}
>
{action}
</div>
</div>
</div>
) : (
group
)
// With an action the head row is a size container, and a size container
// has no width of its own: inside a centring or shrinking flex parent it
// collapsed to nothing and set the title one letter per line. `w-full` on
// both roots gives it the parent's width to measure.
if (!children) {
return (
<div data-slot="page-header" className={cn(action && "w-full", className)} style={style} {...props}>
{head}
</div>
)
}
return (
<div
data-slot="page-header"
className={cn("flex flex-col", action && "w-full", className)}
style={{ ...style, gap: scale.below }}
{...props}
>
{head}
{children}
</div>
)
}
// Gap below the heading group is set via inline style reading the token, not a
// gap-* class: Tailwind inlines spacing utility values at compile time, so a
// class would freeze the length and a dial or token override could never reach
// it (same reason registry/ui/stack.tsx applies its gap this way).
//
// The title carries `cap-trim` and the group therefore reads
// `--spacing-rhythm-trim-pair`, NOT `--spacing-rhythm-pair`. Those two rungs
// exist because a trimmed box and an untrimmed one need different numbers to
// paint a comparable gap: trimming removes the half-leading a plain text box
// supplies on both sides, so the token has to state outright what it used to
// inherit, and it also measures the bottom edge at the BASELINE, so a descender
// in the title paints into the gap. See stack.tsx for the full derivation of
// the 12px. `display` reads `trim-pair-display` instead, the same derivation
// written in the title's own `em` (8px plus a quarter of the title), since the
// descender grows with the type.
//
// `eyebrow` and `meta` sit in the same group on the same `inside` rung, so
// every line touching the trimmed title is spaced by a trim rung. Neither
// needs a rung of its own: the trim already removed the title's dead space on
// both sides, and the small untrimmed lines bring their own. The description
// is larger type with more dead space above it, so with one shared gap the
// meta line still reads closer to the title than to the description.
//
// The pairing is the invariant: `cap-trim` on
// the heading and a `trim-pair` rung on its container always travel together, and `verify-ui`'s
// `trim-rung-mismatch` rule fails the build if one appears without the other.
export { PAGE_HEADER_SIZE, type PageHeaderSize }