Preview

Installation

pnpm add @oshon-ai/components @oshon-ai/tokens @oshon-ai/primitives

pnpm dlx @oshon-ai/cli add pageheader

Wire the tokens into your Tailwind v4 stylesheet:

/* app/globals.css */
@import 'tailwindcss';
@import '@oshon-ai/tokens/css';
@import '@oshon-ai/tokens/tailwind';

New here? Walk through the full setup — prereqs, theming, your first render.

Usage

Import the component and render it. Every component supports the standard tier, size, and disabled props where applicable.

'use client';
import { PageHeader } from '@oshon-ai/components';

export default function Example() {
  return <PageHeader />;
}

<PageHeader title="Page title" onBack={() => {}}>
      <TrailingActions />
    </PageHeader>

<PageHeader
      title="Page title"
      subtitle="Secondary line of context"
      onBack={() => {}}
    >
      <ButtonHug tier="tertiary">Cancel</ButtonHug>
      <ButtonHug tier="primary">Save</ButtonHug>
    </PageHeader>

<PageHeader
      title="Page title"
      onBack={() => {}}
      tags={
        <>
          <Badge state="success">Tag A</Badge>
          <Badge state="info">Tag B</Badge>
          <Badge state="warning">Tag C</Badge>
        </>
      }
    >
      <ButtonHug tier="primary">Action</ButtonHug>
    </PageHeader>

{
    function Demo() {
      const [q, setQ] = useState('');
      return (
        <PageHeader
          title="Page title"
          filters={
            <Input
              placeholder="Search"
              value={q}
              onChange={(e) => setQ(e.target.value)}
              style={{ maxWidth: 360 }}
            />
          }
        >
          <ButtonHug tier="secondary">Secondary</ButtonHug>
          <ButtonHug tier="primary">Primary</ButtonHug>
        </PageHeader>
      );
    }
    return <Demo />;
  }

{
    function Demo() {
      const [active, setActive] = useState('all');
      const opts = ['all', 'recent', 'archived', 'shared'] as const;
      return (
        <PageHeader
          title="Page title"
          filters={
            <>
              {opts.map((id) => (
                <ChoiceChip
                  key={id}
                  selected={active === id}
                  onClick={() => setActive(id)}
                >
                  {id.charAt(0).toUpperCase() + id.slice(1)}
                </ChoiceChip>
              ))}
            </>
          }
        >
          <ButtonHug tier="primary">Primary</ButtonHug>
        </PageHeader>
      );
    }
    return <Demo />;
  }

{
    function Demo() {
      const [q, setQ] = useState('');
      return (
        <PageHeader
          title="Page title"
          subtitle="Secondary line of context"
          onBack={() => {}}
          tags={
            <>
              <Badge state="success">Tag A</Badge>
              <Badge state="info">Tag B</Badge>
            </>
          }
          filters={
            <Input
              placeholder="Search"
              value={q}
              onChange={(e) => setQ(e.target.value)}
              style={{ maxWidth: 320 }}
            />
          }
        >
          <TrailingActions />
        </PageHeader>
      );
    }
    return <Demo />;
  }

<div style={{ display: 'flex', flexDirection: 'column' }}>
      {SIZES.map((size) => (
        <PageHeader
          key={size}
          size={size}
          title="Page title"
          subtitle="Secondary line of context"
          onBack={() => {}}
          tags={
            <Badge size={size} state="info">
              Tag
            </Badge>
          }
        >
          <TrailingActions />
        </PageHeader>
      ))}
    </div>

<PageHeader title="Page title">
      <ButtonHug tier="secondary">Secondary</ButtonHug>
      <ButtonHug tier="primary">Primary</ButtonHug>
    </PageHeader>

API

Every prop is documented here directly from the component's TypeScript interface. Inherited DOM attributes (aria-*, onClick, style, etc.) work as usual but are omitted from this table.

Styling

