Skip to main content
BEEQ Page title component overviewBEEQ Page title component overview

Page title component overview

Page titles introduce the current page or section and can pair the main heading with navigation, context, and related actions. Use them when the top of the page should confirm location immediately and keep the most relevant page-level controls nearby.
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.

​
Design guidelines

The page title component already renders the main title inside an h1. Use it for the primary page heading, not for lower-level section labels. Follow this sequence when you define a page title:
1

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.
2

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.
3

Keep actions focused

Only place page-level actions in the suffix area. If the title bar starts competing with the page content, reduce or relocate the actions.
Use bq-page-title once per page view and only at the top of the main content area. Placing it inside cards, panels, or repeating list items creates multiple h1 elements on the same page, which breaks heading hierarchy for screen readers.

​
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

  • A page must have only one h1. You must not place bq-page-title inside panels, cards, drawers, or any context where it would render alongside another h1.
  • For icon-only back and suffix buttons, you must set label on bq-button so the inner native button has an accessible name. You should set aria-hidden="true" on its decorative icon; a title or aria-label on the bq-icon host does not label the button.
  • bq-page-title renders the main title inside an h1, so the default slot must contain the primary heading for the page.
  • Back and suffix content are slotted, so their accessibility depends on what you place there. You must use real buttons or links with clear accessible names.
  • The subtitle is additional context, not a replacement for the title. The main heading must be understandable on its own.
  • If you use icon-only controls in back or suffix, they must have an accessible label and not just a visual symbol.

​
Keyboard interaction

No keyboard interaction: the component is not focusable. Controls you place in the back and suffix slots keep their own keyboard behavior.

​
Rules

​
API reference

​
Properties

​
Invalid combinations

No invalid prop combinations.

​
Slots

​
Shadow parts

​
CSS custom properties

Except for --bq-page-title--divider-color, 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. Values set on an ancestor are overridden by the component’s :host defaults.
Learn more about styling with shadow parts and CSS custom properties.

​
Resources

Interactive playground

Explore page title configurations in Storybook

Source code

View the component source on GitHub