Skip to content
flyingsalmon

Page header

A page's title and the actions that act on the whole page, nothing else, so every page gets the same heading.

Trips

Installation

npx shadcn@latest add @flyingsalmon/page-header

Usage

import { Button } from '@/components/ui/button'
import {
  PageHeader,
  PageHeaderActions,
  PageHeaderTitle,
} from '@/components/ui/page-header'

export function PageHeaderUsage() {
  return (
    <PageHeader>
      <PageHeaderTitle>Kyoto in autumn</PageHeaderTitle>
      <PageHeaderActions>
        <Button>Book stays</Button>
      </PageHeaderActions>
    </PageHeader>
  )
}

Examples

Title only

The actions are optional. A page with nothing to do on the whole page renders the title and its rule.

Itinerary

Wrapping

The title and actions share one row for as long as they fit. In the narrow container the actions move under the title, left-aligned. The header follows its own width, not the viewport's.

Kyoto in autumn

Kyoto in autumn

Long titles

A long title wraps with balanced lines and never truncates, because the title is the page's name. The actions stay centred on the title's first line.

Ten days from Ho Chi Minh City through Tokyo, Kyoto, and Osaka with Brian Nguyen and the whole family

Content width

On a wide screen the title and actions sit in a row no wider than the page body's column, and the bottom rule still runs the full width.

Trips

Beside the sidebar

The sidebar names the app and the page header names the page. The wordmark, the title, and any actions sharing its row sit on one centre line. Collapse the sidebar and the wider pane lets the actions join the title's row.

Itinerary

Under the sidebar strip

On a narrow screen the sidebar becomes a strip across the top, and the page header sits beneath it with the same markup as beside the sidebar.

Guidelines

When to use

  • To name a page and hold the actions that act on all of it: the trips list with "Plan a new trip", a trip with "Share" and "Book stays".
  • At the top of the pane, inside main, on every page that has a title.

When not to use

  • Use Sidebar for the app's top bar and navigation. The sidebar is both, and the page header only names the page in the pane beside it.
  • Use Breadcrumb to show where the page sits in a hierarchy, because the header holds no trail.
  • Use Button for the actions on one card or one row, because the header is for the whole page.

Do and don’t

  • Do
    Keep the header to the title and the actions on the whole page. Put the description, the status, and where the page came from below it, as muted text in the page body.Every page then opens with the same heading, and the facts about one page read as its content rather than as chrome.
  • Do
    Give the header one primary action. A second action is a secondary button, and the rest go in a dropdown menu.One filled orange button says what the page is for. A row of equal buttons makes the traveller choose before they have read the page.
  • Don’t
    Repeat an empty page’s call to action in the header.The empty state owns the one action on an empty page, where the traveller is already looking. Show the header action once the page has content.
  • Don’t
    Resize the title for one page.Every page title is the same size, so the app speaks in one voice. A page that needs more emphasis gets it from its content.

Accessibility

The header has no states and no keyboard path of its own. The title is the page’s one h1, and Tab reaches the actions in the order you write them and nothing else. Nothing animates, including the actions wrapping: a layout change at a breakpoint is not feedback.

Place PageHeader inside main. A header outside it becomes a banner landmark and competes with the app shell’s own.

API

PageHeader

Renders a header around one row. Takes every <header> attribute.

PropTypeDefaultDescription
--page-header-max-widthCSS variablenoneCaps the row to the width of the page body’s column. Set it on the header or an ancestor.
--page-header-insetCSS variable0The side padding of the pane the header sits in. The header bleeds out by that much and pads back in, so the rule meets both edges.

PageHeaderTitle

The page’s one h1. Takes every <h1> attribute and has no size prop.

PropTypeDefaultDescription
childrenReactNodeRequiredThe page’s name.

PageHeaderActions takes every <div> attribute and holds the buttons that act on the whole page. It has no overflow menu: when the page has more actions than fit, pass a DropdownMenu as one of its children.

  • Sidebar

    The top bar and navigation beside the header.
  • Breadcrumb

    The trail of ancestors above a page title.
  • Button

    The control the header’s actions are made of.
  • Typography

    The heading face the title is set in.