Anatomy

Guidelines

When to use

The Heading is a typography component that uses the native HTML semantic headings <h1>-<h6>. Headings are important for establishing the overall content outline of the page. Use them to break page content up into named sections of different subtopics.

Heading and Text components

The Text component serves as a base typography component that the Heading and other components are extended from. When a heading is needed on the page, prefer to use the Heading component over Text.

Semantics vs style

A common mistake with headings is choosing them based on stylistic properties, such as using an <h1> when larger text is needed. Heading levels are styled differently to ensure page hierarchy is clear at a glance in most scenarios. However, styles such as font size and weight are not always directly correlated with heading level.

Be sure to never reach for a Heading based on appearance. If Heading styles must be changed, use the available component props and maintain proper heading level structure.

Best practices

Hierarchy

Adhere to logical heading order within pages. Never skip heading levels as this creates a confusing document outline for assistive technology users. For more information from an accessibility standpoint, see Heading level hierarchy under the Accessibility tab.

Single level 1

Each page should only have one level 1 (<h1>) heading. It serves as the primary title and top-level landmark for the entire page. The page's main sections use level 2, subsections under 2 use level 3, and so on.

Appearance

Color

Heading inherits text color options from the Text component. Headings use the base text color by default. If no color is explicitly set, the Heading will automatically adapt to the color most appropriate for the background. When manually changing Heading colors, be sure they adhere to semantic meaning and use.

Font family

Heading inherits font family options from the Text component. Sans-serif is the default. Monospace is used for Headings in code-related contexts.

Font style

Heading inherits font style options from the Text component. The Heading's font style is used to apply italic styling for visual emphasis without changing the Heading's semantic level.

Levels

Headings support six levels that map to the HTML tags <h1> through <h6>. Levels 1 through 4 have their own typography styles while levels 5 and 6 share the same styles.

Size

Heading inherits font size options from the Text component. If a font size different from the default styles is needed, use this option to manually adjust the size and keep proper heading levels intact.

Text

Heading typography can be changed to a predefined set of styles that affect the font size, font weight, line height, and letter spacing. For the full list of available values and their styles, see the Text section of the tokens page.

Weight

Heading inherits font weight options from the Text component. Font weight helps create a more prominent visual contrast between the Heading and surrounding text. If a font weight different from the default styles is needed, use this option to manually adjust the weight and keep proper heading levels intact.

Behaviors

Text wrapping

Headings will wrap automatically when the container resizes. The wrapping algorithm used specifically avoids widows, single words on the last line of text.

Content

Heading text should give the user enough context to understand the page and following supporting sections to come.

Six or fewer words is the ideal length. Longer Headings run the risk of obscuring key information that can be digested by a user at a glance. If a Heading requires more supplemental information, consider using a Paragraph below it.

Capitalization

Sentence case is preferred for Headings to maintain consistent writing across the application.

Punctuation

Omit punctuation from the Heading except in cases such as a confirmation modal that confirms an action.