# Text Rotate

> A rotating word for headlines that cycles through a list of words or short phrases in place, inside a sentence that reflows to fit each one.

- Type: React component (Text & Effects)
- Access: Pro (the source needs a Wingo UI Pro plan, see https://wingo-ui.com/pricing)
- Version: 1.0.0
- Install: `npx wingo-ui@latest add text-rotate`
- Docs: https://wingo-ui.com/components/text-rotate

## Interaction

Every few seconds the word slides, fades, blurs or flips to the next one, letter by letter if you like, while the sentence reflows to fit it. Hover or focus it to hold the current word when pauseOnHover is on. It waits while the tab is hidden or the text is off screen, screen readers hear the full list once, and with reduced motion on the current word simply stays.

## Installation

```bash
npx wingo-ui@latest add text-rotate
```

Pro item: run `npx wingo-ui@latest login` once with a Pro account. The CLI adds the files, their dependencies and a version record for updates.

With shadcn: `npx shadcn@latest add @wingo-ui/text-rotate` (needs the @wingo-ui registry with your API key in components.json)

Files:

- `components/ui/text-rotate.tsx`

npm dependencies: `npm i motion`

Wingo UI dependencies (installed automatically):

- [Motion presets](https://wingo-ui.com/components/motion) ([Markdown](https://wingo-ui.com/components/motion.md))
- [Tones](https://wingo-ui.com/components/tones) ([Markdown](https://wingo-ui.com/components/tones.md))
- [UIProvider](https://wingo-ui.com/components/ui-config) ([Markdown](https://wingo-ui.com/components/ui-config.md))
- [useControllableState](https://wingo-ui.com/components/use-controllable-state) ([Markdown](https://wingo-ui.com/components/use-controllable-state.md))

## Usage

```tsx
import { TextRotate } from "@/components/ui/text-rotate"

export function Hero() {
  return (
    <h1 className="text-5xl font-semibold tracking-tight">
      Ship <TextRotate words={["faster", "smarter", "together"]} tone="brand" highlight="pill" />
    </h1>
  )
}

// Letter by letter with a 3D flip:
// <TextRotate words={["design", "build", "launch"]} effect="flip" by="char" />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `words?` | `string[]` | `"[\"faster\", \"smarter\", \"together\"]"` | The words or short phrases to cycle through, in order. A single word just sits still. |
| `interval?` | `number` | `2500` | Milliseconds each word stays on screen before the next one comes in. |
| `effect?` | `"slide-up" \| "slide-down" \| "fade" \| "blur" \| "flip"` | `"slide-up"` | How words swap. Slides and the 3D flip move on a snappy spring; fade and blur cross-fade on a smooth one. |
| `by?` | `"word" \| "char"` | `"word"` | word swaps the whole word at once; char staggers its letters in and out. |
| `stagger?` | `number` | `25` | With by="char", milliseconds between one letter and the next. |
| `tone?` | `"inherit" \| "neutral" \| "brand" \| "success" \| "warning" \| "danger" \| "info"` | `"inherit"` | Color of the rotating word. inherit keeps the color of the sentence around it; the tones use the readable soft-foreground shade. |
| `color?` | `string` | `""` | Any CSS color for the rotating word and its highlight. Replaces the tone. Leave empty to use the tone. |
| `highlight?` | `"none" \| "underline" \| "pill"` | `"none"` | Decoration behind the word that resizes with it: a soft underline, or a rounded pill tinted with the tone. |
| `paused?` | `boolean` | `false` | Stops the timer and keeps the current word. Changing index still swaps words. |
| `loop?` | `boolean` | `true` | Starts over after the last word. Turn it off to stop on the last one, for a sentence that settles. |
| `pauseOnHover?` | `boolean` | `false` | Holds the current word while a mouse is over it or keyboard focus is inside it. |
| `as?` | `"span" \| "div"` | `"span"` | The root element. span sits inline in a sentence; div for a word on its own line. |
| `defaultIndex?` | `number` | `0` | The word shown first when the rotation runs on its own. |
| `index?` | `number` |  | The shown word, for a controlled rotation. Pair it with onIndexChange; the timer still asks for the next index. |
| `onIndexChange?` | `(index: number) => void` |  | Called with the next index whenever the word changes, from the timer or from outside. |
| `classNames?` | `Partial<Record<"word" \| "char" \| "highlight", string>>` |  | Extra classes for the rotating word, each letter in char mode, and the highlight box around it. |
| `className?` | `string` |  | Extra classes for the root element. |
| `ref?` | `Ref<HTMLElement> (a useRef object or an (el) => void callback)` |  | The root element. |

## Parts

### TextRotateEffect (type)

The effect names: "slide-up" | "slide-down" | "fade" | "blur" | "flip".

### TextRotateBy (type)

The animated unit: "word" | "char".

### TextRotateHighlight (type)

The decoration: "none" | "underline" | "pill".

### TextRotateTone (type)

A tone from lib/tones, or "inherit" to keep the surrounding text color.

### TextRotateSlot (type)

The keys of classNames: "word" | "char" | "highlight".

### TextRotateProps (type)

The props of TextRotate, plus every attribute of the root element.

## Examples

- **Hero headline**: The default slide-up inside an h1; the line reflows as words change length.
- **Brand pill**: tone="brand" with highlight="pill" and a blur swap; pauseOnHover holds the word under the mouse.
- **Letter flip**: by="char" with the 3D flip; each letter turns over 35ms after the one before it.
- **Controlled with buttons**: index and onIndexChange put the rotation in your hands; paused turns the timer off.
- **Inside a paragraph**: A longer phrase in running text, cross-fading every 3 seconds and wrapping on narrow screens.

## See also

- [Text Animate](https://wingo-ui.com/components/text-animate) ([Markdown](https://wingo-ui.com/components/text-animate.md))
- [Hero Section](https://wingo-ui.com/components/hero-section) ([Markdown](https://wingo-ui.com/components/hero-section.md))
- [Gravity Letters](https://wingo-ui.com/components/gravity-letters) ([Markdown](https://wingo-ui.com/components/gravity-letters.md))
- [Tones](https://wingo-ui.com/components/tones) ([Markdown](https://wingo-ui.com/components/tones.md))

---

Canonical: https://wingo-ui.com/components/text-rotate
More components: https://wingo-ui.com/components · Index for agents: https://wingo-ui.com/llms.txt