Flip Words

A headline word that flips through a list. Each replacement enters letter-by-letter out of an 8px blur while the outgoing one drifts up, blurs and scales away.

decorativeclientuiv1.1.0

Flip Words — live renderaceternity-flipwords--headline ↗

Rendered from the story the storybook (a11y) CI gate runs axe against — the preview can't show something that hasn't been verified.

Install

Two equivalent paths — the URL works in any shadcn-CLI setup; the alias works once you've registered @interlace in your components.json.

Via shadcn URL

npx shadcn@latest add https://ds.interlace.tools/r/flip-words.json

With the @interlace alias

npx shadcn@latest add @interlace/flip-words

Behavior

What this component does — the keyboard path, the measured colour, the text equivalent and the states it can be in. Every figure below is read out of the test or the source that enforces it by scripts/build-behavior-map.mjs, so nothing here can outlive the gate that keeps it true.

Text equivalent

packages/ui/src/aceternity/flip-words.tsx ↗

A chart's alt text is not a sentence about the chart — the equivalent of the data is the data. This is what a screen reader gets, read out of the source the install writes into your tree.

Label, not a data equivalentShips sr-only copy

Ships sr-only copy for what the visual carries by position, colour or icon alone — a label, not a full data equivalent.

Runtime contract

packages/ui/vitest.config.ts ↗

Where it renders, how narrow it survives, and whether its lines are inside the coverage gate — three answers a consumer needs before the paste, not after the bug.

Render boundary: 'use client'
Hydrates. It brings JavaScript to any route that imports it — put the boundary here, not at the page.
Minimum viewport: none declared
No width floor: it takes the width it is given. Its container owns the layout question.
Coverage gate: not in the gate
The 100% gate currently covers src/charts/**/*.{ts,tsx} and src/lib/**/*.{ts,tsx} and src/primitives/{button-variants,data-state-model,meter-scale,skeleton-variants}.ts and src/primitives/{alert,aspect-ratio,avatar,badge,box,breadcrumb,button,callout,card,checkbox,container,data-state,focus-ring,grade-badge,grid,input,label,meter,pagination,published-date,reading-time,section,section-boundary,separator,skip-link,stack,stat-strip,tag,textarea,typography,visually-hidden}.tsx. This file is outside it — the glob widens in phase 7.2.

History

This component is at v1.1.0, first shipped in @interlace/ui 1.0.0. The version is stamped as a banner into the file the install writes, so the copy in your tree says which one you have — compare it with the number above before deciding whether to re-run the install.

No release note names this component yet. It shipped with the release above and has not changed since — see the full changelog for what moved elsewhere in the DS.

Import

Single named export.

Public API

import { FlipWords } from '@/components/ui/aceternity/flip-words';

Anatomy

Extracted from the primitive's JSDoc header. The source is the only documentation that can't drift.

FlipWords                        (span — data-slot="flip-words")
    ├─ span.sr-only aria-live=polite   (the announced text)
    └─ span[data-slot=flip-words-static]  (under reduce)
       | motion.span[data-slot=flip-words-word]
           └─ span per word
               └─ motion.span per letter
The visible word is `aria-hidden` in BOTH branches. Everything a screen
reader gets comes from the polite live region, so the letter-by-letter
staging is never spelled out.

API reference

Parsed from the type declarations in the source — the same file the install writes into your tree, so this table can't drift from the component you get.

FlipWordsProps

Prop	Type	Description
words*	string[]	Ordered list of words (or short phrases) to cycle through. Each entry is animated in word-by-word and letter-by-letter, then animated out before the next entry enters.
duration	number	Time in milliseconds a word stays on screen before flipping to the next one. The enter/exit animation runs on top of this dwell time. @default 3000
defaultIndex	number	The index of the word shown on first render when the component is uncontrolled. Ignored when `index` is provided. @default 0
index	number	Controlled index of the active word. When provided, the component will not advance on its own — drive it from the parent and pair with `onIndexChange`.
onIndexChange	(index: number, details: { word: string }) => void	Called with the next index whenever the active word changes, in both controlled and uncontrolled modes. @default undefined
pauseOnHover	boolean	Pause cycling while the pointer is over the component, giving readers time to finish the current word. Has no effect under reduced motion (cycling is already disabled). @default false
wordStagger	number	Stagger between each word in a multi-word entry, in seconds. @default 0.3
letterStagger	number	Stagger between each letter within a word, in seconds. @default 0.05

Accessibility

Every story for this component is rendered headlessly and checked with axe-core (wcag2aa, wcag22aa, best-practice, ACT) on every PR. That gate has no continue-on-error, so what ships has zero known violations.

What follows is what static analysis can see. Axe cannot press a key and never sees an overlay open, so the operable-without-a-mouse claim lives in Behavior instead, where the keyboard path is replayed step by step.

Focus + keyboard behaviour: Native element semantics — no interaction layer to get wrong.
Focus ring (WCAG 2.2 SC 2.4.13): Not focusable — no focus indicator required.
Reduced motion: Animation is gated on prefers-reduced-motion.
ARIA in the source: aria-hidden
aria-live

Examples

3 more states from the same story file.

defaultaceternity-flipwords--default ↗

long dwellaceternity-flipwords--long-dwell ↗

pause on hoveraceternity-flipwords--pause-on-hover ↗

Dependencies

Base UI primitive: Native / no Base UI dependency
Lucide icons: none
NPM dependencies: motion
Registry dependencies: @interlace/theme
@interlace/cn
@interlace/use-reduced-motion

Source

The full implementation — components/ui/aceternity/flip-words.tsx once installed.

277 lines · TypeScript

github ↗

"use client";

import {
  type ComponentPropsWithoutRef,
  useCallback,
  useEffect,
  useId,
  useMemo,
  useState,
} from "react";

// @interlace/flip-words v1.1.0 — Interlace design system.
// Docs, props and live preview: https://ds.interlace.tools/c/flip-words
// What changed since: https://ds.interlace.tools/c/flip-words#history
// Generated banner — keep it, the upgrade diff reads this version.

/**
 * @interlace/ui — FlipWords
 *
 * A headline word that flips through a list. Each replacement enters

…257 more lines…

Registry JSON

The raw registry record — what the shadcn CLI fetches.

/r/flip-words.json