Headings

A customized display and label heading, and H1-H6 styles utilizing USWDS theme tokens.

View in Figma

Usage

• Use heading display if you'd like the heading to be responsive between tablet and large tablet.
• Use the label modifier to introduce a label to your content that has a horizontal line under the section. This horizontal line extends the width of the page.
• Use Heading 1-Heading 6 (H1-H6) style headings to convey the content hierarchy of your page, as well as the semantic function of your text — this will help search engines to interpret the meaning and structure of your content.
  • Note: Ensure that your headings use relevant keywords and accurately describe the content they are introducing.
• Do not skip heading levels. For example, H2 headings should not be followed immediately by an H4 heading — make sure you use an H3 instead of an H4, in this case.
• Do not use text formatting (bold, italics, etc.) in place of headings.

Where to use

• Use headings on home and landing pages, as well as on inner pages.

When to use

• Any element can be styled as a heading by using the appropriate heading classes.
• Traditional heading elements (H1-H6) are designed to work best in the body of your content.
  • Use your H1 tag and class for your page title
  • Use your H2 tag and class to introduce major sections, and subsequent headings H3-H6 for subsections.
• When you need a heading to stand out, use a display heading — a larger, slightly more opinionated heading style.
  • Only consider applying the display class to your page title (H1), as this class will make your heading slightly larger than any element styled with an H1 class.

When to consider something else

• If an element is not styled using a heading class, the USWDS prose class can be used to style an element within blocks of text in a WYSIWYG where it’s more difficult to add custom classes to individual elements.

Best Practices

Character limits

Character limits are strongly recommended to ensure text is concise, scannable, and not visually distorted.

Character limits are based on best practices and when a line of text will be forced to wrap onto a second line of text on desktop.

• Keep H1’s between 60-70 characters long. This will help to avoid truncation of your title by search engines.
• Keep subheadings (H2-H6) under 50 characters long to create a content hierarchy that’s easy to scan by users, allowing them to find information quicker within your content.

Accessibility

Follow best practices regarding heading usage.

• Use only one H1 per page. The H1 heading is the most important ranking on the page and should be reserved for the page title to describe the page’s overall content.
• Avoid skipping heading levels. Skipping heading levels can cause confusion for those using the document outline or headings for in-page navigation. For example, H2 headings should not be followed immediately by an H4 heading.

For more on accessible best practices, refer to W3C guidance on headings.

<section class="usa-section">
    <div class="grid-container">
        <h1 class="nci-heading-display">nci-heading-display</h1>
        <h1 class="nci-heading-h1">nci-heading-h1</h1>
        <h2 class="nci-heading-h2">nci-heading-h2</h2>
        <h3 class="nci-heading-h3">nci-heading-h3</h3>
        <h4 class="nci-heading-h4">nci-heading-h4</h4>
        <h5 class="nci-heading-h5">nci-heading-h5</h5>
        <h6 class="nci-heading-h6">nci-heading-h6</h6>
        <h1 class="nci-heading-h1 nci-heading--label">
            nci-heading-h1 nci-heading--label
        </h1>
        <h2 class="nci-heading-h2 nci-heading--label">
            nci-heading-h2 nci-heading--label
        </h2>
        <h3 class="nci-heading-h3 nci-heading--label">
            nci-heading-h3 nci-heading--label
        </h3>
        <h4 class="nci-heading-h4 nci-heading--label">
            nci-heading-h4 nci-heading--label
        </h4>
        <h5 class="nci-heading-h5 nci-heading--label">
            nci-heading-h5 nci-heading--label
        </h5>
        <h6 class="nci-heading-h6 nci-heading--label">
            nci-heading-h6 nci-heading--label
        </h6>
    </div>
</section>

Package

Import this Sass partial into your stylesheet

@forward "nci-heading";