Page Header

The page header provides consistent page-level context and navigation on a brand-blue background with inverted text. It includes breadcrumbs, a title, an optional kicker, and optional action buttons built as an fd-button-group of shared fd-button actions.

Component

Use fd-page-header at the top of each page to establish wayfinding context with breadcrumbs, the page's primary heading, and optional page-level actions.

When to use

• Every content page needs a consistent heading region — The page header provides a shared layout for the <h1>, breadcrumbs, and actions so teams don't build this from scratch.
• The page sits within a multi-level site hierarchy — Breadcrumbs show the user where they are and how to navigate up.
• The page has a content type or category — Use the kicker to surface a short label like "Consumer Resources" or "News" above the title.
• The page needs page-level actions — Use the actions slot for buttons like Print, Share, or Export that apply to the whole page.

When not to use

• Don't use it for section headings within a page — Use native <h2>–<h6> elements for in-page sections.
• Don't use it as a replacement for the global header — fd-page-header sits below fd-global-header, inside <main>.
• Don't use it for hero banners or marketing blocks — This component is for structured page context, not promotional content.
• Don't use it for standalone breadcrumbs without a title — The component requires a heading to render.

Examples

Full page header with breadcrumbs, kicker, title, and actions. The Playground story in Storybook provides interactive controls for all properties. View in Storybook →

fd-page-header is one of the components that consumes the shared Page Shell contract directly. Its inner wrapper aligns to --fdic-layout-shell-max-width, switches to the shared tablet and mobile gutters at the canonical shell ranges, and uses --fdic-layout-section-block-padding for its default vertical spacing.

Basic usage

<fd-page-header heading="Deposit Insurance"></fd-page-header>

With breadcrumbs

const header = document.querySelector('fd-page-header');
header.breadcrumbs = [
  { label: 'Home', href: '/' },
  { label: 'Consumer Resources', href: '/resources' },
  { label: 'Deposit Insurance', href: '/resources/deposit-insurance' },
];

The last breadcrumb item renders as a non-interactive <span> with aria-current="page". All preceding items render as links.

On narrow containers (640px and below), breadcrumbs collapse to a single Back link that points to the immediate parent breadcrumb. Keep the parent breadcrumb label clear because it becomes the link's accessible name (Back to …) in the mobile presentation.

With kicker and actions

<fd-page-header
  heading="Quarterly Banking Profile"
  kicker="Analysis"
>
  <fd-button-group slot="actions" label="Page actions">
    <fd-button variant="subtle">
      <fd-icon slot="icon-start" name="share-fat"></fd-icon>
      Share
    </fd-button>
    <fd-button variant="subtle">
      <fd-icon slot="icon-start" name="plus"></fd-icon>
      Add to Quick Links
    </fd-button>
  </fd-button-group>
</fd-page-header>

Page header buttons

Use an fd-button-group in the actions slot, and use fd-button with variant="subtle" for each action inside the group. The page header action area supplies the inverted text and interaction tokens needed for the brand-blue background. If you need a compatibility wrapper, fd-page-header-button now renders an internal subtle fd-button.

<fd-button-group label="Page actions">
  <fd-button variant="subtle">
    <fd-icon slot="icon-start" name="share-fat"></fd-icon>
    Share
  </fd-button>
</fd-button-group>

Properties

Name	Type	Default	Description
heading	string	``	Page heading text rendered as an <h1> inside the component.
kicker	string	``	Optional description displayed below the title. Rendered at weight 450, 20px desktop / 18px mobile.
breadcrumbs	FdPageHeaderBreadcrumb[]	[]	Ordered breadcrumb trail. Each item has label and href. The last item renders as the current page with aria-current="page".
breadcrumb-label	string	"Breadcrumbs"	Accessible label for the breadcrumb <nav> landmark.

Slots

Name	Description
actions	Optional action buttons or links displayed alongside the page title.

CSS custom properties

Name	Default	Description
--fd-page-header-bg		Section background color.
--fd-page-header-text-color		Text color for all content inside the header.
--fd-page-header-max-width		Maximum inline size of the page header content area. Defaults to the shared page-shell width contract.
--fd-page-header-padding-block		Block (vertical) padding on desktop. Defaults to the shared major-section spacing token.
--fd-page-header-padding-inline		Inline (horizontal) padding on desktop. Defaults to the shared page-shell gutter token.

Shadow parts

