Heading is a typographic component that introduces or summarizes sections of a web page. It’s used to control text’s appearance while still using the correct HTML tags behind the scenes.

• Heading is displayed on page load and appears at the top of a page or content section.
• If used, the heading description provides information about the content that Heading introduces. This could be a description of the content, short instructions for interacting with elements in the section, or secondary information that’s longer than a few words.

• For page, section, and subsection headings
• To structure web page content visually and semantically

• To style text that doesn’t introduce a section or subsection, because it adds <h> tags that identify the text as a section or subsection title

Heading has 3 types:

• Page headings introduce the web page. Use only 1 per page.
• Section headings title the top-level sections of a page. Use as many as necessary for your content.
• Subsection headings title the smaller content sections within a section. These should be used below section Headings only, not on their own. Use as many as necessary for your content.

Description

The description is short, supplemental text directly below a Heading. It’s ideal for content that would make the Heading too long and interfere with users’ ability to scan the page. Use only 1 description per Heading.

Tags

With Heading, CSS is used to control the text’s appearance separately from the HTML tags that structure the page correctly behind the scenes. This is important, because proper HTML structure:

• Makes web pages work correctly in browsers
• Sets the order for screen readers to announce content, which improves accessibility and ADA compliance

In your code, set Heading to use the HTML heading level that fits your content. Use these heading tag suggestions to create proper HTML structure:

• Page headings (only 1 per page): <h1> or <h2>
• Section headings: <h3>, <h4>, <h5>, <h6>
• Subsection headings: <h4>, <h5>, <h6>

No additional information for this component.

Heading goes above the content it introduces (or in some multi-column layouts, next to the top of this content). The page Heading can be part of a separate header section at the top of the page, while section and subsection Headings go directly above the content they introduce.

Never use a subsection Heading without a parent section Heading, because this negatively affects accessibility.

Heading

For easy scanning, keep the page heading (<h1> or <h2>) to approximately 24 characters.

Heading is used mainly for titles, so use title case for all Headings (“Patient Profile Details”", not “Patient profile details”).

Description

Keep the description to a sentence or less. For longer text, use a separate paragraph instead.

Use sentence case for description text (“Use this section to edit patient details”, not “Use This Section to Edit Patient Details”).

The semantic use of an HTML heading is separate from its visual styling. Heading tags (like <h1>, <h2>, <h3>, and so on) are used to define the structure of the page and organize the HTML correctly. Thanks to CSS, though, the heading can be displayed differently, in a way that suits the page visually, while still being semantically correct under the hood. The Heading component uses:

• The headingTag prop to set the correct semantic tag
• The variant prop to control the visual display

For tips on using heading levels correctly, see the W3C web accessibility tutorial page on headings.

Implementation links

Heading directory in Bitbucket

Implementation details

It is strongly recommended to familiarize yourself with the Forge source code. While this documentation is a best effort to document the intent and usage of a component, sometimes some features only become clear when looking at the source code. Also, looking at Forge's source code may help identify and fix bugs in either your application or Forge itself.

Storybook files

Forge maintains at least one storybook file per component. While the primary audience for these files is typically the Forge team, these storybook files may cover usages of the component not covered by a demo. The storybook for the latest version of forge can be found at go/forge-storybook-lts.

Testing library

Forge strongly encourages using testing-library to write tests for your application.

"The more your tests resemble the way your software is used, the more confidence they can give you."

If you're having trouble testing a Forge component using testing-library, it would be a good idea to see how Forge tests its own components. For the most part, Forge tries to use screen.getByRole as much as it can, as that API provides the best feedback on a11y compliance. Forge discourages the use of document.querySelector and screen.getByTestId as both APIs encourage using implementation details to test your component, and discourage adding roles to your component.

With that being said, many of Forge's components were not built with accessibility in mind. These components do break the recommendations listed above.

In Nimbus applications

athenaOne serves the Forge bundle independently from your application's bundle. Importing Forge components directly from '@athena/forge' takes advantage of this feature.

import { Heading } from '@athena/forge'

In standalone applications

Importing components using the exact path to the module takes advantage of webpack's tree shaking feature. Webpack will include only that module and its dependencies.

import Heading from '@athena/forge/Heading';

To use this import guidance, Typescript applications must use typescript >= 4.7.3, and should add this setting to their tsconfig.json file:

{
  "compilerOptions": {
    "moduleResolution": "Node16",
  }
}

If this setting doesn't work for your application, use this import statement instead:

import Heading from '@athena/forge/dist/Heading';