Heading
A typographic component for titles that describe the main sections of an interface and how they hierarchically relate to each other.
Hierarchy
The hierarchy of heading levels available. In a design, headings won't always start from the largest and descend incrementally to the smallest, but semantically headings should be ordered this way. See the for more info.
Editable example
Best practices
- Avoid manually applying a
className
to override thecolor
,text-align
,font-weight
, orfont-size
. All of these parameters are handled by the component's props. - Heading components do not contain any inherent spacing. It's recommended to use the layout to determine spacing. Rather than applying a
className
and applying amargin
orpadding
to the text, use the containing element withdisplay: flex;
ordisplay: grid;
andgap
to determine spacing.
Element
Determines the underlying HTML
element rendered by the component. By default headings will render an element matching the level prop. So <Heading level="1">
will render an <h1>
. Be careful to use the correct element for the page context. See the for more info.
Editable example
Secondary
Secondary headings should be used to reduce emphasis on the heading with a fainter text color.
Editable example
Strong
Use the strong
prop to make headings appear bolder for emphasis. Note that this does not change the rendered HTML
element to a <strong>
tag.
Editable example
Alignment
Alignment can be set using the align
prop. Defaults to left aligned.
Editable example
Theme
Change the theme for headings to match their context.
Editable example
Accessibility
- Headings should always start from
<h1>
and descend in a logical order for each level down in the hierarchy without skipping any levels. That means even if a design has alevel="2"
heading as the first and largest heading on the page, it should be set to render an<h1>
element withelement="h1"
. If the design then steps down to alevel="3"
heading for headings below that level, they should be set toelement="h2"
. This makes it easier for users of assistive technology to jump between sections of the page using the heading hierarchy. - If a heading is not intended to act as a descriptor for a section of the page (i.e. is being used cosmetically and not semantically) switch out the element to match its lack of semantics e.g.
element="div"
- Avoid manually overriding the text color and instead use the
secondary
prop to dim less important text and thetheme
prop to use appropriate colors for a light or dark theme. The default colors assigned for each of these props have been chosen to meet the WCAG AA minimum contrast ratio.
Figma text styles
There's an explicit mapping of text styles to React components for the standard and strong variants. Figma doesn't store text color or alignment in text styles though, so those variants need to be inferred. Rule of thumb is if the heading color is Slate
in Figma, it should be the secondary
variant.
Figma text style | React component |
---|---|
Heading/Level 1 | <Heading level="1"> |
Heading/Level 2 | <Heading level="2"> |
Heading/Level 3 | <Heading level="3"> |
Heading/Level 4 | <Heading level="4"> |
Heading/Level 5 | <Heading level="5"> |
Heading/Strong/Level 1 | <Heading strong level="1"> |
Heading/Strong/Level 2 | <Heading strong level="2"> |
Heading/Strong/Level 3 | <Heading strong level="3"> |
Heading/Strong/Level 4 | <Heading strong level="4"> |
Heading/Strong/Level 5 | <Heading strong level="5"> |