;
};
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.
The simplest pattern, used when the page heading alone provides enough context.
Useful for nested screens, sub-pages, or multi-step flows where users may need to return to a previous page.
Adds supporting context when the page needs a little more explanation than the main title alone can provide.
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 an `h1`. Use it for the primary page heading, not for lower-level section labels.
Follow this sequence when you define a page title:
Start with the shortest heading that clearly identifies the page. The main title should confirm location immediately without sounding like a sentence.
Use the subtitle for clarifying details that help users act or understand scope. If the subtitle repeats the title, remove it.
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.
bq-page-title {
inline-size: 100% !important;
}
Title
`}
>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
Title
```
```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqPageTitle } from "@beeq/react";
Title
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqPageTitle } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqPageTitle],
template: `
Title
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
Title
```
### Title + Back
Use a back action when the page is part of a flow or nested navigation path.
bq-page-title {
inline-size: 100% !important;
}
Title
`}
>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
Title
```
```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqButton, BqIcon, BqPageTitle } from "@beeq/react";
Title
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqPageTitle, BqButton, BqIcon } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqPageTitle, BqButton, BqIcon],
template: `
Title
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
Title
```
### Title + Back + Subtitle
Add a subtitle when people need a little more context before acting.
bq-page-title {
inline-size: 100% !important;
}
Title
Sub-title
`}
>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
Title
Sub-title
```
```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqButton, BqIcon, BqPageTitle } from "@beeq/react";
Title
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
Title
Sub-title
```
## 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.
bq-page-title {
inline-size: 100% !important;
& [slot="suffix"] {
display: flex;
align-items: center;
flex-grow: 1;
justify-content: flex-end;
}
}
Dashboard users
Add user
`}
>
```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
Dashboard users
```
### Title + Back + Subtitle + Actions
Use the suffix slot when the title area needs page-level actions such as edit or download.
bq-page-title {
inline-size: 100% !important;
& [slot="suffix"] {
display: flex;
flex-grow: 1;
justify-content: end;
}
& [slot="suffix"] bq-button {
padding: var(--bq-spacing-xs2);
}
}
Title
```
## Best practices
Do
Use the page title for the main page heading so people can understand location immediately.
Don't
Do not use the component for lower-level section labels that should remain inside the page content.
Do
Keep the title concise and use the subtitle only when it adds real context.
Don't
Do not repeat the same message across the title and subtitle or turn the header into a paragraph.
Do
Use the back slot for clear return navigation when the page belongs to a nested flow.
Don't
Do not add decorative icons that look like actions but have no clear purpose.
Do
Keep suffix actions limited to the page-level controls users are most likely to need right away.
Don't
Do not overload the title area with too many actions or controls that compete with the heading itself.
## Accessibility
* Only one `h1` may exist per page. Do not place `bq-page-title` inside panels, cards, drawers, or any context where it would render alongside another `h1`.
* When using an icon-only back button, add `role="img"` and a descriptive `title` attribute to `bq-icon` (e.g., `title="Navigate back to the previous page"`) so screen readers announce the icon's purpose rather than its name.
* `bq-page-title` renders the main title inside an `h1`, 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 `back` or `suffix`, 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
| Variable | Description | Default |
| --------------------------- | ------------------------------------------ | ------------------------------------- |
| `--paddingY` | Vertical padding of the page title wrapper | `var(--bq-spacing-xl)` |
| `--subtitle-borderBlockEnd` | Border below the page title area | `1px solid var(--bq-stroke--primary)` |
| `--subtitle-fontWeight` | Subtitle font weight | `var(--bq-font-weight--medium)` |
| `--subtitle-textColor` | Subtitle text color | `var(--bq-text--secondary)` |
| `--subtitle-textSize` | Subtitle font size | `var(--bq-font-size--l)` |
| `--title-fontWeight` | Title font weight | `var(--bq-font-weight--bold)` |
| `--title-lineHeight` | Title line height | `var(--bq-font-line-height--regular)` |
| `--title-textColor` | Title text color | `var(--bq-text--primary)` |
| `--title-textSize` | Title font size | `var(--bq-font-size--xxl)` |
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.
Learn more about [styling with shadow parts](/guides/styles#component-shadow-dom-parts) and [CSS custom properties](/guides/styles#global-css-custom-properties).
## Resources
Explore page title configurations in Storybook
View the component source on GitHub
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.