# Wave text

> Letters ride a springy travelling wave on hover or in view, with wave, bounce, and scatter variants.

- Type: Component (text)
- Access: Free, open source
- Page: https://uiarc.dev/components/wave-text
- Markdown: https://uiarc.dev/components/wave-text/markdown
- Registry item: https://uiarc.dev/r/wave-text.json
- Source file: `registry/components/wave-text/wave-text.tsx`
- Dependencies: motion
- Keywords: text, motion, new, wave text, hover text animation, bouncing letters, letter wave, springy text, text hover effect react, animated heading, wavy text

## When to use

- Section titles and hero headlines that should feel alive on hover.
- Celebration moments: fire play() after a success.
- Logos and wordmarks on playful landing pages.

## When not to use

- Body copy or long headings; the motion becomes noise.
- Use text-shimmer to signal ongoing work.
- Use rubber-band-text when the letters should be grabbable.

## Installation

### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/wave-text
pnpm dlx shadcn@latest add @uiarc/wave-text
yarn dlx shadcn@latest add @uiarc/wave-text
bunx --bun shadcn@latest add @uiarc/wave-text
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/wave-text.json
```

### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/wave-text/wave-text.tsx`

   The source is in the registry item: https://uiarc.dev/r/wave-text.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

## Usage

```tsx
import { WaveText } from "@/components/arc/wave-text/wave-text";

export function Title() {
  return <WaveText as="h2" text="Ride the wave" variant="bounce" />;
}
```

## API reference

### WaveText

Text whose letters ride a travelling wave. Hovering sends a ripple out from the letter under the pointer and a sweep runs when the text scrolls into view. Every letter is its own spring, so motion overlaps and follows through.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `text` (required) | `string` | – | The text. Words wrap as whole words. |
| `as` | `"h1" \| "h2" \| "h3" \| "h4" \| "p" \| "span" \| "div"` | `"span"` | Element to render. |
| `variant` | `"wave" \| "bounce" \| "scatter"` | `"wave"` | wave rises and settles, bounce hops and lands with a squash, scatter knocks letters loose and pulls them home. |
| `trigger` | `"hover" \| "in-view" \| "both" \| "manual"` | `"both"` | What starts the motion. manual only runs play() from the ref. |
| `amplitude` | `number` | `0.4` | Peak lift as a fraction of the font size. |
| `stagger` | `number` | `0.032` | Seconds between neighbouring letters. |
| `color` | `string` | `var(--accent)` | Color a letter takes at the top of its travel, fading back as it settles. Pass "currentColor" to keep one color. |
| `ref` | `Ref<{ play: (from?: number) => void }>` | – | Imperative handle. play(from) sends a wave outward from a letter index. |
| `className` | `string` | – | Extra class on the root. |
| `style` | `CSSProperties` | – | Inline styles on the root. |

## Accessibility

- Screen readers get the text once from a visually hidden copy; the animated letters are aria-hidden, so words are never spelled out letter by letter.
- It is not interactive and adds no tab stops; hover only adds motion.
- Reduced motion disables every sweep and ripple.

## Motion

- Each letter is a spring (wave, scatter) or a small gravity body with a bouncy floor (bounce), integrated in one rAF loop.
- Kicks are scheduled per letter with a stagger, so the wave visibly travels.
- Entering the text ripples the whole line from the entry letter; moving along it pushes a short swell that follows the pointer.
- Kicks set velocity rather than add to it, so lingering never pumps letters higher.
- Wave letters tilt in the direction of travel; bounce letters stretch in flight and squash on landing.

## Responsive behavior

- Offsets are in em, so the motion scales with the font size.
- Touch drags along the text trigger the same ripple as hover.
- Words wrap as whole words at narrow widths.

## Performance

- The loop runs only while letters move and writes one transform per letter.
- The in-view sweep uses one IntersectionObserver that disconnects after the first run.

## Notes for AI

- Use it on headings and short labels; keep it under about 40 letters.
- Use trigger="manual" with the ref to fire a wave on an event, such as a successful submit.
- bounce is the most playful; wave suits calm brands; scatter works for a single word.

## Related

- [Text reveal](https://uiarc.dev/components/text-reveal/markdown): Reveal a short piece of content with restrained motion.
- [Text shimmer](https://uiarc.dev/components/text-shimmer/markdown): Show ongoing work with a calm light across the words.
- [In-view title](https://uiarc.dev/components/in-view-title/markdown): Bring a section title in as it scrolls into view.

## Also in text effects

- [Text morph](https://uiarc.dev/components/text-morph/markdown): Morph a label into its next state, letter by letter.

## Guidance for AI tools

Wave text: Letters ride a springy travelling wave on hover or in view, with wave, bounce, and scatter variants. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt
