Page Header

A page-level header with title and optional description.

Installation

$
npx shadcn@latest add https://ui.mattdowney.com/r/page-header.json

Usage

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

PropTypeDefaultDescription
title*ReactNodeNoneThe page title. A string, or inline content such as <code> or a link; it renders inside the heading, so keep it to phrasing content.
descriptionReactNodeNoneOptional 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.
eyebrowReactNodeNoneA 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.
metaReactNodeNoneOne 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).
actionReactNodeNoneA 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.
titleClassNamestringNoneThe 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 | 61Heading level. A page has one h1; a section-level header should pass level={2}.
childrenReactNodeNoneContent 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.