Heading
A themeable heading with size and color from the typography scale. Renders an h2 unless level says otherwise. HeadingLevelProvider sets the level for headings nested below it.
Use for
- a section or page title
- a heading whose level follows its nesting, with
HeadingLevelProvideranduseHeadingLevel
Practices
| Guidance | Practice |
|---|---|
| Do | Pass level={useHeadingLevel()} from a component rendered inside the HeadingLevelProvider when the heading should follow its nesting. Heading does not read the level from context on its own. |
| Do | Wrap a nested region in HeadingLevelProvider so headings inside it sit one level deeper. |
| Don’t | Pick level for its look. Use size for the look and level for the outline. |
API reference
Heading
Renders h1 to h6 and forwards its ref. Defaults can come from HeadingContext.
Slot: cl-heading
| Prop | Type | Description |
|---|---|---|
size | TypographySize | Type scale step.Default: 'base' |
color | TypographyColor | Text color token.Default: 'foreground' |
level | HeadingLevel | The heading element, 1 to 6.Default: 2 |
HeadingLevelProvider
Sets the level useHeadingLevel returns below it. Renders no element.
| Prop | Type | Description |
|---|---|---|
level | HeadingLevel | The level for its subtree.Default: one below the parent's, capped at `6`; the root is `2` |
Examples
A nested heading
function SectionHeading({ children }: { children: React.ReactNode }) {
return <Heading level={useHeadingLevel()}>{children}</Heading>;
}
<HeadingLevelProvider>
<SectionHeading>Members</SectionHeading>
</HeadingLevelProvider>