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

Figma:

Web:

iOS:

Android:

A11y:

Props

Component props
Name
Type
Default
align
"start" | "end" | "center" | "forceLeft" | "forceRight"
-

"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"
| "subtle"
| "success"
| "error"
| "warning"
| "shopping"
| "link"
| "inverse"
| "light"
| "dark"
-

The color of the text content. See the colors variant for more details.

inline
boolean
-

Indicates how the text should flow with the surrounding content. See the block vs inline variant for more details.

italic
boolean
-

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" | "breakWord" | "noWrap"
-

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"
-

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
-

Indicates if the text content should be underlined. See the styles variant for more details.

weight
"bold" | "normal"
-

Indicates the font weight for the text content. See the styles variant for more details.

Usage guidelines

Do
  • 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

Do

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.

Do

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.

Do

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.

Do

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

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.

Text-wrapping and hyphenation

Hyphenation on iOS is turned off by default to avoid incorrect word breaks when strings of text wrap to the next line. This is especially helpful for international languages where an incorrect word break can greatly change the meaning of a word or sentence.

Variants

Alignment

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

Block vs. inline

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

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.

Overflow & truncation

Gestalt provides utility options to deal with text overflow.

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.

Styles

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

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.

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.

Writing

Do
  • 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.

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.