Skip to content
Mosaic
On this page

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 HeadingLevelProvider and useHeadingLevel

Practices

GuidancePractice
DoPass 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.
DoWrap a nested region in HeadingLevelProvider so headings inside it sit one level deeper.
Don’tPick 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

PropTypeDescription
sizeTypographySizeType scale step.Default: 'base'
colorTypographyColorText color token.Default: 'foreground'
levelHeadingLevelThe heading element, 1 to 6.Default: 2

HeadingLevelProvider

Sets the level useHeadingLevel returns below it. Renders no element.

PropTypeDescription
levelHeadingLevelThe level for its subtree.Default: one below the parent's, capped at `6`; the root is `2`

Examples

A nested heading

TSX
function SectionHeading({ children }: { children: React.ReactNode }) {
  return <Heading level={useHeadingLevel()}>{children}</Heading>;
}

<HeadingLevelProvider>
  <SectionHeading>Members</SectionHeading>
</HeadingLevelProvider>