Page header

Composable page-level header. Title + subtitle + breadcrumbs + actions + tabs + metadata + stats.

PageHeader is the standard page-top header — composes Breadcrumb, Button, TabBar, and a metadata grid into one component. Inherits background from parent context (no surface of its own), so it works on pages with any background.

Use it for

Detail page headers (company / project / record pages)
Section headers that need breadcrumbs + page title + primary action
Dashboards with metadata + stat tiles + tab navigation
Any page where the top region groups identity + navigation + primary CTA

For Sheet headers (inside a <Sheet>), the Sheet component composes its own — don't reach for PageHeader inside a Sheet body.

Import

import { PageHeader } from '@brikdesigns/bds';

Anatomy

PageHeader has six optional regions plus a required title. From top to bottom:

breadcrumbs — Breadcrumb above the title row
badge + title — service icon (left) + page H1
subtitle — supporting paragraph under the title
actions — right-aligned action buttons (typically a Button or ButtonGroup)
metadata — built-in key/value grid (Owner, Status, Updated)
stats — summary content (e.g. stat-tile Card preset="summary" grid)
tabs — TabBar for in-page section nav

Variants

Title only

<PageHeader title="Dashboard" />

Title + subtitle

<PageHeader
  title="My account"
  subtitle="Manage your membership plan and billing."
/>

With breadcrumbs and actions

<PageHeader
  title="Birdwell & Mutlak"
  breadcrumbs={
    <Breadcrumb items={[
      { label: 'Clients', href: '/clients' },
      { label: 'Birdwell & Mutlak' },
    ]} />
  }
  actions={<Button variant="primary">Edit</Button>}
/>

With service badge

ServiceBadge renders to the left of the title for service-line pages.

<PageHeader
  title="Website Design"
  subtitle="Custom web development and design."
  badge={<ServiceBadge category="marketing" serviceName="Custom Web Development" size="lg" />}
  actions={<Button variant="primary">Edit Service</Button>}
/>

With metadata

metadata is a built-in key/value grid for page-level facts.

<PageHeader
  title="Brand Refresh"
  metadata={[
    { label: 'Owner', value: 'Sarah Chen' },
    { label: 'Status', value: <Badge status="positive">Active</Badge> },
    { label: 'Updated', value: '2 days ago' },
  ]}
/>

With stats

stats renders summary content between metadata and tabs — typically a row of stat tiles.

<PageHeader
  title="Q1 Performance"
  stats={
    <CardList orientation="horizontal" gap="md">
      <Card preset="summary" label="Revenue" value={48250.75} type="price" />
      <Card preset="summary" label="New clients" value={12} />
      <Card preset="summary" label="Projects" value={34} />
    </CardList>
  }
/>

With tabs

<PageHeader
  title="My Account"
  subtitle="Manage your membership plan."
  tabs={
    <TabBar items={[
      { label: 'Overview', active: true },
      { label: 'Billing' },
      { label: 'Security' },
    ]} />
  }
/>

Sizes

size controls the title scale. Default lg.

<PageHeader title="Compact dashboard header" size="sm" />
<PageHeader title="Standard page header" size="md" />
<PageHeader title="Hero detail page" size="lg" />

Flush layout

flush removes horizontal padding for layouts that provide their own.

<PageHeader title="..." flush />

Pattern: full company detail page

The canonical layout — breadcrumb + service badge + title + actions + metadata + tabs.

<PageHeader
  title="Birdwell & Mutlak"
  subtitle="Active client · Dental"
  breadcrumbs={
    <Breadcrumb items={[
      { label: 'Clients', href: '/clients' },
      { label: 'Birdwell & Mutlak' },
    ]} />
  }
  badge={<ServiceBadge category="dental" size="lg" />}
  actions={<ButtonGroup>
    <Button variant="ghost">Archive</Button>
    <Button variant="primary">Edit</Button>
  </ButtonGroup>}
  metadata={[
    { label: 'Owner', value: 'Nick Stanerson' },
    { label: 'Industry', value: 'Dental' },
    { label: 'Updated', value: '3 days ago' },
  ]}
  tabs={
    <TabBar items={[
      { label: 'Brand', active: true },
      { label: 'Services' },
      { label: 'Locations' },
      { label: 'Activity' },
    ]} />
  }
/>

When not to use

Don't use PageHeader inside a Sheet. Use Sheet's built-in header instead — different shape, different semantics.
Don't use PageHeader without a title. It's required and serves as the page H1; without it, the page outline breaks.
Don't put complex JSX in metadata values. Metadata is for short pinned facts. For richer per-section content, use DataSection.

Accessibility

Renders a real <header> landmark.
The title is the page's <h1> — only one PageHeader per page.
Breadcrumb, TabBar, and action elements keep their own semantics.

API

Prop	Type	Default
`title`	`string` (required)	—
`subtitle`	`string`	—
`badge`	`ReactNode`	—
`breadcrumbs`	`ReactNode`	—
`actions`	`ReactNode`	—
`tabs`	`ReactNode`	—
`metadata`	`MetadataItem[]`	—
`stats`	`ReactNode`	—
`showDivider`	`boolean`	`true`
`flush`	`boolean`	`false`
`size`	`'sm' \| 'md' \| 'lg'`	`'lg'`

MetadataItem

interface MetadataItem {
  label: string;
  value: ReactNode;
}

Breadcrumb — common breadcrumbs prop content
TabBar — common tabs prop content
ServiceBadge — common badge prop content
DataSection — for body sections below the header
Sheet — has its own header for in-Sheet contexts
Storybook playground

Page header

On this page