# Text
> Text is a basic typography component for outputting any supported text style provided by our design tokens.

## Import

```js
import { Text } from '@gemini-suite/vera-react';
```

## Examples

### Basic

Use **Text** as a wrapper component that will apply constrained set of styles to the text inside. Available text styles are derived from [our typography tokens](/tokens/typography).

<Callout variant="tip">

**Text** should be used for any non-heading text. If you need to define a semantically relevant title to a component, section or page, use [Heading component](/components/typography/heading).

</Callout>

```jsx
<Box>
  <Text>Text is the most basic component for rendering text blocks.</Text>
  <Text as="div" marginY="spacingM">
    Text might seem like a{' '}
    <Text as="b" color="foregroundNeutralSubtle">
      boring component
    </Text>
  </Text>
  <Text as="div" fontSize="gamma" lineHeight="gamma" fontFamily="display">
    but can be incredibly handy
  </Text>
</Box>
```

### Custom semantics

**Text** component will render an HTML `span` element by default, but via the `as` property, you can set it to render as any HTML element to ensure the underlying document semantics are meaningful. For example, using a `p` element for marking-up a paragraph.

```jsx
<Box>
  <Text as="p" marginBottom="spacingM">
    Text using a <b>p</b> element to provide paragraph semantics.
  </Text>
  <Text as="p" marginY="none">
    Brownie liquorice sugar plum carrot cake soufflé pie gingerbread.
    Marshmallow marshmallow lollipop apple pie gingerbread. Chupa chups jelly-o
    tiramisu chocolate cake lollipop. Bonbon muffin gummi bears macaroon
    lollipop tart chupa chups tiramisu biscuit. Cotton candy marshmallow halvah
    marzipan wafer.
  </Text>
</Box>
```

### Visual variants

**Text** comes with two built-in variants used for displaying long-form writing. These variants are represented by `font-size`, `font-weight`, `line-height` and `font-family` values.

- `epsilon` is the default variant used for most body text.
- `zeta` variant is recommended for small components and conserving space in data-heavy layouts.
- `eta` variant is suitable for small amounts of additional information in data-heavy layouts. Use in moderation.

To change the visual variant, use the `variant` property.

```jsx
<Flex flow="column">
  <Text as="p" variant="epsilon" marginY="none">
    <b>epsilon variant</b> used for long-form text (default). Pastry halvah
    halvah bear claw donut chocolate cake. Macaroon shortbread pudding tart
    sesame snaps lemon drops. Gummies tootsie roll oat cake fruitcake chocolate
    bar. Donut wafer wafer oat cake croissant gingerbread cake.
  </Text>
  <Text as="p" variant="zeta" marginY="none">
    <b>zeta variant</b> used for smaller long-form text. Pastry halvah halvah
    bear claw donut chocolate cake. Macaroon shortbread pudding tart sesame
    snaps lemon drops. Gummies tootsie roll oat cake fruitcake chocolate bar.
    Donut wafer wafer oat cake croissant gingerbread cake.
  </Text>
  <Text as="p" variant="eta" marginY="none">
    <b>eta variant</b> used for subtext. Pastry halvah halvah bear claw donut
    chocolate cake.
  </Text>
</Flex>
```

### Custom styling

Apart from selecting `variant`, you can freely manipulate **Text** styling, by passing style properties for common text styles. These properties include `fontFamily`, `fontSize`, `fontWeight`, `letterSpacing`, `color`and`lineHeight`.
You can only select design tokens as the value of each property. Combination of the different properties is possible.

```jsx
<Flex flow="column" gap="spacingL">
  <Flex flow="column" gap="spacingS">
    <Text fontSize="gamma" lineHeight="gamma">
      Text size gamma
    </Text>
    <Text fontSize="delta" lineHeight="delta">
      Text size delta
    </Text>
    <Text>Text size base</Text>
    <Text fontSize="zeta" lineHeight="zeta">
      Text size zeta
    </Text>
  </Flex>
  <Text fontFamily="mono" fontSize="zeta" lineHeight="zeta">
    Text with mono font
  </Text>
  <Flex flow="column" gap="spacingS">
    <Text weight="normal">Text weight normal</Text>
    <Text fontWeight="semibold">Text weight semibold</Text>
  </Flex>
  <Flex flow="column" gap="spacingS">
    <Text letterSpacing="tight">Tracking tight</Text>
    <Text letterSpacing="normal">Tracking normal</Text>
    <Text letterSpacing="wide">Tracking wide</Text>
    <Text letterSpacing="wider">Tracking wider</Text>
  </Flex>
  <Flex flow="column" gap="spacingS">
    <Text color="foregroundNeutral">Base</Text>
    <Text color="foregroundNeutralModerate">Muted</Text>
    <Text color="foregroundNeutralSubtle">Dim</Text>
    <Text color="foregroundDangerModerate" fontWeight="semibold">
      Critical
    </Text>
    <Text color="foregroundInfoModerate" fontWeight="semibold">
      Informative
    </Text>
    <Text color="foregroundSuccessModerate" fontWeight="semibold">
      Success
    </Text>
  </Flex>
</Flex>
```

### Responsive

Any style or variant property supported by the **Text** component is responsive, meaning it can accept either a single value or an object that maps values to [breakpoints defined in Vera](/tokens/breakpoints).

