Twilio's Heading component

yarn add @twilio-paste/heading — or — yarn add @twilio-paste/core


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#

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
  • There can only be one <h1> tag per page.


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 be used thoughtfully, with clear hierarchies for content and subsections


Black lives matter

Black lives matter

Black lives matter

Black lives matter

Black lives matter
Black lives matter

Heading as h2 with heading10 variant#

Heading One

Heading as h2 with heading20 variant#

Heading Two

Heading as h2 with heading30 variant#

Heading Three

Heading as h2 with heading40 variant#

Heading Four

Heading as h2 with heading50 variant#

Heading Five

Heading as h2 with heading60 variant#

Heading Six

Heading with no bottom margin#

Heading with no margin

Composition Notes#

When to use Heading#

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.


Use headings for page headings to specific sections of content.


Don’t use headings for pure stylistic purposes.


Use headings in order, so your content reads like an outline.


Don’t use headings out of order.

Usage Guide#



yarn add @twilio-paste/heading - or - yarn add @twilio-paste/core


import {Heading} from '@twilio-paste/heading';
const Component = () => (
<Heading as="h2" variant="heading20">
Heading Two


asasTags'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'div', 'label', 'span'null
marginBottom?oneOf(['space0'])Currently we only allow space0 to remove bottom marginnull
variantheadingVariants'heading10', 'heading20', 'heading30', 'heading40', 'heading50', 'heading60'null


If you need support, please open a new issue in our GitHub repository. Please try to provide as much detail as possible in your issue.


The Paste design system is open source and contributions are welcome. Check out the project on GitHub to learn more about contributing.

Copyright © 2020 Twilio, Inc.