Page Header
The Page Header is a layout component that provides a consistent heading area for pages. It supports breadcrumbs, icons, titles, subtitles, and action slots, adapting its grid layout automatically based on the content provided.
When to use
- As the top section of any page to display the page title
- To provide navigation context via breadcrumbs
- To show a visual icon representing the page category
- To add action buttons (e.g., "Edit", "Export") aligned to the right
- As a hero banner on landing pages with a 2-column layout
When not to use
- For card headers or section headings within a page (use standard headings)
- For navigation bars (use NavBar)
Component Anatomy
A QPageHeader consists of:
- Breadcrumb area (optional): Spans the full width above the content row
- Icon (optional): A colored square with an icon representing the page topic
- Content area: Contains the title (required) and an optional subtitle
- Actions slot (optional): Right-aligned area for buttons or controls
- Hero layout (variant): 2-column layout with content on the left and image slot on the right
Variants
The component supports 4 main variants based on the combination of props.
| Variant | Usage | Composition |
|---|---|---|
| Hero | Home / landing pages | Large title + subtitle + description + image, 2 columns |
| Full | Component pages | Breadcrumb + icon + title + subtitle |
| Icon only | Category pages with icon | Icon + title + subtitle, no breadcrumb |
| Minimal | Root sections | Title only, no icon or breadcrumb |
Minimal (title only)
Used on root section pages like /get-started, /foundations.
With subtitle
Icon only
Used on category pages that have an icon but no breadcrumb navigation.
Full (breadcrumb + icon)
Used on component detail pages like /components/buttons.
Hero
Used on home or landing pages with a 2-column layout, large title, and image.
With actions
Any variant can include an actions slot for right-aligned buttons.
Title size
Use the title-size prop to change the heading size. Accepts Bootstrap display classes: display-3, display-4, display-5, display-6 (default).
Props
| Prop | Type | Default | Description |
|---|---|---|---|
title | string | (required) | The main heading text |
subtitle | string | undefined | Secondary text below the title |
description | string | undefined | Longer description (hero variant) |
icon | string | undefined | Bootstrap icon class (e.g., "bi-palette2") |
iconBgColor | string | "var(--q-primary-lighter)" | Background color for the icon area |
breadcrumbs | Array<{ text, to?, href?, active? }> | undefined | Breadcrumb navigation items |
titleSize | string | "display-6" | Bootstrap display class for heading size |
variant | "default" | "hero" | "default" | Layout variant |
Slots
| Slot | Description |
|---|---|
default | Content rendered inside the content area, below title/subtitle |
breadcrumb | Override the default QBreadcrumb rendering |
icon | Override the default icon rendering |
actions | Right-aligned action area (buttons, controls) |
image | Image area for the hero variant (right column) |
Accessibility
- The title renders as an
<h1>element for correct heading hierarchy - Breadcrumb navigation uses the standard QBreadcrumb accessible pattern
- Icon is decorative and does not require alt text
- Action buttons should have meaningful labels