# Kinetic Text

> A headline whose words or letters rise out of a mask, one after another, as it scrolls into view.

```tsx
'use client';

import { useState } from 'react';
import { Button, KineticText } from '@brand-studio/ui';

export default function KineticTextDemo() {
  const [run, setRun] = useState(0);
  const [by, setBy] = useState<'word' | 'letter'>('word');
  return (
    <div style={{ width: '100%', maxWidth: 620, display: 'grid', gap: 24 }}>
      <KineticText key={`${run}-${by}`} by={by} text="Roasted on Monday, in your cup by Friday." />
      <div style={{ display: 'flex', gap: 8 }}>
        <Button tone="secondary" onClick={() => setRun(run + 1)}>Replay</Button>
        <Button tone="secondary" onClick={() => setBy(by === 'word' ? 'letter' : 'word')}>By {by === 'word' ? 'letter' : 'word'}</Button>
      </div>
    </div>
  );
}
```

## Installation

```sh
npm install @brand-studio/ui
```

React 18 or 19 is a peer dependency. Import the stylesheet once and wrap the app in a brand theme:

```tsx
import '@brand-studio/ui/styles.css';
import { BrandTheme, KineticText } from '@brand-studio/ui';
import brand from './brand.json';

<BrandTheme palette={brand.tokens} mode="system">
  {/* your app */}
</BrandTheme>
```

## Usage

```tsx
import { KineticText } from '@brand-studio/ui';
```

```tsx
<KineticText as="h1" by="letter" text="Roasted on Monday." />
```

## Accessibility

- Screen readers hear the whole text once; the moving pieces are hidden from them.
- A headline already on screen plays at once; one further down waits until it scrolls in.
- Without JavaScript or with reduced motion the text shows in place.

## API Reference

| Prop | Type | Default |
|---|---|---|
| `text` | `string` | – |
| `as?` | `React.ElementType` | – |
| `by?` | `"letter" \| "word"` | `'word'` |
| `stagger?` | `number` | `45` |
| `className?` | `string` | `''` |

Source: https://brandstudio.js.org/docs/components/kinetic-text/
