Skip to content
Nexus Application Design nadesign

PageHeader

<PageHeader> is the foundational page-bar primitive. Line 1 = leading + title (left) and actions (right). Line 2 = optional children (subtitle, tabs, filters). Sits ABOVE the scrolling PageContent and never scrolls itself.

import from "@na/ui/components/PageHeader" ▶ Open in Storybook packages/ui/src/components/PageHeader.tsx

When to use

  • Every routed page that’s not a Focus / wizard layout.
  • Foundation for higher-level page bars: ListPageBar, DetailPageBar.

Don’t use PageHeader for: focus / wizard flows (FocusLayout has its own header), section-internal headings (ContentSection), or modal / sheet titles (use the matching component’s own title slot).

With actions

Marketing Bot

Body content…
 
<PageHeader
  title="Marketing Bot"
  actions={
    <>
      <Button variant="outline" size="sm">Cancel</Button>
      <Button size="sm">Save</Button>
    </>
  }
/>

With subtitle

Run #abc123

Started 2 minutes ago · 12 calls processed

Body…
 
<PageHeader title="Run #abc123">
  <p className="text-muted-foreground py-1 text-xs">
    Started 2 minutes ago · 12 calls processed
  </p>
</PageHeader>

API

Prop Type Default Description
title * ReactNode — Page title. String → rendered inside <H3>. ReactNode → rendered as-is for composed titles.
leading ReactNode — Left-side element before the title (back button, sidebar trigger).
actions ReactNode — Right-aligned action buttons.
children ReactNode — Second-line content. Tabs, subtitle, search, filter chips.

Design guidelines

✓ Do

  • Use ListPageBar / DetailPageBar when they fit — they wire leading affordances correctly.
  • Keep title plus actions short — long titles truncate at max-w-64 by design.
  • Cap actions at 2–3 buttons. More belongs in a DropdownMenu next to the primary.

✗ Don't

  • Render PageHeader inside PageContent. The header sits above; the content scrolls below.
  • Use PageHeader for section headings inside a page — that's ContentSection.

Accessibility

  • <H3> automatically renders the title when string. For ReactNode titles, the consumer owns heading semantics.
  • The wrapper is a plain <div> — pair with <main> or <header> semantics in the surrounding layout.
  • ListPageBar — Wraps PageHeader with the SidebarTrigger for list pages.
  • DetailPageBar — Wraps PageHeader with back button + tabs for detail pages.
  • PageContent — The scrolling region below.

▶ Open PageHeader stories in Storybook