bq-page-title is slot-based. Use the default slot for the main title, back for navigation, sub-title for supporting text, and suffix for related actions.When to use
Use page titles when
- The page needs a clear H1-level title
- People benefit from a back action or supporting context near the heading
- Related page-level actions should stay close to the title instead of being scattered across the layout
- The page should immediately confirm where the user is
Do not use page titles when
- A smaller section heading is enough
- Several competing actions would overload the title area
- The title repeats information that is already obvious from surrounding context
- Extra supporting text would make the top of the page harder to scan
Patterns
The common page-title compositions build from the same base component.Title only
The simplest pattern, used when the page heading alone provides enough context.
Title with back navigation
Useful for nested screens, sub-pages, or multi-step flows where users may need to return to a previous page.
Title with subtitle
Adds supporting context when the page needs a little more explanation than the main title alone can provide.
Title with actions
Keeps page-level actions such as edit, save, or download close to the heading they affect.
Anatomy
Page titles combine a required H1 with optional supporting slots. This makes it easy to keep navigation, context, and related actions grouped in one predictable place.| Part | Element | Description |
|---|---|---|
| 1 | Back | Optional slot used for back navigation |
| 2 | Title | The main page heading rendered as an h1 |
| 3 | Suffix | Optional slot for page-level actions |
| 4 | Sub-title | Optional supporting text shown below the title row |
Design guidelines
The page title component already renders the main title inside anh1. Use it for the primary page heading, not for lower-level section labels.
Follow this sequence when you define a page title:
Write the title first
Start with the shortest heading that clearly identifies the page. The main title should confirm location immediately without sounding like a sentence.
Add context only when needed
Use the subtitle for clarifying details that help users act or understand scope. If the subtitle repeats the title, remove it.
Usage
Default
Use the default composition when the title alone provides enough context.Title + Back
Use a back action when the page is part of a flow or nested navigation path.Title + Back + Subtitle
Add a subtitle when people need a little more context before acting.Options
Title + Actions
Use the suffix slot for page-level actions when back navigation is not relevant — for example, a top-level list page with a primary action.Title + Back + Subtitle + Actions
Use the suffix slot when the title area needs page-level actions such as edit or download.Best practices
DoUse the page title for the main page heading so people can understand location immediately.
Don’tDo not use the component for lower-level section labels that should remain inside the page content.
DoKeep the title concise and use the subtitle only when it adds real context.
Don’tDo not repeat the same message across the title and subtitle or turn the header into a paragraph.
DoUse the back slot for clear return navigation when the page belongs to a nested flow.
Don’tDo not add decorative icons that look like actions but have no clear purpose.
DoKeep suffix actions limited to the page-level controls users are most likely to need right away.
Don’tDo not overload the title area with too many actions or controls that compete with the heading itself.
Accessibility
- Only one
h1may exist per page. Do not placebq-page-titleinside panels, cards, drawers, or any context where it would render alongside anotherh1. - When using an icon-only back button, add
role="img"and a descriptivetitleattribute tobq-icon(e.g.,title="Navigate back to the previous page") so screen readers announce the icon’s purpose rather than its name. bq-page-titlerenders the main title inside anh1, so the default slot should contain the primary heading for the page.- Back and suffix content are slotted, so their accessibility depends on what you place there. Use real buttons or links with clear accessible names.
- The subtitle is additional context, not a replacement for the title. Keep the main heading understandable on its own.
- If you use icon-only controls in
backorsuffix, make sure they have an accessible label and not just a visual symbol.
API reference
Properties
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
| None | None | This component does not expose public properties | — | — |
Slots
| Slot | Description |
|---|---|
| (default) | The main page title content |
back | Optional back navigation action |
sub-title | Optional supporting text shown below the title row |
suffix | Optional trailing actions shown beside the title |
Shadow parts
| Part | Description |
|---|---|
base | The inner container that holds the full page title component |
back | The container for the back slot |
content | The main title and subtitle container |
title-suffix | The row containing the title and suffix |
title | The h1 title element |
suffix | The container for the suffix slot |
sub-title | The container for the subtitle slot |
CSS custom properties
The CSS custom properties for
bq-page-title use shorthand names (e.g., --paddingY, --title-fontWeight) rather than the --bq-* prefix convention used by other BEEQ components. Set these variables directly on the bq-page-title element or a wrapping ancestor.Resources
Interactive playground
Explore page title configurations in Storybook
Source code
View the component source on GitHub