Skip to content


Heading is used to create semantic heading hierarchies with flexible styles using Workbench’s design tokens.
Diagram defining Heading text above Subtext
Heading and its sub-components
Anatomy of the Heading component
HeadingPrimary heading wrapper component; can be used on its own
HeadingSubtextSmaller sub-heading to visually segment heading text into parts
HeadingTextOnly used alongside HeadingSubtext to create proper alignment
  • Headings are used to outline page structure
  • Structure your headings sequentially, starting with <h1>, followed by <h2>, etc.
  • Use the typePreset to override the default styles if they don’t work with the page UI

This example illustrates the default styles applied to each heading level.

Headings can be visually segmented with a smaller sub-heading sized at type token 200. Adding a sub-heading requires the use of HeadingSubtext and HeadingText.

This example illustrates proper heading hierarchy that would be easily understood by users of screen readers.

  • h1 Bill Pay
    • h2 How it works
      • h3 Add a vendor
      • h3 Set up a payment
      • h3 Schedule and pay
    • h2 Questions? Meet answers.
Headings divide content into different subjects.

Maintaining consecutive semantic page headings is the first priority, but the style can be adjusted to accommodate page design. See the Workbench typography page for available tokens and their values.

Add margin in a single direction: below the element. The marginBottom prop can be used to override the default of 2 spacing units, though we advise sticking with the defaults.

Headings can be used as links—just embed a Link within them.

React props
children  Required
-The content of the heading
level  Required
-The semantic level that will be applied to the heading. 1 will become <h1>, 2 will become <h2>, etc.
2The number of spacing units applied as margin-bottom
-Specifies the typographic design token used to override the default style of the heading provided with the level prop. See Workbench typography for further guidance.
React props
-The primary content of the heading; optional when not using HeadingSubtext
React props
-The content of the sub-heading
salt-800Token representing the color of the sub-heading
  • Headings are used to outline page content for screen readers, allowing users to navigate a page more efficiently
  • See guidelines from MDN regarding accessibility concernsExternal link when working with headings
Jordan demonstrates how screen readers interpret page headings.