Layout

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.

Settings

Billing

Your plan, invoices and payment method.

In Spoonjoy

Spoonjoy, a recipe app, is built with Ouro HX (how).

See it live, no sign-in needed: Test kitchen · Developers · API playground

In its source: app/routes/my-recipes.tsx · app/components/errors/route-error.tsx · app/components/recipe/RecipeNotFound.tsx

Install

Once per app, with Tailwind CSS v4 and an @/* path alias (Ouro HX is built on Base UI, so --base base; skip -t in an existing app):

npx shadcn@latest init --base base --preset nova --yes --no-monorepo

npx shadcn@latest add ourostack/ouro-ui/ouro-base#v1.2.13

Then the component. From v0.8.0 it installs only the helpers it imports and never touches your stylesheet (Installing):

npx shadcn@latest add ourostack/ouro-ui/page-header#v1.2.13

Or, with the @ouro namespace set up:

npx shadcn@latest add @ouro/ouro-base @ouro/page-header

Its tests, stories and Playwright spec are optional. They need Vitest 4.1.11 or later, and from v0.8.0 never change a version your app has (Testing):

npx shadcn@latest add ourostack/ouro-ui/page-header#v1.2.13 ourostack/ouro-ui/page-header-tests#v1.2.13

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

Paths use shadcn's default @/ alias; the CLI rewrites them to yours.

Example

<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.

actions: Type: 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: Type: ReactNode; A trail above everything else, such as a Breadcrumb.
children: Type: ReactNode; More under the description, such as badges or a byline.
className: Type: string; Layout only: margins, width (mb-8, max-w-5xl). Appearance classes warn in development.
description: Type: ReactNode; A short sentence under the title.
divider: Type: boolean; A line under the header, between it and the page's content.
eyebrow: Type: ReactNode; A short line above the title that says what kind of page this is or where it sits: "Settings", "Project".
level: Type: 1 | 2; Default: 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: Type: 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: Type: Ref<HTMLDivElement>; Reaches the rendered element.
size: Type: "md" | "lg"; Default: "md"; How large the title is: md for an app page, lg for a landing or profile page.
title (required): Type: ReactNode; The page's title, its <h1> (or <h2> with level={2}).

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.

Source on GitHub This page as Markdown