Skip to main content
Bedrock Design System

Heading

A typography component to render headings at various levels and styles.

UsagePermalink to: Usage

Heading is a collection of typography components that are used to display headings and titles on a page.It does not render as a specific HTML element by default, but can be rendered as a <h1> to <h6> via the level prop.

Make sure headings follow a logical hierarchy on a page, both visually and semantically.

When to usePermalink to: When to use

  • Use it for titles and subtitles

When not to usePermalink to: When not to use

  • Do not use it for non-heading content, eg. bodies of text

AccessibilityPermalink to: Accessibility

It's important to maintain a logical hierarchy of headings on a page for both visual and semantic reasons.

Guidelines:

  • Only one <h1> on each page
  • Should be sequential and reflect the sections of a page
  • Keep headings short and concise

To quickly identify and fix heading hierarchy issues, you can use browser extensions or bookmarklets eg. h123(external link).

An example of a good heading hierarchy:

<section>
  <Heading1 level={1}>Page title</Heading1>
  <section>
    <Heading2 level={2}>Page section 1</Heading2>
    <section>
      <Heading4 level={3}>Subtitle</Heading4>
      <Heading4 level={3}>Subtitle</Heading4>
    </section>
  </section>
  <section>
    <Heading2 level={2}>Page section 2</Heading2>
    <section>
      <Heading4 level={3}>Subtitle</Heading4>
      <Heading4 level={3}>Subtitle</Heading4>
    </section>
  </section>
</section>

Notice how the visual headings skips a level in the page sections, but the semantic level props are sequential - this is perfectly fine, if the visual hierarchy is consistent.

An example of a bad heading hierarchy:

<section>
  <Heading1 level={1}>Page title</Heading1>
  <section>
    <Heading2 level={2}>Page section 1</Heading2>
    <section>
      <Heading4 level={1}>Subtitle</Heading4>
      <Heading4 level={1}>Subtitle</Heading4>
    </section>
  </section>
  <section>
    <Heading2 level={2}>Page section 2</Heading2>
    <section>
      <Heading4 level={4}>Subtitle</Heading4>
      <Heading4 level={4}>Subtitle</Heading4>
    </section>
  </section>
</section>

Notice how the first section uses level={1} inside a level={2} section (goes up one level), and the second section uses level={4} inside a level={2} section (skips a level). This would create a bad semantic page hierarchy.

ExamplesPermalink to: Examples

The Heading component comes with several variants to accommodate the visual hierarchy of a page. For semantic hierarchy, see Accessibility.

Open
import {
  Hero,
  Heading1,
  Heading2,
  Heading3,
  Heading4,
  Heading5,
} from "@peakon/bedrock/react/typography";
import { Stack } from "@peakon/bedrock/react/layout";

function Snippet() {
  return (
    <Stack spacing={8}>
      <Hero level={1}>Hero heading</Hero>
      <Heading1 level={2}>Heading 1</Heading1>
      <Heading2 level={3}>Heading 2</Heading2>
      <Heading3 level={4}>Heading 3</Heading3>
      <Heading4 level={5}>Heading 4</Heading4>
      <Heading5 level={6}>Heading 5</Heading5>
    </Stack>
  );
}

Text colorPermalink to: Text color

The textColor prop controls the color of the heading.

Open
import { Heading4 } from "@peakon/bedrock/react/typography";
import { Stack } from "@peakon/bedrock/react/layout";

function Snippet() {
  return (
    <Stack spacing={8}>
      <Heading4 level={2} textColor="heading">
        Heading color (default)
      </Heading4>
      <Heading4 level={2} textColor="body">
        Body color
      </Heading4>
      <Heading4 level={2} textColor="hint">
        Hint color
      </Heading4>
      <Heading4 level={2} textColor="disabled">
        Disabled color
      </Heading4>
      <div style={{ backgroundColor: "black", padding: "8px" }}>
        <Heading4 level={2} textColor="inverted">
          Inverted color
        </Heading4>
      </div>
      <Heading4 level={2} textColor="inherit">
        Inherit color (from parent)
      </Heading4>
    </Stack>
  );
}

Text alignmentPermalink to: Text alignment

Heading will inherit text alignment from their parent, but can be overwritten with the textAlign prop.

Open
import { Heading4 } from "@peakon/bedrock/react/typography";

function Snippet() {
  return (
    <div style={{ display: "flex", flexDirection: "column" }}>
      <Heading4 level={2} textAlign="start">
        Heading aligned to start
      </Heading4>
      <Heading4 level={2} textAlign="center">
        Heading aligned center
      </Heading4>
      <Heading4 level={2} textAlign="end">
        Heading aligned to end
      </Heading4>
    </div>
  );
}

Props TablePermalink to: Props Table

Props extend from HTML Heading Element(external link), with the omission of className and style

NameTypeDescriptionDefaultRequired
refany

Forwards a ref to the Heading.

—No
level1 | 2 | 3 | 4 | 5 | 6

What HTML heading element to use, <h1> through <h6>.

—Yes
textAlignstart | center | end

How the text should align (will inherit as default).

—No
textColorinherit | heading | body | hint | inverted | disabled

Controls the color of the heading.

headingNo