Text

Text component is used for all non-heading text on all surfaces, whether inside of UI components or in long-form paragraph text.

also known as Copy, Subtext, Caption, Footer, Helper text

Figma:

Ready

Responsive:

Ready

Adaptive:

N/A

Props

Component props
Name	Type	Default
`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 the alignment variant for more details.
`children`	`React.Node`	-
	The text content to be displayed.
`color`	`"default" \| "disabled" \| "subtle" \| "success" \| "error" \| "warning" \| "shopping" \| "link" \| "inverse" \| "recommendation" \| "light" \| "dark"`	`"default"`
	The color of the text content. See the colors variant for more details.
`dataTestId`	`string`	-
	Available for testing purposes, if needed. Consider better queries before using this prop.
`id`	`string`	-
	A unique identifier for the element.
`inline`	`boolean`	`false`
	Indicates how the text should flow with the surrounding content. See the block vs inline variant for more details.
`italic`	`boolean`	`false`
	Indicates if the text should be displayed in italic. See the styles variant for more details.
`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 the overflow and truncation variant for more details.
`overflow`	`"normal" \| "breakAll" \| "breakWord" \| "noWrap"`	`"breakWord"`
	Indicates how the text content should handle overflowing its container. See the overflow and truncation variant for more details.
`ref`	`HTMLDivElement \| HTMLSpanElement`	-
	Ref that is forwarded to the underlying element. See the ref variant for more details.
`size`	`"100" \| "200" \| "300" \| "400" \| "500" \| "600"`	`300`
	The sizes are based on our font-size design tokens. See the sizes variant for more details.
`title`	`string`	-
	This populates the `title` attribute of the element, which is visible on hover in most browsers. This is useful when truncating the text with `lineClamp` when `children` is a `React.Node`. See the Title variant for more details.
`underline`	`boolean`	`false`
	Indicates if the text content should be underlined. See the styles variant for more details.
`weight`	`"bold" \| "normal"`	`"normal"`
	Indicates the font weight for the text content. See the styles variant for more details.

Usage guidelines

Any time that text is needed in the UI as a label, paragraph or number display

Don't

When you need to use a semantic H1–H6 heading to create a clear typographic hierarchy and page structure. Use Heading instead.

Best practices

Emphasize text inside of paragraphs by using a bold weight.

Don't

Emphasize text inside of paragraphs by underlining it; this can be confused with Link.

Use size to emphasize things like numbers that don’t define a page structure.

Don't

Use as section, page or surface titles to create a logical hierarchy. Use Heading instead.

Use a minimal amount of sizes and styles to keep the UI clean and readable.

Don't

Mix styles and alignment, as this can be hard to read and follow.

Start-align paragraph text.

Don't

Center-align paragraph text. This is hard to read, especially for users with dyslexia.

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

Accessibility

Accessible sizing

A minimum text size of 16 px (12pt) is recommended for readability. Some short text labels, or secondary text 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,
  DesignTokensProvider,
  Flex,
  SelectList,
  Text,
} 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">
          <DesignTokensProvider
            id="localizationLanaguage"
            languageMode={language}
          >
            <Flex direction="column" gap={1}>
              <Text size="100">{content[language]}</Text>
              <Text size="200">{content[language]}</Text>
              <Text size="300">{content[language]}</Text>
              <Text size="400">{content[language]}</Text>
            </Flex>
          </DesignTokensProvider>
        </ColorSchemeProvider>
      </Flex>
    </Box>
  );
}

Variants

Alignment

Use align to adjust the positioning of text within wrapper elements.

import { Divider, Flex, Text } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Flex direction="column" gap={{ column: 4, row: 0 }} width={200}>
        <Text align="start">Start (default)</Text>
        <Divider />
        <Text align="end">End</Text>
        <Divider />
        <Text align="center">Center</Text>
        <Divider />
        <Text align="forceLeft">Force left</Text>
        <Divider />
        <Text align="forceRight">Force right</Text>
      </Flex>
    </Flex>
  );
}

Block vs. inline

The Text component allows you to specify whether you want block or inline text.

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

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Flex alignItems="start" direction="column" gap={{ column: 4, row: 0 }}>
        <Text>Some content in a default block element. (default)</Text>
        <Box>
          <Text inline>Inline text with the inline prop.</Text>{' '}
          <Text inline>More inline text.</Text>
        </Box>
      </Flex>
    </Flex>
  );
}

Colors

You can specify which color you want for your text. Most colors change in dark mode, but light and dark are available when no switch is desired.

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

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Flex alignItems="start" direction="column" gap={{ column: 3, row: 0 }}>
        <Text color="default" size="400">
          Default
        </Text>
        <Text color="subtle" size="400">
          Subtle
        </Text>
        <Box color="inverse" padding={1}>
          <Text color="inverse" size="400">
            Inverse
          </Text>
        </Box>
        <Text color="disabled" size="400">
          Disabled
        </Text>
        <Text color="error" size="400">
          Error
        </Text>
        <Text color="success" size="400">
          Success
        </Text>
        <Text color="warning" size="400">
          Warning
        </Text>
        <Text color="recommendation" size="400">
          Recommendation
        </Text>
        <Text color="link" size="400">
          Link
        </Text>
        <Text color="shopping" size="400">
          Shopping
        </Text>
        <Box color="primary" padding={1}>
          <Text color="light" size="400">
            Light
          </Text>
        </Box>
        <Box color="infoWeak" padding={1}>
          <Text color="dark" size="400">
            Dark
          </Text>
        </Box>
      </Flex>
    </Flex>
  );
}

