Skip to content

Heading

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
ElementPurpose
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 the "spacing.200" spacing token, though we advise sticking with the defaults.

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

React props
NameTypeDefaultDescription
children  Required
ReactNode
-The content of the heading
level  Required
123456
-The semantic level that will be applied to the heading. 1 will become <h1>, 2 will become <h2>, etc.
marginBottom  
number
spacing.200The amount of spacing to apply as margin-bottom, expressed as a spacing token, such as spacing.200, or as a number representing a spacing unit.
typePreset  
725625525425325225125
-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
NameTypeDefaultDescription
children  
ReactNode
-The primary content of the heading; optional when not using HeadingSubtext
React props
NameTypeDefaultDescription
children  
ReactNode
-The content of the sub-heading
color  
ReactNode
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.