# Text

Text with paired font sizes and line heights.

```tsx
import { Text } from "@/components/ui/text"
import { VStack } from "@/components/ui/stack"

export default function TextDemo() {
  return (
    <VStack gap={3}>
      <Text weight="medium">Deployment complete</Text>
      <Text tone="muted">Your changes are live on arene.style.</Text>
      <Text size="xs" tone="muted">
        Updated just now
      </Text>
    </VStack>
  )
}
```

## Installation

**Command**

```bash
npx shadcn@latest add @arene/text
```

Needs the [arene setup](https://www.arene.style/docs/installation) first.

**Manual**

1. Install the packages it imports:

   ```bash
   npm install @base-ui/react @stylexjs/stylex clsx
   ```

2. Set up the token layer. See [Installation](https://www.arene.style/docs/installation).

3. Copy the component into your project.

   ```tsx title="components/ui/text.tsx"
   "use client"

   import type { CSSProperties } from "react"
   import { useRender } from "@base-ui/react/use-render"
   import * as stylex from "@stylexjs/stylex"
   import type { StyleXStyles } from "@stylexjs/stylex"
   import { clsx } from "clsx"

   import { color, leading, text } from "@/theme/tokens.stylex"

   const sizes = stylex.create({
     xs: { fontSize: text.xs, lineHeight: leading.xs },
     sm: { fontSize: text.sm, lineHeight: leading.sm },
     base: { fontSize: text.base, lineHeight: leading.base },
     lg: { fontSize: text.lg, lineHeight: leading.lg },
     xl2: { fontSize: text.xl2, lineHeight: leading.xl2 },
     xl3: { fontSize: text.xl3, lineHeight: leading.xl3 },
     xl4: { fontSize: text.xl4, lineHeight: leading.xl4 },
   })

   const tones = stylex.create({
     muted: { color: color.mutedForeground },
   })

   const weights = stylex.create({
     normal: { fontWeight: 400 },
     medium: { fontWeight: 500 },
     semibold: { fontWeight: 600 },
     bold: { fontWeight: 700 },
   })

   const textStyles = { sizes, tones, weights }

   type TextProps = useRender.ComponentProps<"span"> & {
     size?: keyof typeof sizes
     tone?: keyof typeof tones
     weight?: keyof typeof weights
     xstyle?: StyleXStyles
     style?: CSSProperties
   }

   function Text({ render, ref, size, tone, weight, xstyle, className, style, ...props }: TextProps) {
     const sx = stylex.props(
       size && sizes[size],
       tone && tones[tone],
       weight && weights[weight],
       xstyle,
     )
     return useRender({
       defaultTagName: "span",
       render,
       ref,
       props: {
         "data-slot": "text",
         "data-size": size,
         ...sx,
         ...props,
         className: clsx(sx.className, className),
         style: { ...sx.style, ...style },
       },
     })
   }

   export { Text, textStyles, type TextProps }
   ```

4. Change the `@/` imports if your project uses different aliases.

## Usage

```tsx
import { Text } from "@/components/ui/text"
```

```tsx
<Text tone="muted">Changes are saved automatically.</Text>
```

Unset size, tone and weight inherit. `textStyles` exports `sizes`, `tones` and
`weights` for use in another element's `stylex.props()` call.

## Size

Each size includes its line height. Leave `size` unset to inherit.

```tsx
import { Text } from "@/components/ui/text"
import { VStack } from "@/components/ui/stack"

export default function TextSize() {
  return (
    <VStack gap={3}>
      <Text size="xs">Updated just now</Text>
      <Text size="sm">Changes are saved automatically.</Text>
      <Text size="base">Read the project overview.</Text>
      <Text size="lg">Build something useful.</Text>
      <Text size="xl2">Your next project</Text>
      <Text size="xl3">Start building</Text>
      <Text size="xl4">Made for the web</Text>
    </VStack>
  )
}
```

## Tone

Leave `tone` unset to inherit the surrounding color.

```tsx
import { Text } from "@/components/ui/text"
import { VStack } from "@/components/ui/stack"

export default function TextTone() {
  return (
    <VStack gap={3}>
      <Text>Deployment complete</Text>
      <Text tone="muted">Last updated just now</Text>
    </VStack>
  )
}
```

## Weight

Leave `weight` unset to inherit the surrounding weight.

```tsx
import { Text } from "@/components/ui/text"
import { VStack } from "@/components/ui/stack"

export default function TextWeight() {
  return (
    <VStack gap={3}>
      <Text weight="normal">Normal text</Text>
      <Text weight="medium">Medium text</Text>
      <Text weight="semibold">Semibold text</Text>
      <Text weight="bold">Bold text</Text>
    </VStack>
  )
}
```

## Composition

Pass `render` to choose a semantic element. Put its props on that element.

```tsx
import { Text } from "@/components/ui/text"

export default function TextRender() {
  return (
    <Text render={<p />} tone="muted">
      Changes are saved automatically.
    </Text>
  )
}
```

## API reference

See Base UI's [useRender reference](https://base-ui.com/react/utils/use-render)
for composition props. Native element props are forwarded.

| Prop        | Type                                           | Default        |
| ----------- | ---------------------------------------------- | -------------- |
| `size`      | `keyof typeof textStyles.sizes`                | None           |
| `tone`      | `"muted"`                                      | None           |
| `weight`    | `"normal" \| "medium" \| "semibold" \| "bold"` | None           |
| `render`    | `useRender.RenderProp`                         | Native element |
| `xstyle`    | `StyleXStyles`                                 | None           |
| `className` | `string`                                       | None           |
| `style`     | `CSSProperties`                                | None           |

### Data attributes

| Attribute          | On   | Effect                   |
| ------------------ | ---- | ------------------------ |
| `data-slot="text"` | root | Identifies the component |
| `data-size`        | root | Mirrors `size`           |
