PageHeader

Canonical page header - the top of a page, beneath the app's own header. Pass its parts and it lays them out: a breadcrumb or back link, the title with optional media, a count or badge and a subtitle, the page's actions, and a switcher beneath between views of what the page shows. Every part but the title is optional, and a row with nothing in it is not rendered. It says what the page is; the controls that narrow or order a list sit in a PageToolbar beneath it.

Materials

128 in library

Usage

@instruments/materia-ui/compositions/page-header

<PageHeader>
  <PageHeaderTitle level="2" size="heading" subtitle="128 in library">
    Materials
  </PageHeaderTitle>
  <PageHeaderActions>
    <Button emphasis="soft" icon={SlidersHorizontal} tone="neutral">
      Filter
    </Button>
    <Button icon={Plus} tone="brand">
      Add material
    </Button>
  </PageHeaderActions>
</PageHeader>

Best practices

Pass title and the parts the page has rather than composing rows by hand; the header owns wrapping, truncation and spacing, so every page reads the same.
A count belongs in meta or subtitle, never in the title text; a back link belongs in breadcrumb, never in actions.
nav switches between views of the thing the page shows (a pill TabNavigation of routes). Type switchers, filters, sort and view belong in a PageToolbar, each once.
Set layout="stacked" and wrap each row in PageHeaderRow for multi-row headers; the default "single" wraps only when a narrow viewport needs to protect the title or actions.
PageHeader is the sub-header below the app HeaderBar, not the app chrome itself - use SidebarProvider with SidebarInset or HeaderBar for the top-level frame; its sticky offset assumes that header is present.

Props

PageHeader

Prop	Type	Default	Description
actions	`React.ReactNode`		Actions on the title's row, such as a primary button and a menu. They share the title's row; on a phone the title wraps first, and actions too wide to fit drop beneath it.
breadcrumb	`React.ReactNode`		Where the page sits, above the title: a `Breadcrumb`, or a back link. Leave the current page out; the title names it.
level	`"1" \| "2" \| "3" \| "4" \| "5" \| "6" \| undefined`	`"1"`	Heading level of the title.
media	`React.ReactNode`		An image beside the title, such as an `Avatar` or a brand's logo.
meta	`React.ReactNode`		A count or badge on the title's baseline, such as "1,240 products".
nav	`React.ReactNode`		A switcher between views of what the page shows, beneath the title, such as a pill `TabNavigation` of routes. Controls that narrow or order a list belong in a `PageToolbar`.
size	`ResponsiveValue<"title" \| "heading" \| "paragraph-sm" \| "paragraph-lg" \| "subheading" \| "subheading-lg" \| "heading-sm" \| "heading-lg"> \| undefined`	`"heading-sm"`	Title type role, or a role per breakpoint.
subtitle	`React.ReactNode`		One line under the title: a count, a date, or who it belongs to.
title	`React.ReactNode`		The page's name. A string, or a node such as a link.
gutter	`boolean`		Apply the shared page gutter. Set false when an enclosing shell owns it.
sticky	`boolean`		When true, the header sticks to the top of the viewport when scrolling.
layout	`"single" \| "stacked"`		Layout mode - "single" for one responsive title/actions composition, "stacked" for multiple explicit rows using `PageHeaderRow`.

PageHeaderTitle

Prop	Type	Description
children(required)	`React.ReactNode`	Title content - a string or custom React nodes.
collapseOnScroll	`boolean`	When true, the heading fades out and collapses as the page scrolls past it - useful for standalone page titles beneath a fixed app header. Defaults to false.
collapseOnScrollDistance	`number`	Distance in px the page must scroll before the heading fully collapses.
level	`HeadingLevel \| undefined`	Heading level for semantic HTML (h1-h6). Defaults to "1".
meta	`React.ReactNode`	Optional inline metadata rendered beside the heading, such as a count.
size	`ResponsiveValue<"title" \| "heading" \| "paragraph-sm" \| "paragraph-lg" \| "subheading" \| "subheading-lg" \| "heading-sm" \| "heading-lg"> \| undefined`	Type role of the title - a single role or a responsive object. Defaults to "heading-sm".
subtitle	`React.ReactNode`	Optional subtitle text displayed below the title.

Also exports

componentPageHeaderActions
componentPageHeaderLead
componentPageHeaderRow
interfacePageHeaderSlotProps
componentPageHeaderTabs
constusePageHeader

Composition

Builds on

Flex, Heading, Text