Skip to contentSkip to navigationSkip to topbar
Paste
FigmaStar

Heading

A Heading is text that gives hierarchical structure to a page.

Version 11.0.0
Github
Storybook
Component preview theme
<Heading as="h1" variant="heading10" marginBottom="space0">

  Black lives matter

</Heading>

Guidelines

Guidelines page anchor

Headings are words or phrases that are intended to introduce sections of content. Headings are often used for page headings, as well as content subsections within the page.

About Heading

About Heading page anchor

Headings should allow users to easily distinguish content sections on the page.

  • Headings can have multiple levels of depth to help organize content.
  • Heading types provide specific styles to the font-size, font-weight, and line-height of the text to create hierarchy that allow users to easily scan pages and content.
  • Headings should be used with intention that maintains a coherent document outline.
  • Don’t use heading tags to resize text. Instead use the <Text> primitive.
  • Don’t skip headline levels. Always start with <h1>, <h2>, and so on. In other words, don't use an <h3> unless preceded by an <h2>.
  • There can only be one <h1> tag per page.
  • Always use sentence case when writing headings, for more information read the product style guide.

Accessibility

Accessibility page anchor

It is important to not skip one or more heading levels as it is common for screen readers to build an outline of the page and assist users as they navigate a page. Skipping a heading level could cause confusion as the user navigating the page may not know why a heading is missing.

  • Heading text should meet AA requirements (4.5:1) for color contrast from itself and the background color.
  • Headings should have clear hierarchies of content and subsections.

Examples

Examples page anchor
Component preview theme
<>

<Heading as="h1" variant="heading10">

  Black lives matter

</Heading>

<Heading as="h2" variant="heading20">

  Black lives matter

</Heading>

<Heading as="h3" variant="heading30">

  Black lives matter

</Heading>

<Heading as="h4" variant="heading40">

  Black lives matter

</Heading>

<Heading as="h5" variant="heading50">

  Black lives matter

</Heading>

<Heading as="h6" variant="heading60">

  Black lives matter

</Heading>

</>

Heading as h2 with heading10 variant

Heading as h2 with heading10 variant page anchor
Component preview theme
<Heading as="h2" variant="heading10">

  Heading one

</Heading>

Heading as h2 with heading20 variant

Heading as h2 with heading20 variant page anchor
Component preview theme
<Heading as="h2" variant="heading20">

  Heading two

</Heading>

Heading as h2 with heading30 variant

Heading as h2 with heading30 variant page anchor
Component preview theme
<Heading as="h2" variant="heading30">

  Heading three

</Heading>

Heading as h2 with heading40 variant

Heading as h2 with heading40 variant page anchor
Component preview theme
<Heading as="h2" variant="heading40">

  Heading four

</Heading>

Heading as h2 with heading50 variant

Heading as h2 with heading50 variant page anchor
Component preview theme
<Heading as="h2" variant="heading50">

  Heading five

</Heading>

Heading as h2 with heading60 variant

Heading as h2 with heading60 variant page anchor
Component preview theme
<Heading as="h2" variant="heading60">

  Heading six

</Heading>

Heading with no bottom margin

Heading with no bottom margin page anchor
Component preview theme
<Card>

  <Heading as="h2" marginBottom="space0" variant="heading10">

    Heading with no margin

  </Heading>

</Card>

Composition notes

Composition notes page anchor

Headings should capture the most important information contained in the content beneath it. A user should be able to scan just the headers and understand the flow of information on the page.

Keep headings concise. You can omit articles ("a", "the") depending on the context. If the user would be prioritizing efficiency, leave out articles. If the content is more casual, include articles.

Use sentence case.

Difference between the as and variant props

Difference between the as and variant props page anchor

Visual hierarchy doesn't always follow document hierarchy. For this reason, we've decoupled the visual appearance (the variant prop) from the semantic hierarchy (the as prop) of the element.

For accessibility reasons we want to create a nice clean document hierarchy where:

  • We only have one h1
  • We don't skip levels as we travel the DOM:
h1
  h2
    h3
    h3
  h2
  h2
    h3
      h4
    h3
      h4

Sometimes, the appropriate document level doesn't match the visual design, because, for example, the third section of content is less important than the previous two, but at the same logical level of document hierarchy.

By decoupling visual appearance from hierarchy, we enable designers and engineers to create visual and semantic hierarchy correctly for all users.

Do and don't

Do and don't page anchor

Headings should be used for page headings or content subsections. Headings are broken into six levels, where h1 is the highest level and h6 is the lowest. Avoid skipping heading levels. Use the next lowest heading level to maintain a coherent document outline.

This is sentence case

Do

Use sentence case in headings.

This Is Title Case

Don't

Don’t use title case.

Do

Use headings for page headings and to organize content on the page.

Don't

Don’t use headings for pure stylistic purposes.

Do

Use headings in order.

Don't

Don’t skip levels or put smaller headings before larger headings.

Usage Guide

Usage Guide page anchor

API

API page anchor

Installation

Installation page anchor
yarn add @twilio-paste/heading - or - yarn add @twilio-paste/core

Usage

Usage page anchor
import {Heading} from '@twilio-paste/core/heading';

const Component = () => (
  <Heading as="h2" variant="heading20">
    Heading Two
  </Heading>
);

Props

Props page anchor
PropTypeDescriptionDefault
asasTags'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'div', 'label', 'span'null
id?stringnull
marginBottom?oneOf(['space0'])Currently we only allow space0 to remove bottom marginnull
variantheadingVariants'heading10', 'heading20', 'heading30', 'heading40', 'heading50', 'heading60'null
display?CSS display property options'block', 'inline', 'inline-block', 'flex', 'inline-flex', 'grid', 'inline-grid', and more"block"
element?stringOverrides the default element name to apply unique styles with the Customization Provider'HEADING'