Name	Description
base	Root container element.
breadcrumbs	Breadcrumb <nav> element.
breadcrumb-back-link	Mobile Back link rendered from the immediate parent breadcrumb.
nameplate	Container for title and kicker.
kicker	Kicker/eyebrow text element.
title	<h1> heading element.
actions	Actions container with the actions slot.

Best practices

Do

• Place fd-page-header as the first element inside <main>.
• Keep it aligned with the rest of the page shell. If adjacent top-level sections also use the shared shell contract, prefer leaving --fd-page-header-max-width and the inline padding tokens at their defaults.
• fd-page-header switches to the shared tablet gutter before the mobile breakpoint so it stays aligned with shell-based content through intermediate viewport widths.
• Use heading for the page's primary heading — the component renders it as <h1>.
• Keep breadcrumb labels short and descriptive. Match them to the actual page titles they link to.
• Mark the last breadcrumb item's href to match the current page URL, even though the component renders it as a non-interactive span.
• Put the immediate parent page directly before the current page in the breadcrumbs array. On mobile, that parent becomes the single Back link destination.
• Use the kicker for short content-type labels, not full sentences.

Don't

• Don't add a separate <h1> elsewhere on the page — the component already renders one.
• Don't slot multiple loose buttons side by side. Use fd-button-group so related page actions share one layout wrapper.
• Don't mix button variants in the actions group. Keep page-level utility actions on fd-button variant="subtle" for a consistent hierarchy.
• Don't use the actions slot for primary navigation — it's for page-level utility actions.
• Don't include more than 5 breadcrumb levels — keep the hierarchy shallow and scannable. Deep trails still collapse to the immediate parent on mobile.

Content guidelines

• Heading: Use the full page title. Avoid abbreviations unless the abbreviation is more recognizable than the full name.
• Kicker: Use a consistent content-type label across pages in the same category. Examples: "Consumer Resources", "News", "Analysis", "Regulation".
• Breadcrumbs: Match labels to the destination page titles. Use "Home" for the root.
• Actions: Use short, action-oriented labels. Prefer verbs: "Print", "Share", "Export".

Accessibility

• The breadcrumb trail renders inside a <nav> landmark with aria-label="Breadcrumbs" (customizable via the breadcrumb-label property).
• Breadcrumbs use a semantic <ol> to convey ordered hierarchy to assistive technology.
• The last breadcrumb item has aria-current="page" so screen readers announce it as the current location.
• On narrow containers, the visible Back link navigates to the immediate parent breadcrumb and uses aria-label="Back to …" for context. The full trail remains the source hierarchy for wider layouts.
• Separator icons between breadcrumbs are aria-hidden="true" and excluded from the accessible name.
• The heading renders as <h1> — do not add another <h1> on the same page.
• All interactive elements (breadcrumb links, action buttons) have visible focus indicators using the standard FDIC focus ring pattern.
• The component uses plain tab order — no custom keyboard navigation is needed.
• White text on the brand-blue background (#0d6191) exceeds WCAG AA contrast requirements (4.62:1).
• fd-button-group remains a layout wrapper in the actions slot; it does not change button semantics.
• fd-button variant="subtle" inside the actions group keeps the standard FDIC focus ring and uses inverted text tokens supplied by the page-header action region.
• In forced-colors mode, the brand-blue background is replaced with Canvas, text uses CanvasText, breadcrumb links use LinkText, and the section gets a bottom border for visual separation.
• In print, breadcrumbs and actions are hidden; the background is removed and text is printed in black.

Known limitations

• No data fetching — The component does not fetch breadcrumb data. Pass the breadcrumbs array from your application.
• No routing integration — Breadcrumb links use standard <a> elements. For SPA routing, intercept clicks in your framework's router.
• Mobile back-link destination is derived — The component derives the mobile Back link from the immediate parent breadcrumb. It does not support choosing a different ancestor level in v1.
• Heading level is fixed at <h1> — The component always renders an <h1>. If you need a different heading level, use native HTML instead.

Related components

• fd-global-header — Site-level header with navigation, search, and branding. Place fd-page-header below it, inside <main>.
• fd-hero — Use Hero when the page needs strong visual framing or a campaign-style introduction rather than breadcrumbs and structured hierarchy.
• fd-button-group — Use this in the actions slot to cluster related page-level utility actions.
• fd-button — Shared button component used inside the page-header action group.
• fd-icon — Used inside page-header action buttons. Icons come from the Phosphor registry.
• Page Shell — Shared width and responsive gutter contract for shell-aligned components and top-level sections.