<!-- Protocore Design System — PageHeader -->
# PageHeader

- **Category:** Navigation (`navigation`)
- **Slug:** `navigation/page-header`
- **Status:** stable
- **Platforms:** web
- **Import:** `import { PageHeader } from "@protocore/pds";`
- **Docs:** https://pds.protocore.io/components/navigation/page-header

> Page title row — an optional icon tile and eyebrow, an h1, a lead line, a meta-badges slot and an actions slot, closed by a bottom hairline.

## When to use it

Use **PageHeader** once per screen, at the top, to name the page and expose its top-level actions. It anchors the layout and gives every page a consistent title row.

- Sits directly under a **Breadcrumb** on nested routes — the crumb shows the path, the header restates the leaf.
- Just a mono kicker above a section, not a whole page? Use **Eyebrow** on its own.
- Grouping content within a page below the header? Use **Section**.
- Put page-level KPIs in a **StatStrip** beneath the header rather than crowding the title row.

## Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `actions` | `ReactNode` | no | — | Actions slot pinned to the right (e.g. buttons); stacks below on mobile. |
| `className` | `string` | no | — | — |
| `eyebrow` | `ReactNode` | no | — | Mono uppercase eyebrow above the title (e.g. an `<Eyebrow>` or plain text). |
| `icon` | `ReactNode` | no | — | Optional leading icon, framed in a 32px square surface-2 tile beside the title. |
| `lead` | `ReactNode` | no | — | Supporting lead line beneath the title. |
| `meta` | `ReactNode` | no | — | Meta badges slot rendered inline beside the title (e.g. status Badges). |
| `style` | `CSSProperties` | no | — | — |
| `title` | `ReactNode` | yes | — | The page title — rendered as the `<h1>`. |

## Examples

### Basics

At minimum a `title` — add an `eyebrow` for context and a `lead` line to summarise the page. The bottom hairline separates it from the content below.

```tsx
import { PageHeader } from "@protocore/pds";

export default function PageHeaderBasics() {
  return (
    <PageHeader
      eyebrow="Networks"
      title="Ethereum Mainnet"
      lead="Endpoint status, verifier set, and recent message throughput."
    />
  );
}
```

### Icon, meta and actions

The `icon` slot frames a leading glyph in a 32px tile, `meta` renders status Badges beside the title, and `actions` pins buttons to the right (stacking below on mobile).

```tsx
import { PageHeader, Badge, Button, Icon } from "@protocore/pds";
import { Network, RefreshCw, Settings } from "lucide-react";

export default function PageHeaderFull() {
  return (
    <PageHeader
      icon={
        <Icon>
          <Network />
        </Icon>
      }
      eyebrow="Console / Networks"
      title="Ethereum Mainnet"
      lead="Endpoint status, verifier set, and recent message throughput."
      meta={
        <Badge tone="success" dot>
          operational
        </Badge>
      }
      actions={
        <>
          <Button variant="secondary" startIcon={<RefreshCw />}>
            Sync
          </Button>
          <Button startIcon={<Settings />}>Configure</Button>
        </>
      }
    />
  );
}
```

## Do & don't

**Do**

- Use exactly one PageHeader per page, as the first element of the main content.
- Put the page's primary action in the actions slot; keep it to one or two buttons.
- Use meta for status Badges (environment, health), not for long prose.
- Keep the title short — the lead line carries the explanation.

**Don't**

- Don't nest a PageHeader inside a card or a section — it owns the page top.
- Don't stack multiple headers to fake a hierarchy; use Section headings instead.
- Don't overload actions with a whole toolbar of buttons — move overflow into a menu.
- Don't restate the breadcrumb leaf verbatim if it adds nothing.

## Accessibility

**Notes**

- The title renders as the page's `<h1>`; keep one PageHeader per page so the document has a single top-level heading.
- The icon tile is `aria-hidden` decoration — never rely on it to convey meaning the title doesn't.
- Buttons in the actions slot bring their own labels; icon-only actions must carry an `aria-label`.

## Related

`breadcrumb`, `eyebrow`, `section`, `stat-strip`

---

© Protocore. All rights reserved. Use of the Protocore Design System requires prior written authorization from Protocore (contact@protocore.io). These machine-readable materials must not be ingested into ML-training datasets or derivative design systems. See https://pds.protocore.io/legal/