<!-- Generated by scripts/gen-docs.mts from the JSDoc in registry/. Do not edit; run `pnpm run docs`. -->

# PageHeader

The top of a page: its title with an optional line above it (`eyebrow`), a description under it, the page's actions beside it, and a trail and an image above. On phones the actions move under the title. The title is the page's `<h1>`, in the theme's heading font; with `level={2}` the header heads a section instead.

```tsx
import { PageHeader } from "@/components/ouro/page-header/page-header";
```

## Example

```tsx
<PageHeader
  eyebrow="Settings"
  title="Billing"
  description="Your plan, invoices and payment method."
  actions={<Button>Change plan</Button>}
/>
```

## Use instead when

- Use `Heading` instead for a plain title with nothing around it, and `Card` for a block of content with its own title inside a page.

## Props

Type: `PageHeaderProps`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `actions` | `ReactNode` |  | The page's actions, such as Edit and Share buttons: at the end of the title on wide screens, under it on phones. |
| `breadcrumb` | `ReactNode` |  | A trail above everything else, such as a `Breadcrumb`. |
| `children` | `ReactNode` |  | More under the description, such as badges or a byline. |
| `className` | `string` |  | Layout only: margins, width (`mb-8`, `max-w-5xl`). Appearance classes warn in development. |
| `description` | `ReactNode` |  | A short sentence under the title. |
| `divider` | `boolean` |  | A line under the header, between it and the page's content. |
| `eyebrow` | `ReactNode` |  | A short line above the title that says what kind of page this is or where it sits: "Settings", "Project". |
| `level` | `1 \| 2` | `1` | The title's heading level. `1` for the page title; `2` when the header heads a section inside a page that already has its `<h1>`. |
| `media` | `ReactNode` |  | An image or illustration above the title, at the header's full width with rounded corners. Give an `<img>` its `alt`, or `alt=""` when the title already says what it shows. |
| `ref` | `Ref<HTMLDivElement>` |  | Reaches the rendered element. |
| `size` | `"md" \| "lg"` | `"md"` | How large the title is: `md` for an app page, `lg` for a landing or profile page. |
| `title` (required) | `ReactNode` |  | The page's title, its `<h1>` (or `<h2>` with `level={2}`). |

## Native attributes

Also accepts the attributes in React's `HTMLAttributes` (`id`, `aria-*`, event handlers), passed to the rendered element, except those named on this page.

## Don't use

These are not props. Passing one fails the type check with the fix in the error, and in development a console message names the fix.

- `action`: Not a prop. The buttons are `actions`: `<PageHeader actions={<Button>Edit</Button>} />`.
- `heading`: Not a prop. The title is `title`: `<PageHeader title="Billing" />`.
- `image`: Not a prop. The image is `media`: `<PageHeader media={<img src={src} alt="" />} />`.
- `overline`: Not a prop. The text above the title is `eyebrow`: `<PageHeader eyebrow="Settings" title="…" />`.
- `subtitle`: Not a prop. The text under the title is `description`: `<PageHeader title="…" description="…" />`.

## `className` is for layout only

Pass margins, width and grid placement (`mt-4`, `w-full`, `col-span-2`).

Appearance comes from props, not classes. In development, a class that sets appearance logs one warning per component instance, naming the prop to use instead. A class sets appearance when, after its variants (`hover:`, `sm:`) and any `!` are removed, it starts with `bg-`, `text-`, `border-`, `rounded-`, `shadow-`, `font-`, `ring-`, `from-`, `via-`, `to-`, `fill-` or `stroke-`, or is `border`, `rounded`, `shadow` or `ring`, or has a `dark:` variant. Text wrapping, overflow and table layout classes (`text-wrap`, `text-ellipsis`, `border-collapse`) are layout and do not warn.

Alignment classes (`text-center`) warn too: set alignment on a parent element.
