Install

pnpm exec vegastack-design verify page-header

pnpm dlx shadcn@4.21.0 add @vegastack/page-header

Usage

import { PageHeader } from "@/components/ui/page-header";
import { Button } from "@/components/ui/button";

<PageHeader
  title="Spaces"
  description="Organize work into shared spaces."
  actions={<Button>New space</Button>}
/>;

PageHeader is presentational — it owns layout, not behavior. You pass navigation (backHref / onBack), the breadcrumb node, right-side actions and secondaryMenu slots, and a favorite config; the host owns routing and persistence.

The registry component is client-rendered because it includes the optional favorite toggle and imperative onBack button path. Prefer backHref for URL-backed navigation; use onBack only for app-local behavior such as closing a picker or returning to a non-URL state.

Anatomy

PageHeader lays out, top to bottom, an optional breadcrumb row, then a title row split into a left title block (back button, <h1>, favorite star, description) and a right actions block (actions + secondary menu), then the tabs row (tabs), followed by any children. Every region exposes a data-slot for styling and testing:

<PageHeader
  backHref="/settings" // ← page-header-back   (<a>, ChevronLeft)
  breadcrumb={<Breadcrumb>…</Breadcrumb>} // ← page-header-breadcrumb
  title="API Keys" // ← page-header-title  (<h1>)
  description="Manage keys." // ← page-header-description
  favorite={{ defaultActive: true }} // ← page-header-favorite (Star toggle)
  actions={<Button>Create key</Button>} // ← page-header-actions
  secondaryMenu={<DropdownMenu>…</DropdownMenu>}
>
  {/* children render below the header row */}
</PageHeader>

