build69
build69  /  Components  /  Page Structure  /  PageHead

PageHead

v1.0.18Updated 19 Oct 2026

In-page header with title, breadcrumb, subtitle, status badge, and action buttons. Sits just below the global Topbar.

View source← Back to catalog

Preview

Live · 14 stories
DefaultOpen ↗
▸Why this is recommendedheaderpagetitlebreadcrumb+5

The default, out-of-the-box PageHead.

Recommended for+14
  • ✓Every content page inside AppShell
  • ✓Detail pages that need status chips beside the title
  • ✓Headers whose subtitle must stay fully readable without a click (descriptionClamp={false})
  • ✓Pages with more actions than fit, which should collapse into an overflow menu
Tags+6
headerpagetitlebreadcrumbsubnavactionsstickyeditabledefault
Features+4
  • Breadcrumb trail above the title
  • Client-side routing: pass `linkComponent` (next/link, React Router Link) and every row that has an href renders through the host app link component instead of a plain anchor, which would reload the whole document (fb_bf7dc63a), breadcrumb crumbs included; PageHeadBreadcrumbItem gains an event-carrying onClick so a host can preventDefault and route itself
  • Title as ReactNode, or inline-editable via `editable` + `onTitleChange`
  • Status / meta chips via `tags`
  • Description with configurable clamp — `descriptionClamp` lines, or false for the whole text with no toggle
  • Action cluster: an arbitrary `actions` node, or structured `actionItems` that collapse into an overflow menu past `maxVisibleActions`
  • Optional `subnav` row beneath the header
  • `sticky` pins the header while the page scrolls
  • i18n: labels prop overrides every built-in UI string (breadcrumb/subnav aria, Show more/less, overflow + editable-title aria) — see PageHeadLabels / DEFAULT_PAGE_HEAD_LABELS
Not recommended for−2
  • ✕Inside dialogs / sheets (use DialogHeader / SheetHeader)

Install

Ask your agent, or call the MCP tool directly. The resolved bundle is written into your project.

get_registry_item({ name: "PageHead" })

Usage

import { PageHead } from '@/components/patterns/page-head';

<PageHead
  title={<>Invoices <span className="font-mono text-muted-foreground">QT-2026-0140</span></>}
  description="Every reference here has to stay readable without a click."
  descriptionClamp={false}
  tags={[{ id: 'draft', label: 'Draft' }]}
  actions={<Button>New</Button>}
/>

Tick variants in the left menu — each adds a tab with that variant’s real story source, the same code the preview above renders.

Props

PropTypeRequired
flush

Drop the head's own horizontal and vertical padding, for a page that already pads its content. `className` lands on the OUTER wrapper, so the inner row's px-6 was unreachable and the title sat 24px right of everything beneath it; hosts were reaching in with [&>div]:px-0 (fb_780b4ee6).

boolean—
title

Page title. Any node, so a code chip or badge can sit inline.

React.ReactNodeyes
breadcrumb

Trail rendered above the title.

ReadonlyArray<PageHeadBreadcrumbItem>—
tags

Status / meta chips beside the title.

ReadonlyArray<PageHeadTag>—
description

Subtitle below the title.

React.ReactNode—
descriptionClamp

Lines to clamp the description to before offering "Show more"; false shows it all with no toggle. Defaults to 1.

number | false—
descriptionClassName

Extra classes on the description, e.g. max-w-none to opt out of its max-w-2xl measure.

string—
actions

Arbitrary action cluster. Children must be single-row controls — the row is vertically centred.

React.ReactNode—
actionItems

Structured actions; collapse into an overflow menu past maxVisibleActions. Preferred over `actions`.

ReadonlyArray<PageHeadAction>—
maxVisibleActions

How many actionItems show before the rest collapse. Defaults to 3.

number—
sticky

Pin the header while the page scrolls.

boolean—
editable

Make the title inline-editable; pair with onTitleChange.

boolean—
onTitleChange

Called when an editable title is committed.

(value: string) => void—
subnav

Nav row beneath the header.

ReadonlyArray<PageHeadSubnavItem>—
activeSubnavId

Which subnav item is current.

string—
onSubnavChange

Called when a subnav item is chosen.

(id: string) => void—
labels

Override any built-in UI string — breadcrumb/subnav aria, Show more/less, overflow + editable-title aria (i18n). Merged over DEFAULT_PAGE_HEAD_LABELS.

Partial<PageHeadLabels>—
linkComponent

The host app link component for every breadcrumb that has an href (next/link, React Router Link). Defaults to a plain anchor, which in a routed app reloads the whole document, loses client state, and does nothing at all when the click lands before hydration. Crumbs carry data-slot="page-breadcrumb-link". PageHeadBreadcrumbItem.onClick receives the click EVENT so a host can preventDefault and route itself. MCP feedback fb_bf7dc63a.

PageHeadLinkComponent—

Related

Platform docsAll componentsSource files