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:

Responsive:

Adaptive:

A11y:

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" | "breakAll"
"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 BannerSlim, 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

Be sure to localize all text strings. Note that localization can lengthen text by 20 to 30 percent.

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.

import { Box, Flex, Heading } from 'gestalt';

export default function Example() {
  return (
    <Box
      alignItems="center"
      display="flex"
      height="100%"
      justifyContent="center"
      padding={8}
    >
      <Flex direction="column" gap={{ column: 4, row: 0 }}>
        <Heading size="100">Heading size 100</Heading>
        <span lang="ja">
          <Heading size="100">こんにちは</Heading>
        </span>

        <span>
          <Heading size="200">Heading size 200</Heading>
        </span>
        <span lang="ja">
          <Heading size="200">こんにちは</Heading>
        </span>

        <Heading size="300">Heading size 300</Heading>
        <span lang="ja">
          <Heading size="300">こんにちは</Heading>
        </span>

        <Heading size="400">Heading size 400</Heading>
        <span lang="ja">
          <Heading size="400">こんにちは</Heading>
        </span>

        <Heading size="500">Heading size 500</Heading>
        <span lang="ja">
          <Heading size="500">こんにちは</Heading>
        </span>

        <Heading size="600">Heading size 600</Heading>
        <span lang="ja">
          <Heading size="600">こんにちは</Heading>
        </span>
      </Flex>
    </Box>
  );
}

Color

import { Box, Flex, Heading } from 'gestalt';

export default function Example() {
  return (
    <Box alignItems="center" display="flex" justifyContent="center" padding={8}>
      <Flex direction="column" gap={{ column: 4, row: 0 }}>
        <Box color="dark" padding={1}>
          <Heading color="inverse" size="500">
            Inverse
          </Heading>
        </Box>

        <Heading size="500">Default</Heading>

        <Heading color="subtle" size="500">
          Subtle
        </Heading>

        <Heading color="success" size="500">
          Success
        </Heading>

        <Heading color="error" size="500">
          Error
        </Heading>

        <Heading color="warning" size="500">
          Warning
        </Heading>

        <Heading color="shopping" size="500">
          Shopping
        </Heading>

        <Box color="primary" padding={1}>
          <Heading color="light" size="500">
            Light
          </Heading>
        </Box>

        <Box color="infoWeak" padding={1}>
          <Heading color="dark" size="500">
            Dark
          </Heading>
        </Box>
      </Flex>
    </Box>
  );
}

Overflow & truncation

import { Box, Flex, Heading, Text } from 'gestalt';

export default function Example() {
  return (
    <Box display="flex" justifyContent="center" padding={8}>
      <Flex direction="column" gap={{ column: 8, row: 0 }} maxWidth={240}>
        <Flex direction="column" gap={{ column: 2, row: 0 }}>
          <Text>breakWord (default):</Text>
          <Box color="secondary" padding={2} rounding={2}>
            <Heading overflow="breakWord" size="400">
              This is a long and Supercalifragilisticexpialidocious sentence.
              次の単語グレートブリテンおよび北アイルランド連合王国で本当に大きな言葉
            </Heading>
          </Box>
        </Flex>

        <Flex direction="column" gap={{ column: 2, row: 0 }}>
          <Text>normal:</Text>
          <Box color="secondary" padding={2} rounding={2}>
            <Heading overflow="normal" size="400">
              This is a long and Supercalifragilisticexpialidocious sentence.
              次の単語グレートブリテンおよび北アイルランド連合王国で本当に大きな言葉
            </Heading>
          </Box>
        </Flex>

        <Flex direction="column" gap={{ column: 2, row: 0 }}>
          <Text>breakAll:</Text>
          <Box color="secondary" padding={2} rounding={2}>
            <Heading overflow="breakAll" size="400">
              This is a long and Supercalifragilisticexpialidocious sentence.
              次の単語グレートブリテンおよび北アイルランド連合王国で本当に大きな言葉
            </Heading>
          </Box>
        </Flex>

        <Flex direction="column" gap={{ column: 2, row: 0 }}>
          <Text>lineClamp:</Text>
          <Box color="secondary" padding={2} rounding={2}>
            <Heading lineClamp={2} size="400">
              This is a long and Supercalifragilisticexpialidocious sentence.
              次の単語グレートブリテンおよび北アイルランド連合王国で本当に大きな言葉
            </Heading>
          </Box>
        </Flex>
      </Flex>
    </Box>
  );
}

Alignment

Use align to adjust the positioning of text within container elements

import { Box, Divider, Flex, Heading } from 'gestalt';

export default function Example() {
  return (
    <Box
      alignItems="center"
      display="flex"
      height="100%"
      justifyContent="center"
      padding={8}
    >
      <Flex direction="column" gap={{ column: 4, row: 0 }}>
        <Heading align="start" size="400">
          Start-aligned heading (default)
        </Heading>
        <Divider />
        <Heading align="end" size="400">
          End-aligned heading
        </Heading>
        <Divider />
        <Heading align="center" size="400">
          Center-aligned heading
        </Heading>
        <Divider />
        <Heading align="forceLeft" size="400">
          Forced-left-aligned heading
        </Heading>
        <Divider />
        <Heading align="forceRight" size="400">
          Forced-right-aligned heading
        </Heading>
      </Flex>
    </Box>
  );
}

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.

import { Box, Flex, Heading } from 'gestalt';

export default function Example() {
  return (
    <Box
      alignItems="center"
      display="flex"
      height="100%"
      justifyContent="center"
      padding={8}
    >
      <Flex direction="column" gap={{ column: 4, row: 0 }}>
        <Heading accessibilityLevel={2} size="500">
          Medium heading level 2
        </Heading>
        <Heading accessibilityLevel={3} size="400">
          Small heading level 3
        </Heading>
        <Heading accessibilityLevel="none" size="400">
          Small heading without a level
        </Heading>
      </Flex>
    </Box>
  );
}

Component quality checklist

Component quality checklist
Quality item
Status
Status description
Figma Library
Ready
Component is available in Figma for web and mobile web.
Responsive Web
Ready
Component responds to changing viewport sizes in web and mobile web.
Issues
This component has known issues.

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.