• page-header — the root container (<header>, vertical stack). A banner landmark when PageHeader sits at the top of the page — not nested inside <article> / <aside> / <main> / <nav> / <section>.
• page-header-breadcrumb — wraps the breadcrumb node above the title row. Omitted when no breadcrumb.
• page-header-back — the back affordance: the backRender element (your framework link) or an <a> when backHref is set, each with a ChevronLeft; a button when onBack is set. Omitted when none is set.
• page-header-title — the page <h1>. The title text itself routes through TruncatedText (data-slot="truncated-text", nested inside the <h1>), so an overlong tenant/workspace title clips with an ellipsis instead of overflowing the header row, and reveals in full via a tooltip on hover/focus. The <h1> stays the accessible heading — TruncatedText composes inside it, never replaces it.
• page-header-favorite — the star toggle. Sets aria-pressed and data-active. Omitted when no favorite.
• page-header-description — the muted description under the title. Omitted when no description.
• page-header-meta — the muted metadata row under the description, a <div> that can hold controls. Omitted when no meta.
• page-header-actions — the right-aligned slot holding actions then secondaryMenu. Omitted when both are empty.
• page-header-tabs — the row holding tabs, 24px under the title and, when it ends a header placed directly in an AppShellPage, 12px above the page below (the same rhythm as a ListToolbar's tabs row, so every page reads title → tabs → content alike). Omitted when empty.

Examples

Minimal

The only required prop is title. With nothing else, PageHeader renders just the <h1> — every other slot (back button, breadcrumb, description, favorite, actions) is opt-in:

<PageHeader title="Profile" />

With breadcrumb, back button, and actions

A back button (rendered as a link via backHref), a full breadcrumb trail, a description, and two actions on the right:

Back navigation

Pass backHref for URL-backed navigation (renders an <a>) or onBack for an app-specific imperative action (renders a <button>). The two render different elements; onBack takes precedence when both are set. The preview below uses onBack, so the back affordance is a real <button>:

// Link — renders an <a>
<PageHeader title="Select plan" backHref="/billing" />

// Imperative app action — renders a <button>
<PageHeader title="Select plan" onBack={() => closePlanPicker()} />

Framework link for back

backHref renders a plain <a>, which reloads the page in a client-routed app. Pass your router's link element as backRender instead — it receives the back affordance's classes, aria-label, data-slot and chevron, and navigates client-side. backRender wins over backHref; onBack wins over both.

import Link from "next/link";

<PageHeader
  backRender={<Link href="/products" />}
  backLabel="Back to products"
  title={product.name}
/>;

Long title

An overlong tenant or workspace title truncates with an ellipsis instead of overflowing the header row. The full title reveals via a tooltip on hover or keyboard focus — a tap-to-toggle disclosure on devices that can't hover (see TruncatedText):

<PageHeader title="Q3 Platform Reliability & Performance Engineering Initiative Retrospective" />

Wrapping title

titleLines sets how many lines the title may take before it clips — 2 clamps to two lines — and "none" lets it wrap freely with no truncation, for record pages whose name is the content. An unbroken token — a 170-character file name, a pasted URL — breaks anywhere rather than pushing the page sideways, and inside a clamp it breaks too, so the ellipsis still lands.

View tabs

On a list page, the scope tabs — whose records it shows ("My tasks | Created by me | Team") — do not go in tabs: they go in the ListToolbar's tabs, on the toolbar row (tabs left, tools right), where they fold to a dropdown when tight. A list page passes no actions either: its main button is the toolbar's action. The header keeps the title, description, meta and ⓘ (see Lists and tables).

tabs is for a record page's content tabs and a settings page's sub-page route tabs (RouteTabs overflow="menu", which folds on a phone instead of clipping).

<PageHeader
  title="Tasks"
  actions={<Button>New task</Button>}
  tabs={
    <Tabs value={scope} onValueChange={setScope}>
      <TabsList aria-label="Tasks to show">
        <TabsTrigger value="mine">My tasks</TabsTrigger>
        <TabsTrigger value="team">Team</TabsTrigger>
      </TabsList>
    </Tabs>
  }
/>
<ListToolbar
  aria-label="Task toolbar"
  search={{ value: query, onValueChange: setQuery, placeholder: "Search tasks" }}
  filterRow={<FilterRow facets={facets} />}
  layout={{ value: view, options: ["list", "board"], onValueChange: setView }}
/>

Metadata with controls

description is a paragraph, so a button or select inside it is invalid HTML. Put status badges, owners, dates and inline pickers in meta instead: a muted, wrapping <div> row under the title.

Favorite star

The star is controlled when you pass active, or uncontrolled when you pass defaultActive. It reports the next state through onToggle. Pass disabled to remove it from the tab order.

The active star fills with neutral ink, not warning yellow. The status hues are rationed to actual status, and a favourite is a user's own mark rather than a caution — the fill is what carries the on/off read, so the colour was never doing that work.

The preview shows a controlled star (click to toggle) above a disabled one:

// Uncontrolled — seeds initial state, host persists on toggle
<PageHeader title="Doc" favorite={{ defaultActive: true, onToggle: (next) => persist(next) }} />

// Controlled — host owns the state
<PageHeader title="Doc" favorite={{ active: isStarred, onToggle: setStarred }} />

// Disabled — non-interactive, out of the tab order
<PageHeader title="Doc" favorite={{ defaultActive: true, disabled: true }} />

Secondary menu

Compose your own overflow menu (e.g. a DropdownMenu with an icon-only Button trigger) and pass it via secondaryMenu — it renders to the right of actions:

<PageHeader
  title="Spaces"
  actions={<Button>New space</Button>}
  secondaryMenu={
    <DropdownMenu>
      <DropdownMenuTrigger
        render={
          <Button size="icon" variant="ghost" aria-label="More actions">
            <MoreVertical />
          </Button>
        }
      />
      <DropdownMenuContent>{/* … */}</DropdownMenuContent>
    </DropdownMenu>
  }
/>

Section headings

SectionHeading titles an in-page section below the PageHeader, so a page never hand-rolls <h2 className="text-base font-medium">. size="md" (16px, the default) titles a page section, size="sm" (14px) a card or panel section, and variant="eyebrow" is the quiet muted 12px label above a group. actions sits at the end of the same row; as sets the outline level.

import { SectionHeading } from "@/components/ui/page-header";

<SectionHeading actions={<Button variant="ghost" size="sm">View all</Button>}>
  Recent activity
</SectionHeading>
<SectionHeading size="sm" as="h3">Contacts</SectionHeading>
<SectionHeading variant="eyebrow" as="h3">Pinned</SectionHeading>

API Reference

PageHeader

SectionHeading

PageHeaderFavorite

FavoriteStar

FavoriteStar renders the controlled star toggle used by PageHeader's favorite slot. Prefer the favorite prop for ordinary page headers; export-level composition is available when the same toggle must be placed elsewhere.

Accessibility

• The root renders <header>, a banner landmark when PageHeader sits at the top of the page (outside <article>/<aside>/<main>/<nav>/<section>), so assistive tech can jump straight to it.
• The title renders as a single <h1> in the page-heading face (font-heading text-2xl font-semibold) — one per page — so assistive tech announces the page's primary heading. Pass the breadcrumb as a labelled <nav aria-label="breadcrumb">.
• An overlong title is keyboard-focusable when clipped (TruncatedText's overflow measurement), so the full title is reachable via Tab and a focus-triggered tooltip — not hover-only.
• The back affordance is a real link (backRender or backHref) or button (onBack) with an accessible backLabel (default "Go back"), and shows a visible :focus-visible ring.
• The favorite star is a toggle button: it carries aria-pressed reflecting the starred state and a label (default "Favorite"); the visual fill is decorative.
• All interactive parts are keyboard reachable and operable; the visual order matches the DOM order.

Do / Don't