Props
Usage guidelines
- When you need to use a semantic H1–H6 heading to create a clear typographic hierarchy and page structure
- To emphasize text. Use Text with a bold or italic style instead
- To provide an overall Page title. Use PageHeader instead
Best practices
Use to help group text and items into sections in a logical order.
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.
Keep headings short and glanceable.
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.
Clearly describe the section a Heading refers to.
Use vague language that doesn’t describe the section that a Heading refers to.
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.
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.
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:
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 when translating languages that require more characters.
import { useState } from 'react'; import { Box, ColorSchemeProvider, Flex, Heading, SelectList } from 'gestalt'; export default function Example() { const [language, setLanguage] = useState('default'); const content = Object.freeze({ default: 'Lorem ipsum dolor sit amet, vis legimus appetere sententiae ex, est habeo erant noluisse ex. Ad sit enim vitae concludaturque, id diam aperiam explicari has.', tall: 'अंतर्गत निर्माण क्षमता। विभाग लोगो तकनिकल प्रव्रुति प्रतिबध्दता अपने चुनने साधन आधुनिक स्वतंत्र संसाध पुस्तक व्याख्या सेऔर भाषाओ मानसिक सोफ़्टवेर जिसे लक्षण सादगि केवल सुचनाचलचित्र विकेन्द्रियकरण', ck: '法大感康催今間郎済分暮測。会転大籍法必辞住利業済表者加社。見競回画訴藤投冠阪暮止逮使際女審。堅種術天可毎帰画級見田頭豊世建抽座総目功。作温霊住再提略投際界利浜東着送容方権六。阪千割断待伴民腺結道員賀荷知外森若免教', ja: '尾ノホタクスフ名津以樹ふなり夜巣区ヨクエヨイ個尾御すんちゆゅときよりせけ離根巣遊野名離他都二露二鵜ひへせと、毛以く派雲ろ絵ほまり列知津絵日日区目魔阿御ろんさゆ等他', vi: 'Lorem Ipsum chỉ đơn giản là một đoạn văn bản giả, được dùng vào việc trình bày và dàn trang phục vụ cho in ấn. Lorem Ipsum đã được sử dụng như một văn bản chuẩn cho ngành công nghiệp in ấn từ những năm ', th: 'Lorem Ipsum คือ เนื้อหาจำลองแบบเรียบๆ ที่ใช้กันในธุรกิจงานพิมพ์หรืองานเรียงพิมพ์ มันได้กลายมาเป็นเนื้อหาจำลองมาตรฐานของธุรกิจดังกล่าวมาตั้งแต่ศตวรรษที่', }); return ( <Box height="100%" padding={8} width="100%"> <Flex direction="column" gap={4} width="100%"> <SelectList id="selectlistMain" label="line height type" onChange={({ value }) => { if ( value === 'default' || value === 'ja' || value === 'tall' || value === 'ck' || value === 'th' || value === 'vi' ) { setLanguage(value); } }} > {[ { label: 'default', value: 'default' }, { label: 'tall', value: 'tall' }, { label: 'ck', value: 'ck' }, { label: 'ja', value: 'ja' }, { label: 'vi', value: 'vi' }, { label: 'th', value: 'th' }, ].map(({ label, value }) => ( <SelectList.Option key={label} label={label} value={value} /> ))} </SelectList> <ColorSchemeProvider colorScheme="light" fullDimensions id="localizationLanaguage" language={language} > <Flex direction="column" gap={1}> <Heading size="200">{content[language]}</Heading> <Heading size="300">{content[language]}</Heading> <Heading size="400">{content[language]}</Heading> <Heading size="500">{content[language]}</Heading> <Heading size="600">{content[language]}</Heading> </Flex> </ColorSchemeProvider> </Flex> </Box> ); }
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
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
- 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
- Punctuate headings unless they are posing a question or making an exclamation
- Use Title Case or ALL CAPS
Related
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.