Skip to content
Gusto’s condensed “G” logoWorkbench

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 2 spacing units, though we advise sticking with the defaults.

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

React props
NameTypeDefaultDescription
children  RequiredReactNodeThe content of the heading
level  Required123456The semantic level that will be applied to the heading. 1 will become <h1>, 2 will become <h2>, etc.
marginBottom  number2The number of spacing units applied as margin-bottom
typePreset  725625525425325225125Specifies 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  ReactNodeThe primary content of the heading; optional when not using HeadingSubtext
React props
NameTypeDefaultDescription
children  ReactNodeThe content of the sub-heading
color  ReactNodesalt-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.