Heading

To add the Heading component to your app:

1
2
import { Heading } from '@forge/react';

Description

A heading is a typography component used to display text in different sizes and formats.

Props

Name	Type	Required	Description
`as`	`"h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "h6"`	Yes	Allows the component to be rendered as the specified DOM element.
`children`	`string`	No	The text of the heading.
`color`	`"color.text" \| "color.text.inverse" \| "color.text.warning.inverse"`	No	Text color of the heading. Defaults to "color.text". Use "color.text.inverse" for a light text color over a dark background. Use "color.text.warning.inverse" for a dark text color over a warning background.
`id`	`string`	No	Unique identifier for the heading DOM element.

Examples

Basic

The selected as will affect the final HTML element rendered in the DOM.

Example image of headings and their levels

1
2
import { Stack, Heading } from "@forge/react";

const HeadingBasicExample = () => {
  return (
    <Stack space="space.100">
      <Heading as="h1">h1</Heading>
      <Heading as="h2">h2</Heading>
      <Heading as="h3">h3</Heading>
      <Heading as="h4">h4</Heading>
      <Heading as="h5">h5</Heading>
      <Heading as="h6">h6</Heading>
    </Stack>
  );
};

Inverse

Set color to change the text color in the heading. Use color="color.text.inverse" for headings placed on a dark background or color="color.text.warning.inverse" for headings placed on a warning background for better color contrast.

Example image of heading with inverse color

1
2
import { Box, Heading, Stack } from "@forge/react";

const HeadingInverseExample = () => {
  return (
    <Stack space="space.200">
      <Box backgroundColor="color.background.brand.boldest">
        <Heading color="color.text.inverse" as="h1">
          Heading color can be manually inverted.
        </Heading>
      </Box>
      <Box backgroundColor="color.background.warning.bold">
        <Heading color="color.text.warning.inverse" as="h1">
          Heading color can be manually inverted.
        </Heading>
      </Box>
    </Stack>
  );
};

Accessibility considerations

When using the Heading component, we recommend keeping the following accessibility considerations in mind:

Consistent and clear hierarchy helps people navigate the page. Use headings and titles to outline the page so people can understand the page structure.
The most important heading has the rank 1 (<h1>), the least important heading has the rank 6 (<h6>). Headings with an equal or higher rank start a new section, headings with a lower rank start new subsections that are part of the higher ranked section. There should only be one rank 1 (<h1>) heading per page which explains the main purpose of the page.
Never skip lower heading levels. For example, a <h2> should not be followed by an <h4>. It should be followed by an <h3> (for a lower section in the hierarchy), or another <h2> (for a section of the same level of importance). It is ok to skip ranks when closing subsections, for instance, a <h2> beginning a new section, can follow a <h4> as it closes the previous section.
Text should be a minimum of 3:1 color contrast when it is 24px or larger, and 4.5:1 color contrast when it is under 24px. Use color="color.text.inverse" for headings placed on a dark surface for better color contrast.