@atlaskit/primitives/constellation/text/examples.mdx

Primitives are token-backed low-level building blocks.

---
title: Text
description: Text is a token-backed typography component to display body text.
order: 0
---

import TextBasic from '../../examples/constellation/text/text-basic';
import TextColorInverse from '../../examples/constellation/text/text-color-inverse';
import TextColorInherit from '../../examples/constellation/text/text-color-inherit';
import TextWeight from '../../examples/constellation/text/text-weight';
import TextAlign from '../../examples/constellation/text/text-align';
import TextAsElement from '../../examples/constellation/text/text-as-element';
import TextSpacing from '../../examples/constellation/text/text-spacing';
import TextTruncation from '../../examples/constellation/text/text-truncation';
import TextCustomization from '../../examples/constellation/text/text-customization';

## Basic

Use a Text component for main content. Text typically appears after headings or subheadings as
detailed descriptions and messages, but also as standalone text in components.

The `size` prop expresses the visual appearance of the text element:

- `'large'` is for long-form content. Use this size for a comfortable reading experience such as in
  blogs.
- `'medium'` is the default size in components or where space is limited, for detailed or
  descriptive content such as primary descriptions in flags.
- `'small'` should be used sparingly and is for secondary level content such as fine print or
  semantic messaging.

<Example Component={TextBasic} packageName="@atlaskit/primitives" />

## Color

Text uses the `color.text` token which automatically switches colors to be legible across both light
and dark modes.

Text will automatically apply the correct inverse color token if placed within a
[box component](/components/primitives/box) with a bold background color.

<Example Component={TextColorInverse} packageName="@atlaskit/primitives" />

The `color` prop can be used with any text color token. If Text is nested inside another Text
component, color will automatically inherit from its parent.

<Example Component={TextColorInherit} packageName="@atlaskit/primitives" />

## Font weight

Font weight defaults to regular (400) and can be set using the `weight` prop. More information about
the available weights can be found on the
[typography foundations page](/foundations/typography-beta/#body-font-weight).

Note: Text supports the semibold weight, however due to differences between font stacks across
different operating systems, semibold text may render as bold. We recommend using regular, medium,
and bold for the best results.

<Example Component={TextWeight} packageName="@atlaskit/primitives" />

## Alignment

Text can be aligned using the `align` prop.

<Example Component={TextAlign} packageName="@atlaskit/primitives" />

## Rendered HTML element

Text renders a HTML `<span>` element by default. Use the `as` prop to change the rendered HTML
element.

<Example Component={TextAsElement} packageName="@atlaskit/primitives" />

## Arrangement with other text styles

Text does not apply any vertical margin or spacing. To control space between text and other content,
use a [stack component](/components/primitives/stack).

The available values for paragraph spacing are outlined in the
[Typography foundations](/foundations/typography-beta/#body) page.

<Example Component={TextSpacing} packageName="@atlaskit/primitives" />

## Truncation

Truncation in product experiences [should be avoided](/content/language-and-grammar/#truncation).

However if truncation cannot be avoided, for example when displaying user-generated content, use the
`maxLines` prop to indicate how text should be truncated.

<Example Component={TextTruncation} packageName="@atlaskit/primitives" />

## Customization

A restricted set of styles can be customized using the `xcss` prop. This is only available in the
Compiled version of Text.

<Example Component={TextCustomization} packageName="@atlaskit/primitives" />