Word Rotate

A phrase where one word swaps for the next in the same spot, cycling through a list. The slot is as wide as the longest word, so nothing around it jumps.

Motionv0.1.0experimentalWCAG 2.2 AAView spec

Optional, and kept apart.

Nothing here is included in a project unless you add it, and the plain component it builds on is unchanged. This effect is decoration: it is hidden from screen readers, stands still for visitors who prefer reduced motion, and can be paused. Use Still on a preview to see that version.

Built for

import { WordRotate } from "@rdloom/react";

export default function WordRotateBasicExample() {
  return (
    <div className="flex w-full justify-center text-2xl font-semibold">
      <p>
        Built for <WordRotate className="text-[var(--rd-color-action-primary)]" words={["teams", "makers", "studios", "everyone"]} />
      </p>
    </div>
  );
}

Installation

CLI

Manual

npm

pnpm

yarn

bun

npx rdloom add word-rotate

Copies the source into src/components/rdloom. Edit it freely: rdloom upgrade merges later versions into your changes.

It also adds rdloom-motion.css next to your tokens and imports it from the tokens file, once: no setup, and no inline styles. The plain components you already use are untouched.

Use another registry client

npx shadcn@latest add https://rdloom.vimalbhatt.com/r/word-rotate.json

Works, but without upgrade tracking, and you import the motion CSS yourself.

Usage

import { WordRotate } from "@rdloom/react";

<div className="flex w-full justify-center text-2xl font-semibold">
  <p>
    Built for <WordRotate className="text-[var(--rd-color-action-primary)]" words={["teams", "makers", "studios", "everyone"]} />
  </p>
</div>

In a heading

Your data, secure

import { WordRotate } from "@rdloom/react";

// announce reads each new word out politely, for when the word is part of the message.
export default function WordRotateInAHeadingExample() {
  return (
    <div className="flex w-full justify-center">
      <h3 className="text-xl font-semibold">
        Your data, <WordRotate announce duration={3000} words={["secure", "portable", "yours"]} />
      </h3>
    </div>
  );
}

API Reference

Defined by the spec. Components also accept the props of the React Aria component they wrap.

Prop	Type	Default
`words`required The words to cycle through, in order.	`string[]`	none
`duration` Milliseconds each word stays before the next replaces it.	`number`	`2500`
`announce` Announces each new word politely to screen readers. Off by default: most rotating words are decoration.	`boolean`	`false`
`label` Accessible name for the whole slot when announce is off. Defaults to all the words, joined with commas.	`string`	none
`isPaused` Stops the animation and shows the finished text. Moving content that lasts more than five seconds should be stoppable.	`boolean`	`false`

Accessibility

Role group, WCAG 2.2 AA. Tested with axe and keyboard tests; screen reader checks are in the audit checklist.

Keyboard

Not interactive.

Screen readers announce

Without announce: the list of all words, once
With announce: each new word, politely

What your code must do

Without announce, the slot has an accessible name listing all the words, and the visible word is hidden from assistive technology
With announce, the visible word sits in a polite live region and is read when it changes
Hidden sizing copies of the other words are invisible to everyone, so they are never read twice
Decoration only: the animated layers are hidden from assistive technology and never take focus
Stands still for visitors who ask for less motion (prefers-reduced-motion), and can also be shown still with the rdm-still class or isPaused
In forced-colors (high contrast) mode the text is drawn in the system colours
Does not flash: nothing changes more than three times in a second (WCAG 2.3.1)
Optional: it is a separate component, so projects that do not add it carry none of its code

Guidelines

Use it when

A headline such as Built for teams, makers, studios where one word changes
Showing the range of things a product handles

Avoid it when

Words that carry information people must not miss
Lists longer than six words

Don't

Turning announce on for a purely decorative swap, which interrupts reading
Putting a different meaning in each word and expecting every one to be noticed

Design tokens

The semantic tokens this component uses. Change them once and every component follows; see Design tokens.

--rd-color-text-default
--rd-color-text-muted