# Scatter Text

> Letters knocked out of place that people can drag about, and that spring back on cue.

```tsx
'use client';

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

export default function ScatterTextDemo() {
  const [tidy, setTidy] = useState(false);
  return (
    <div style={{ display: 'grid', justifyItems: 'center', gap: 20, textAlign: 'center' }}>
      <h2 style={{ margin: 0, fontSize: 'clamp(2.4rem, 9vw, 4.5rem)', fontWeight: 800 }}>
        <ScatterText text="Page not found" tidy={tidy} />
      </h2>
      <p style={{ margin: 0, maxWidth: '30ch', color: 'var(--bs-muted)' }}>Drag the letters about, or put them back in one go.</p>
      <Button tone="secondary" onClick={() => setTidy(value => !value)}>{tidy ? 'Knock it over' : 'Put it back'}</Button>
    </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, ScatterText } from '@brand-studio/ui';
import brand from './brand.json';

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

## Usage

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

```tsx
<h1><ScatterText text="Page not found" tidy={tidy} /></h1>
<Button tone="secondary" onClick={() => setTidy(true)}>Put it back</Button>
```

The letters scatter after the page loads and spring back when `tidy` turns on. `spread` scales how far they fall; the default keeps them clear of the line below. Words wrap as whole words.

## Accessibility

- Screen readers hear the plain text once; the loose letters are hidden from them.
- The server renders the text in order, so it reads correctly before scripts run.
- Under reduced motion the letters stay in place.

## API Reference

| Prop | Type | Default |
|---|---|---|
| `text` | `string` | – |
| `tidy?` | `boolean` | `false` |
| `spread?` | `number` | `1` |
| `as?` | `React.ElementType` | – |
| `className?` | `string` | `''` |

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