Heading
A document heading with a visual typography role independent of its level.
On this page
Voyage planning
Before departure
Review the route and prepare the vessel.
Vessel notes
Lines, fenders and shore power.
Code
import { Stack } from "@bosunkit/components/stack";
import { Text } from "@bosunkit/components/text";
import { Heading } from "@bosunkit/components/heading";
import type { ReactElement } from "react";
export const description: string =
"The page title uses the page role. Both section titles are level two, with different visual roles for their content.";
export default function Example(): ReactElement {
return (
<Stack space="lg">
<Heading level={1}>Voyage planning</Heading>
<section>
<Stack space="sm">
<Heading level={2} variant="heading-section">Before departure</Heading>
<Text>Review the route and prepare the vessel.</Text>
</Stack>
</section>
<section>
<Stack space="sm">
<Heading level={2} variant="heading-component">Vessel notes</Heading>
<Text variant="caption" color="text-dim">Lines, fenders and shore power.</Text>
</Stack>
</section>
</Stack>
);
}
level selects the heading element for the document outline. variant selects its visual
typography role: heading-page, heading-section or heading-component.
A compact panel can use level={2} and variant="heading-component" together.
Without an explicit variant, level one uses page, level two uses section and levels three through six use component. Each role sets the font, size, weight and line height for the presentation scope. Choose levels in document order, without skipping levels to obtain a different font size.
Voyage planning
Before departure
Review the route and prepare the vessel.
Vessel notes
Lines, fenders and shore power.
Code
import { Stack } from "@bosunkit/components/stack";
import { Text } from "@bosunkit/components/text";
import { Heading } from "@bosunkit/components/heading";
import type { ReactElement } from "react";
export const description: string =
"The page title uses the page role. Both section titles are level two, with different visual roles for their content.";
export default function Example(): ReactElement {
return (
<Stack space="lg">
<Heading level={1}>Voyage planning</Heading>
<section>
<Stack space="sm">
<Heading level={2} variant="heading-section">Before departure</Heading>
<Text>Review the route and prepare the vessel.</Text>
</Stack>
</section>
<section>
<Stack space="sm">
<Heading level={2} variant="heading-component">Vessel notes</Heading>
<Text variant="caption" color="text-dim">Lines, fenders and shore power.</Text>
</Stack>
</section>
</Stack>
);
}
Structure survives visual density
Choose the heading level from the surrounding document before choosing its variant. A report panel inside a section can use a compact heading role while remaining one level below that section. Do not restart every card at level one or skip levels to get a smaller font.
Keep a heading meaningful when read in a screen reader's heading list. Put dates, badges and actions beside it as supporting content rather than encoding them into a screenshot. The page shell already supplies a document title; an embedded report block should not repeat it as another page heading.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| childrenrequired | ReactNode | – | The heading's text. |
| levelrequired | HeadingLevel | – | The document heading level (h1..h6); choose this for the page structure. |
| variant | HeadingRole | undefined | – | Visual role, independent of level. Defaults: level 1 page, level 2 section, levels 3–6 component. |
| as | PrimitiveElement | undefined | – | The element to render; the level's heading element unless set. |
| className | string | undefined | – | Classes added to the element's own. |
| testId | string | undefined | – | Becomes data-testid on the element. |
Related
- Typography: the shared role definitions and presentation sizes
- Text: body text, labels, captions and code