Overflow & truncation

Gestalt provides utility options to deal with text overflow.

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

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

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

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

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

Sizes

You can apply size options to define the size of the text. These font sizes follow those available through our Design Tokens. If your text needs to be a semantic heading (H1-H6), use Heading instead.

import { Flex, Text } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Flex alignItems="start" direction="column" gap={{ row: 2, column: 0 }}>
        <Flex alignItems="center" gap={{ row: 2, column: 0 }}>
          <Text inline size="100">
            Size 100
          </Text>
          <span lang="ja">
            <Text inline size="100">
              こんにちは
            </Text>
          </span>
        </Flex>

        <Flex alignItems="center" gap={{ row: 2, column: 0 }}>
          <Text inline size="200">
            Size 200
          </Text>
          <span lang="ja">
            <Text inline size="200">
              こんにちは
            </Text>
          </span>
        </Flex>

        <Flex alignItems="center" gap={{ row: 2, column: 0 }}>
          <Text inline size="300">
            Size 300 (default size)
          </Text>
          <span lang="ja">
            <Text inline size="300">
              こんにちは
            </Text>
          </span>
        </Flex>

        <Flex alignItems="center" gap={{ row: 2, column: 0 }}>
          <Text inline size="400">
            Size 400
          </Text>
          <span lang="ja">
            <Text inline size="400">
              こんにちは
            </Text>
          </span>
        </Flex>

        <Flex alignItems="center" gap={{ row: 2, column: 0 }}>
          <Text inline size="500">
            Size 500
          </Text>
          <span lang="ja">
            <Text inline size="500">
              こんにちは
            </Text>
          </span>
        </Flex>

        <Flex alignItems="center" gap={{ row: 2, column: 0 }}>
          <Text inline size="600">
            Size 600
          </Text>
          <span lang="ja">
            <Text inline size="600">
              こんにちは
            </Text>
          </span>
        </Flex>
      </Flex>
    </Flex>
  );
}

Styles

There are multiple styles, such as bold and italic, that we can attach to the Text component.

Note: Use "underline" style with caution. It should be limited to links and it's already internally managed by the component to adhere to best practices

import { Flex, Text } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Flex alignItems="start" gap={6}>
        <Flex alignItems="start" direction="column" gap={2}>
          <Text inline size="100">
            Size 100
          </Text>
          <Text inline size="200">
            Size 200
          </Text>
          <Text inline size="300">
            Size 300
          </Text>
          <Text inline size="400">
            Size 400
          </Text>
          <Text inline size="500">
            Size 500
          </Text>
          <Text inline size="600">
            Size 600
          </Text>
        </Flex>
        <Flex alignItems="start" direction="column" gap={2}>
          <Text inline size="100" weight="bold">
            Size 100
          </Text>
          <Text inline size="200" weight="bold">
            Size 200
          </Text>
          <Text inline size="300" weight="bold">
            Size 300
          </Text>
          <Text inline size="400" weight="bold">
            Size 400
          </Text>
          <Text inline size="500" weight="bold">
            Size 500
          </Text>
          <Text inline size="600" weight="bold">
            Size 600
          </Text>{' '}
        </Flex>
        <Text italic>Italic</Text>
        <Text underline>Underline</Text>
      </Flex>
    </Flex>
  );
}

Title

The title attribute on a <div> can be used to show the full text of a truncated string on hover. That attribute is populated automatically when the text is truncated using lineClamp, as long as children is a string.
If children is a React.Node (e.g. when using Link), use the title prop to manually set the title attribute.

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

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Flex alignItems="start" direction="column" gap={2}>
        <Flex
          alignItems="center"
          direction="column"
          gap={{ column: 2, row: 0 }}
        >
          <Text size="200" weight="bold">
            Hover over the examples below for a few seconds to see the title
            text:
          </Text>

          <Box borderStyle="sm" maxWidth={400} padding={1}>
            <Flex direction="column" gap={{ column: 3, row: 0 }}>
              <Flex direction="column" gap={{ column: 1, row: 0 }}>
                <Text italic size="100">
                  This title attribute is automatically added because lineClamp
                  is used and children is a string.
                </Text>
                <Text lineClamp={1}>
                  This is a long and Supercalifragilisticexpialidocious
                  sentence.
                  次の単語グレートブリテンおよび北アイルランド連合王国で本当に大きな言葉
                </Text>
              </Flex>

              <Flex direction="column" gap={{ column: 1, row: 0 }}>
                <Text italic size="100">
                  This example uses lineClamp but has no title attribute,
                  because children is a React.Node.
                </Text>
                <Text lineClamp={1}>
                  <Link href="#">
                    This is a long and Supercalifragilisticexpialidocious
                    sentence.
                    次の単語グレートブリテンおよび北アイルランド連合王国で本当に大きな言葉
                  </Link>
                </Text>
              </Flex>

              <Flex direction="column" gap={{ column: 1, row: 0 }}>
                <Text italic size="100">
                  This example uses lineClamp and children is a React.Node, but
                  uses the title prop.
                </Text>
                <Text
                  lineClamp={1}
                  title="This is a long and Supercalifragilisticexpialidocious sentence. 次の単語グレートブリテンおよび北アイルランド連合王国で本当に大きな言葉"
                >
                  <Link href="#">
                    This is a long and Supercalifragilisticexpialidocious
                    sentence.
                    次の単語グレートブリテンおよび北アイルランド連合王国で本当に大きな言葉
                  </Link>
                </Text>
              </Flex>
            </Flex>
          </Box>
        </Flex>
      </Flex>
    </Flex>
  );
}

