Heading

Headings help introduce and organize content on a page. There is typically a main heading for the page and additional headings for the subsequent sections.

Code

Usage

import { Heading } from "@twilio-labs/match/components";
const Component = () => <Heading variant="h1">Ahoy</Heading>;

Props

PropTypeDefaultDescription
variantHeadingVariantnull'h1', 'h2', 'h3', 'h4', 'h5', 'h6'
inverse?booleannullInverts text color for use with dark backgrounds.
as?HeadingVariantnullThe HTML tag to use if different from variant.

Also supports margin props.


Guidelines

About Headings

Headings are used to create a sense of hierarchy in the page. H1s have the highest rank and introduces the page. The following ranks get more specific and divide the page into sections and subsections. 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.

Accessibility

Here are some quick accessibility tips to ensure a positive user experience for all users.

  • Do not skip heading levels. It is common for screen readers to build an outline of the page using headings and skipping a heading level could cause confusion, making a user question why a heading is missing.
  • Headings should be used in a logical order that aligns with the visual hierarchy

Composition

Many users scan websites by reading headings so the heading text should be clear, concise, and descriptive of the content that will follow that heading. Heading text of a lower ranked heading should relate to the heading text of a higher ranked heading. Overall, the headings should read like an outline of the page.

Do
  • Have a single h1 that gives the user an idea of what the page is about.
  • Headings should support the hierarchy and structure of the page.
  • Headings should be in a logical order that can be read like an outline.
Don't
  • Don't have multiple h1s on a page.
  • Don’t use headings for pure stylistic purposes.
  • Don’t use headings out of order.

Examples

Hierarchy

Inverse

Include the inverse prop when headings are used on dark backgrounds.

Heading with variant and as

The underlying HTML of the Heading component matches the provided variant by default. This can be overridden with the as property when a certain visual style is required out of the hierarchical context.