Heading

View source on GitHub

Heading allows you to add H1–H6 level text on a page. They are generally placed underneath a PageHeader, and provide you with a way to create a logical text hierarchy.

also known as Title, Headline
Figma:
Ready
Web:
Ready
iOS:
N/A
Android:
N/A
A11y:
Ready

Props

Component props
Name
Type
Default
accessibilityLevel
1 | 2 | 3 | 4 | 5 | 6 | "none"
-

Allows you to override the default heading level for the given size.

align
"start" | "end" | "center" | "forceLeft" | "forceRight"
"start"

"start" and "end" should be used for regular alignment since they flip with locale direction. "forceLeft" and "forceRight" should only be used in special cases where locale direction should be ignored, such as tabular or numeric text. See Alignment example for more details.

children
React.Node
-
color
"default" | "subtle" | "success" | "error" | "warning" | "shopping" | "inverse" | "light" | "dark"
"default"

The color of the text. See Text colors example for more details.

id
string
-

A unique identifier for the element.

lineClamp
number
-

Visually truncate the text to the specified number of lines. This also adds the title attribute if children is a string, which displays the full text on hover in most browsers. See Truncation example for more details.

overflow
"normal" | "breakWord"
"breakWord"

How truncation is handled when text overflows the line. See Truncation example for more details.

size
"100" | "200" | "300" | "400" | "500" | "600"
600

The font size of the text. See Sizes example for more details.
The sizes are based on our font-size design tokens.

Usage guidelines

Do
  • When you need to use a semantic H1–H6 heading to create a clear typographic hierarchy and page structure
Don't
  • To emphasize text. Use Text with a bold or italic style instead
  • To provide an overall Page title. Use PageHeader instead

Best practices

Do

Use to help group text and items into sections in a logical order.

Don't

Use to emphasize text that you want users to read. Use a message component like SlimBanner, or bold text. You can also emphasize numbers by using text sizes.

Do

Keep headings short and glanceable.

Don't

Use overly long headings. If headings are dynamically generated (like a 3rd party app name), lineClamp will work after 2 lines, but be mindful of unintended changes in meaning.

Do

Clearly describe the section a Heading refers to.

Don't

Use vague language that doesn’t describe the section that a Heading refers to.

Do

Start-align headings to make it faster for users to read text from the point where they naturally start reading. The exceptions are headings related to integers in Table.

Don't

Center-align headings as it can make it harder for users with dyslexia who need a consistent stating edge. Paired with left-aligned paragraph text, it can make the typographic structure feel off-center and unbalanced.

Gestalt's typography guidelines contain additional best practices around sizing, style and hierarchy. View Typography guidelines

Accessibility

Logical order

Users will find a logical heading order and structure very helpful, especially if they have difficulty with reading and language, or if they use assistive devices such as a screen reader. A clear structure will help a screen reader user navigate the app without getting confused. Our headings default to a heading level based on size. For example:

Heading order
Level
Size
H1
600
H2
500
H3
400
H4
300
H5
200
H6
100

In some cases, you may need to start a section with a smaller heading size, but keep an H2 structure. An example is a section heading for a card or sidebar. Use the accessibilityLevel prop to override the default heading level and set the appropriate level.

Accessible sizing

A minimum text size of 16 px (12pt) is recommended for readability. Headings can go lower than that, but smaller sizes should be kept to a minimum. Making text brief will also help with readability.

Accessible color

For low-vision users, text color contrast is very important. To insure accessible contrast, stick to our standard text colors. See our accessibility page for design considerations and handy accessibility tools for checking color contrast.

Localization

Keep text simple and short to avoid truncation or line wrapping in UI controls like buttons when translating languages that require more characters. Avoid overriding our line-height settings, as this can result in text clipping for scripts, like Hindi, that have taller ascenders and descenders.

Variants

Size

These font sizes follow those available through our Design Tokens. If your text does not need to be a semantic heading (H1-H6), use Text instead.

Color

Overflow & truncation

Alignment

Use align to adjust the positioning of text within container elements

Accessibility level

For accessibility purposes, we allow you to override the heading level.

For certain specific situations, it is possible to use Heading without an accessibility level; however, we recommend against using this if possible.

Component quality checklist

Component quality checklist
Quality item
Status
Status description
Figma Library
Ready
Component is available in Figma across all platforms.
Responsive Web
Ready
Component is available in code for web and mobile web.
iOS
Component is not currently available in code for iOS.
Android
Component is not currently available in code for Android.

Writing

Do
  • Keep headings short and clear
  • Use Sentence case for headings per our Pinterest writing standards to keep the tone conversational and make headings easier to scan
Don't
  • Punctuate headings unless they are posing a question or making an exclamation
  • Use Title Case or ALL CAPS

Text
A component to use for all text on a page or in UI components.

Typography guidelines
A run-down on our typographic foundations, with some guidelines for using Heading and Text components together in products.

Design tokens
Values for text sizes, weights, families and colors.

Edit page on GitHub