For example, you may provide responsive values describing font stack, sizes and weights of each breakpoint:

```jsx
<Text
  fontFamily={{
    '@initial': 'base',
    '@mqLargeAndUp': 'display'
  }}
  fontSize={{
    '@initial': 'epsilon',
    '@mqLargeAndUp': 'gamma'
  }}
  fontWeight={{
    '@initial': 'normal',
    '@mqLargeAndUp': 'semibold'
  }}
  color={{
    '@initial': 'foregroundNeutral',
    '@mqLargeAndUp': 'foregroundNeutralModerate'
  }}
>
  I'm using responsive style properties.
</Text>
```

### Alignment

Text can be aligned via the `align` prop.

```jsx
<Flex flow="column" gap="spacingS">
  <Text align="left">Left</Text>
  <Separator />
  <Text align="center">Center</Text>
  <Separator />
  <Text align="right">Right</Text>
  <Separator />
  <Text
    align={{
      '@initial': 'center',
      '@mqLargeAndUp': 'left'
    }}
  >
    Center on small screens
  </Text>
</Flex>
```

### Overflow strategy

Use the `overflowStrategy` property to manage how **Text** behaves with regard to overflow. For example, if you’re displaying user-generated content that may not fit within your layout, you can truncate text with the `overflowStrategy` set to `truncate`.

```jsx
<Flex flow="column" css={{ maxWidth: '36ch' }}>
  <Text>
    <b>default:</b> Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
  </Text>
  <Text overflowStrategy="truncate">
    <b>truncate:</b> Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
  </Text>
  <Text overflowStrategy="nowrap">
    <b>nowrap:</b> Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
  </Text>
  <Text overflowStrategy="breakword">
    <b>breakword:</b> Lorem ipsum dolor_sit_amet_consectetuer_adipiscing elit.
  </Text>
</Flex>
```

### Tabular numbers

Enable `useTabularNumbers` property to make numeric glyphs have uniform/tabular widths (rather than proportional).
This enables columns of numbers to line up properly, which makes scanning numerical data easier and less error-prone (especially useful in large [tables](/components/tables/table)).

```jsx
<Flex flow="column" gap="spacingXs">
  <Text useTabularNumbers fontSize="gamma" fontFamily="display">
    12121
  </Text>
  <Text useTabularNumbers fontSize="gamma" fontFamily="display">
    90909
  </Text>
</Flex>
```

---

## API Reference

<Callout variant="tip">

In addition to the props below, you can pass [Box props](/components/layout/box#api-reference) to control the spacing.

</Callout>

| Name                | Type                                                                                                                  | Default | Description                                                                                                                                                                                                                                                                                  | Required |
| ------------------- | --------------------------------------------------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `as`                | `keyof JSX.IntrinsicElements \| React.ComponentType<any>`                                                             | `span`  | Change the component to a different HTML tag or custom component. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.   For more details, read our [Composition](/get-started/composition#polymorphism) guide. |          |
| `css`               | `StitchesCss`                                                                                                         |         | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries or variants.                                                 |          |
| `variant`           | `"epsilon" \| "zeta" \| "eta"`                                                                                        |         | The visual variant of the text. Available values are pulled from [typography tokens](/tokens/typography).                                                                                                                                                                                    |          |
| `fontFamily`        | `"base" \| "display" \| "mono"`                                                                                       |         | The font of the text. Available values are pulled from [typography tokens](/tokens/typography).                                                                                                                                                                                              |          |
| `fontSize`          | `"base" \| "eta" \| "zeta" \| "epsilon" \| "delta" \| "gamma" \| "beta" \| "alpha" \| "giga"`                         |         | The size of the text. Available values are pulled from [typography tokens](/tokens/typography).                                                                                                                                                                                              |          |
| `fontWeight`        | `"normal" \| "semibold"`                                                                                              |         | The weight of the text. Available values are pulled from [typography tokens](/tokens/typography).                                                                                                                                                                                            |          |
| `lineHeight`        | `"base" \| "none" \| "small" \| "xSmall" \| "zeta" \| "epsilon" \| "delta" \| "gamma" \| "beta" \| "alpha" \| "giga"` |         | The line height (also called leading) of the text. Available values are pulled from [typography tokens](/tokens/typography).                                                                                                                                                                 |          |
| `letterSpacing`     | `"tighter" \| "tight" \| "normal" \| "wide" \| "wider" \| "widest"`                                                   |         | The horizontal spacing between the characters of the text. Available values are pulled from [typography tokens](/tokens/typography).                                                                                                                                                         |          |
| `color`             | `ColorToken`                                                                                                          |         | The color of the text. Subset of contrast-friendly foreground values from [color tokens](/tokens/colors) are available.                                                                                                                                                                      |          |
| `align`             | `"left" \| "center" \| "right"`                                                                                       |         | The horizontal alignment of the text.                                                                                                                                                                                                                                                        |          |
| `useTabularNumbers` | `boolean`                                                                                                             |         | When `true`, numbers in the text will have the same width.                                                                                                                                                                                                                                   |          |
| `overflowStrategy`  | `"wrap" \| "nowrap" \| "truncate" \| "breakword"`                                                                     |         | Controls how text behaves with regard to overflow.                                                                                                                                                                                                                                           |          |