Three layers of customization, in order of escape-hatch strength: className overrides → data-attribute targeting → CSS custom properties.

Passing Tailwind classes

Every Oshon component accepts a className prop merged AFTER the component's default classes. Use it to override spacing, color, or size without forking the component.

<PageHeader
  className="ring-2 ring-offset-2 ring-blue-500"
/>

Data attributes

Oshon components expose their internal state as data-oshon-* attributes so you can target them from CSS without coupling to internal class names. The most common attributes are listed below — see the component's source for the full set.

/* Target the secondary tier specifically */
[data-oshon-tier="secondary"] {
  --oshon-color-primary-700: var(--my-brand-color);
}

Interactive states

Every interactive component supports the standard CSS pseudo- classes plus Tailwind's state variants. Focus rings always use :focus-visible so keyboard users see them but mouse users don't.

• :hover / hover:* — pointer hover
• :focus-visible / focus-visible:* — keyboard focus
• :active / active:* — pressed
• :disabled / disabled:* — set via the disabled prop

Anatomy

The named regions a consumer composes when rendering this component. Each is documented separately so you can target keyboard nav, ARIA labels, and slot props with precision.

Keyboard

Accessibility

Every Oshon component ships axe-clean. We test in CI on every PR and publish the audit log per component.

WCAG level

2.2 AA

Screen readers tested

VoiceOver (macOS), NVDA (Windows)

Last axe audit

2026-04-24

Do / Don't

<PageHeader title="Page title" />

<PageHeader
  title="Page title"
  subtitle="Secondary line of context"
  onBack={() => router.back()}
  tags={<>
    <Badge state="success">Tag A</Badge>
    <Badge state="info">Tag B</Badge>
  </>}
  filters={<TextField placeholder="Search" leadingIcon="search" />}
>
  <ButtonHug tier="tertiary">Cancel</ButtonHug>
  <ButtonHug tier="primary">Save</ButtonHug>
</PageHeader>

<PageHeader
  title="Page title"
  filters={<>
    <ChoiceChip>All</ChoiceChip>
    <ChoiceChip>Recent</ChoiceChip>
    <ChoiceChip>Archived</ChoiceChip>
  </>}
>
  <ButtonHug tier="primary">Primary action</ButtonHug>
</PageHeader>

<PageHeader title="Oshon" /> /* at the top of the app */

<><PageHeader title="Section A" /><PageHeader title="Section B" /></>

<PageHeader className="h-[80px] w-[1200px]" title="Page title" />

<PageHeader title="Page title" filters="42 results · last sync 2 min ago" />

Related

• GlobalToolbar
• SideNav
• Badge
• TextField
• ChoiceChip

Design rationale

PageHeader started as a Figma-faithful title bar with three slots (title, badge, children). Product feedback revealed that real pages want more on this surface: a subtitle for context, multiple tags rather than a single status pill, and a place to put page-level controls (search, filter chips, date range pickers) without colliding with the trailing action cluster. The extended slot topology — lead (back + title-column + tags), filters (flex-1), end (actions) — keeps the original Figma geometry (56px row, 16/8 padding, 16px gap, 20×20 back button at node 9336:1131) intact while giving every consumer a predictable place to land each kind of content. The title-column composes title + subtitle vertically so the heading-then-supporting-text reading order matches the visual order. The tags slot accepts plural children with a wrap-friendly gap so a row with five tags degrades gracefully on a narrow viewport. The filters slot takes `flex-1` and `min-w-0` so an inline search field grows to absorb available width and shrinks past its content size when the surrounding clusters need room. Configurability layers (slotClassName per region, backIcon override, as=`header|div|section`, headingLevel 1..6) ship as additive APIs so callers never need to fork the component — every layout decision the component owns is reachable from props. The badge prop is kept as a deprecated alias because zero consumers shipped against the original API in this monorepo, but the alias means we never have to chase down call sites in downstream products.