Refs

Don't use ref to manipulate the underlaying HTML div or span elements. Use ref to only read HTML attributes. For example, a valid use case can be detecting truncation. The example below illustrates a case where detecting truncation allows rendering links contained within Text.

import { useEffect, useRef, useState } from 'react';
import { Box, Flex, Label, Link, Switch, Text } from 'gestalt';

export default function Example() {
  const [showLongText, setShowLongText] = useState(false);
  const [applyTruncationDetection, setApplyTruncationDetection] =
    useState(false);

  const text =
    'Tag brand partners in your Idea Pins with the paid partnership tool.';

  const veryLongText =
    'Tag brand partners in your Idea Pins with the paid partnership tool. Just make an Idea Pin in the app, add the paid partnership label and tag your partner brand. Once they approve the request, their brand name will show up on your Idea Pin. Brands can also choose to promote your Idea Pins as ads, boosting your reach to even more people. When you use the paid partnership tool, you work directly with brands to define the payment terms and process. Pinterest will not be directly involved in payment.';

  const textRef = useRef(null);
  const [ellipsisActive, setEllipsisActive] = useState(false);

  const isEllipsisActive = (element) =>
    element.offsetHeight < element.scrollHeight ||
    element.offsetWidth < element.scrollWidth;

  useEffect(() => {
    const checkEllipsisActive = () => {
      if (textRef.current) {
        if (!ellipsisActive && isEllipsisActive(textRef.current)) {
          setEllipsisActive(true);
        } else if (ellipsisActive && !isEllipsisActive(textRef.current)) {
          setEllipsisActive(false);
        }
      }
    };
    checkEllipsisActive();
    window.addEventListener('resize', checkEllipsisActive);
    return () => {
      window.removeEventListener('resize', checkEllipsisActive);
    };
  });

  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Flex direction="column" gap={8} width="90%">
        <Flex direction="column" gap={2}>
          <Box alignItems="center" display="flex">
            <Box paddingX={2}>
              <Label htmlFor="longText">
                <Text>Show long text</Text>
              </Label>
            </Box>
            <Switch
              id="longText"
              onChange={() => setShowLongText(!showLongText)}
              switched={showLongText}
            />
          </Box>
          <Box alignItems="center" display="flex">
            <Box paddingX={2}>
              <Label htmlFor="truncation">
                <Text>Apply truncation detection</Text>
              </Label>
            </Box>
            <Switch
              id="truncation"
              onChange={() =>
                setApplyTruncationDetection(!applyTruncationDetection)
              }
              switched={applyTruncationDetection}
            />
          </Box>
        </Flex>
        <Flex direction="column">
          <Text
            ref={textRef}
            align="start"
            inline
            lineClamp={2}
            title={
              ellipsisActive && typeof veryLongText === 'string'
                ? veryLongText
                : undefined
            }
          >
            {showLongText ? veryLongText : text}{' '}
            <Text inline>
              <Link
                accessibilityLabel="Visit our Help Site"
                display="inline"
                href="#"
              >
                Visit our Help Site
              </Link>
            </Text>
          </Text>
          {ellipsisActive && applyTruncationDetection ? (
            <Text>
              <Link
                accessibilityLabel="Visit our Help Site"
                display="inline"
                href="#"
              >
                Visit our Help Site
              </Link>
            </Text>
          ) : null}
        </Flex>
      </Flex>
    </Flex>
  );
}

Component quality checklist

Component quality checklist
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 text in UI components short and clear
Use Sentence case for UI labels

Don't

Use long text labels that could end up truncating or causing space issues when translating to other languages
Use Title Case or ALL CAPS in UI labels
Use ALL CAPS for paragaph text unless referring to a product or other entity that uses that style

Heading
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.

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.

Link
Used as a text-only navigational element. Links usually appear within or directly following a paragraph or sentence.

Edit page on GitHub

Text

also known as Copy, Subtext, Caption, Footer, Helper text

Props

Usage guidelines

Best practices

Accessibility

Accessible sizing

Accessible color

Localization

Variants

Alignment

Block vs. inline

Colors

Overflow & truncation

Sizes

Styles

Title

Refs

Component quality checklist

Writing

Related