The Heading component has been designed with accessibility in mind.

The component offers flexibility in terms of the HTML element used for the root node, the role attribute, and the level attribute. These properties allow for the creation of semantic and accessible headings.

All the props above are optional by default.

If they are not provided, the component will render a div element with no role or aria-level defined. It is not semantically wrong but won’t tell screen readers that the element is a heading. This should be used only for decorative purposes.

<Heading>Hello World!</Heading>

renders:

<div>Hello World!</div>

If the as prop is set to "div" (or undefined), the role prop is optional, but only accepts one possible value (if not undefined): "heading". If the role prop is set to "heading", the level prop must be defined as well. It will tell assistive technologies the level of the heading. The level prop must be a number between 1 and 6 and cannot be used if the role prop is not set to "heading".

<Heading as="div" role="heading" level={1}>
  Hello World!
</Heading>

renders:

<div role="heading" aria-level="1">Hello World!</div>

If the as prop is set to "h1", "h2", "h3", "h4", "h5", or "h6", the component will render the corresponding HTML element. In that case, the role and level props are not needed, since assistive technologies will recognize the element as a heading and its correct level automatically.

<Heading as="h1">Hello World!</Heading>

renders:

<h1>Hello World!</h1>

The dataA11ySection prop can be used to link the Heading to a SkipNavigation component.