Basic usage

A title, an optional description, and a slot for the screen's primary actions. The title becomes the page's <h1>, so there should be exactly one PageHeader per screen.

The header is w-full with px-4 md:px-6 — the same horizontal padding PageContainer uses, which is what keeps the title aligned with the content below it.

Breadcrumb

Pass an array of { label, href? } and the header builds a full Breadcrumb above the title. The last item is always rendered as the current page — non-clickable, marked aria-current="page" — even if you gave it an href. The crumbs below are real links; try them.

LinkComponent exists because the . entry of the package must resolve outside Next — Vite, Storybook, a test runner. A single import 'next/link' in this file would break all of those the moment an app imported Button. The same convention appears on RouteTabs and the shell components.

Icon

icon takes a component, not an element: icon={CalendarCheck}, never icon={<CalendarCheck />}. A Lucide icon is a forwardRef object rather than a function, so a component and an element cannot be told apart at runtime — the package types the slot narrowly and lets the compiler catch the mistake instead of guessing wrong in silence. It is the same IconComponent type used by EmptyState and FilterChips.

The chip is filled with bg-app-accent/10 — a tint of whatever accent the current product sets — while the glyph stays text-foreground. That split is the package's three-role colour contract: --app-accent fills backgrounds and nothing else. The tempting version of this pattern shipped once — 0.1.0's AppLauncher drew the icon in the accent colour on a 15% accent tint — and with the default gold accent it measured 1.69:1, well under the 3:1 WCAG 1.4.11 asks of graphical objects. No shade of gold fixes that pair, which is why the roles are separate variables rather than a rule nobody enforces. If your app overrides --app-accent, override --app-accent-ink alongside it.

Secondary row

Anything passed as children renders under the title and above the bottom rule — route tabs, a filter bar, status chips. The chips below are live; toggling them changes real state.

Note the English strings. FilterChips defaults allLabel to "Tất cả" and its screen-reader group name to "Bộ lọc nhanh", like most of the package. PageHeader itself has no strings of its own to translate — with one exception, covered under Accessibility.

Sticky and borderless

sticky adds sticky top-0 z-20 plus backdrop-blur, so the title and primary action stay reachable down a long list. It pins to the nearest scrolling ancestor — inside AppShell that is <main>, not the window. Scroll the frame below.

The blur is applied as supports-[backdrop-filter]:bg-background/80 on top of a solid bg-background: where the browser cannot blur, the header stays opaque rather than letting rows show through the title.

borderless is the other half of the pair. It removes the bottom rule and the pb-4 that goes with it — the header ends flush against its own content, so whatever follows needs to bring its own top spacing.

PageContainer widths

PageContainer exists so the left margin of Tasks and the left margin of CRM are the same number. Every page writing its own px-4 md:px-6 max-w-… drifts by a few pixels per screen — invisible on any one page, and exactly what makes a suite of products feel like a set of unrelated apps.

This preview frame is narrower than 64rem, so only sm visibly clamps here — md and lg start clamping and centring once the viewport is wide enough, while full never does at any width. The numbers above are the contract; pick by content, not by how it looks in this box.

as changes the wrapper element, and it is the one prop worth thinking about twice. Code only below — rendering a second <main> inside this documentation page would be exactly the landmark error the comment warns about.

import { PageContainer } from '@comitor/ui'

// Outside the shell — a print view, a 404, a standalone screen — there is no
// <main> on the page, so let the container be it.
//
// Inside AppShell, leave 

The two together

The header goes outside the container, as siblings in a fragment. That is deliberate: the header is full width, so its bottom rule and its sticky background span the whole content area, while the container clamps only the body. If you need the title to line up with a clamped column instead, put the header inside a <PageContainer flush> — you trade the edge-to-edge rule for the alignment.

Static by design

Neither file carries 'use client'. Two consequences worth knowing:

• A list page can stay a Server Component: metadata, the frame and the data preparation on the server, with 'use client' pushed down to the one island that actually needs state — usually the table. Putting the directive at the top of the page instead ships the entire frame to the browser for nothing.
• The breadcrumb arrives through props rather than being read from shell context. If PageHeader depended on ShellContext, every screen rendered outside the shell — a print view, an error page, a full-screen dialog — would throw.

Anything interactive you hand to actions or children still has to be a client component itself — the slots are transparent, they do not change the boundary.

Props

PageHeader

PageHeaderBreadcrumbItem — the shape of each entry in the breadcrumb array.

PageContainer

Accessibility

• The root is a real <header> element and the title is a real <h1> — one per screen. (Each demo on this page emits one, so this documentation page has several; that is a demo artefact, not a pattern to copy.)
• The title is truncated visually with truncate, not shortened in the DOM — the full string is still read out. Do not pre-truncate it yourself.
• Breadcrumbs render as <nav> wrapping an ordered list. The final crumb is a <span role="link" aria-disabled="true" aria-current="page">: deliberately not focusable, because a link to the page you are already on is a keyboard stop that leads nowhere, while aria-current still names it as the current position.
• The chevrons between crumbs are role="presentation" and aria-hidden, so a screen reader hears the trail, not a string of “greater-than”.
• The one Vietnamese string. The breadcrumb <nav> is named aria-label="Đường dẫn phân cấp" by the underlying primitive, and PageHeader takes no labels prop — ...rest lands on the <header>, not on the breadcrumb. An English-only product that cares about the landmark name should leave breadcrumb off and compose <Breadcrumb aria-label="Breadcrumb"> above the header itself.
• The wrapper of the icon chip carries aria-hidden="true", which takes the whole chip — glyph included — out of the accessibility tree, so it never doubles the title. Your icon component itself is only ever handed a className here; unlike EmptyState, PageHeader does not pass aria-hidden down. Either way, nothing may live in the icon alone.
• Icon-only buttons in actions need their own aria-label — the header does not supply one, as the demo above shows.
• Colour in the icon chip follows the three-role contract: --app-accent tints the background only, and the glyph sits on it at text-foreground. Never text-app-accent: the accent-on-accent version measured 1.69:1 against the 3:1 that WCAG 1.4.11 requires for graphical objects.
• A sticky header at z-20 can cover content that a fragment link jumps to. Give anchored targets scroll-margin-top equal to the header height when your page uses in-page anchors.
• PageContainer defaults to a plain <div> so it adds no landmark by accident. Only reach for as="main" outside the shell, where nothing else provides one.