# Rotating Word Headline

> A hero headline that cycles its highlighted word: shared letters glide into place, the marker stretches to fit, and the rest of the sentence flows smoothly into its new line breaks.

Canonical: https://gsapvault.com/effects/rotating-word-headline
Live demo: https://gsapvault.com/demos/rotating-word-headline/index.html

| Property | Value |
|----------|-------|
| Type | effect |
| Tier | paid |
| Price | £5 |
| Difficulty | intermediate |
| Plugins | Core GSAP only |
| Techniques | text-animation, text-rotation, letter-morph, flip-reflow, marker-highlight, auto-cycle, pause-control, reduced-motion |
| Uses Lenis | No |

## Lighthouse, as measured

Google Lighthouse on the demo, 15 September 2026. A measurement of the demo as shipped, not a promise for your page.

| Category | Score |
|----------|-------|
| Accessibility | 100 |
| Best practices | 100 |

No performance score is published: it depends on the deployment (server compression, caching, CDN, connection and device) rather than on the code, so measure it where it will live.

## Overview

The "We build websites for [architects]" hero line, done properly. Most rotating-word snippets swap a word inside a fixed-width box, so the sentence either jumps or carries a gap sized for the longest word. Here the highlighted word is part of the sentence: when it changes, every other word glides to where the new line breaks put it, including onto a different line.

Three transition styles share that behaviour. Morph keeps the letters the two words share and slides them to their new places while the rest drop away. Roll turns each letter over on a drum. Slot runs the letters through a mask like a counter. All three are clipped to the marker as it stretches, so the change reads as one window resizing rather than letters flying loose.

It is a drop-in for an existing hero: plain markup with the words listed inside a span, one data attribute for the interval, and no plugins beyond GSAP core.

## Features

- Wrap-aware reflow: surrounding words and punctuation glide to their new positions, even across lines
- Morph style matches letters shared by consecutive words and moves them on a shallow arc
- Roll and Slot styles for a mechanical drum or a masked counter, switchable by attribute
- Pill or plain: one attribute drops the container so the word changes in accent colour straight on the page
- Marker highlight stretches and travels with the word, with optional per-word colours via data-accent
- Reserves the height of the tallest wrap so content below the headline never shifts
- Dwell progress line inside the marker; pauses on hover, off-screen, in a hidden tab or from a Pause button
- Click or tap the word to advance; Next, Previous and Pause buttons connect with aria-controls
- Screen readers hear one complete sentence listing every word, never the animation
- Reduced motion stops the auto-cycle and swaps words instantly on request; no-JS shows the first word
- rotatingheadline:change event and full revert() teardown restoring the original markup

## Use Cases

- Agency and freelancer heroes naming the clients or sectors they serve
- SaaS landing pages cycling the jobs, teams or industries a product is for
- Event and venue pages rotating dates, cities or programme strands in a headline
- Recruitment pages cycling the roles a company is hiring for
- Portfolio intros that rotate disciplines without a separate carousel

## Vibe-Code Ready Setup

This effect includes `START-HERE-AI.md`, a product-specific copy-paste setup prompt for Cursor, Claude Code, ChatGPT, GitHub Copilot, Windsurf, and other coding assistants. It tells the assistant to inspect the existing stack, integrate the supplied files, preserve the design, scope selectors, retain accessibility and responsive behaviour, add framework-appropriate GSAP cleanup, and report what it tested.

[How AI-assisted setup works](https://gsapvault.com/vibe-coding)

## How It Works

On load the script keeps the headline's original markup, adds a screen reader sentence, and builds a hidden-from-assistive-tech visual copy in which every word is its own inline-block. The rotating slot holds one span per letter, and a marker element sits behind the whole sentence.

Each change is a FLIP. The script records where every word, letter and the marker are, lays out the next word, and records the new positions. The words are then transformed back to where they were and animated to zero, so line-break changes become a glide. In Morph, letters present in both words are reused and moved, choosing the match closest in relative position; letters with no partner fall away and new ones rise in.

While a change runs the slot is clipped to the marker's live rectangle, which is why letters never appear outside the highlight. When the word moves to another line, new letters wait for the marker to arrive. A single dwell tween drives both the progress line and the next change, so pausing is one call and nothing drifts.

## Documentation

How this effect works and how it goes into a page. The reference you use once you own the files (worked examples, events, the programmatic API, the class list) ships with the download.

### Quick Start

**1. Add to your HTML `<head>`:**

_Code snippet omitted: it ships with the download._

**2. Add before closing `</body>` tag:**

_Code snippet omitted: it ships with the download._

**3. Write your headline, listing the words inside the slot:**

_Code snippet omitted: it ships with the download._

The first word is the one visitors without JavaScript see, so make it the one that reads best on its own.

**4. Optional controls anywhere on the page:**

_Code snippet omitted: it ships with the download._

### Using It With Your Own Design

**What the effect needs from your markup:** an element with `.rotating-headline`, containing one `.rotating-headline__slot` as a **direct child**, which contains two or more `.rotating-headline__word` spans. Text before and after the slot can be anything, including inline elements such as `<em>` (each is kept whole when it moves). Punctuation written directly after the slot, with no space, stays glued to it so a full stop never wraps onto its own line. Controls find their headline through `aria-controls`, so the headline needs an `id` if you use them.

**What is only the demo's styling:** the `.showcase-*` shell, `.rw-controls` and its buttons, the `.hero__eyebrow` line, the dark palette and Mona Sans. The headline's font, size, weight, letter spacing and `max-width` are yours to change; the effect measures whatever the browser lays out.

**CSS the effect depends on:**

- `.rotating-headline__flow` and `.rotating-headline__char` must be `display: inline-block` with `white-space: pre`. Transforms do not apply to plain inline elements, and the space in a phrase such as "record labels" must keep its width.
- `.rotating-headline__visual` needs `position: relative` and `isolation: isolate`, and `.rotating-headline__marker` needs `position: absolute; z-index: -1`. That is what keeps the marker behind the neighbouring words when it travels to another line.
- `.rotating-headline__slot` stays `display: inline-block` with `white-space: nowrap`. Its padding is the marker's padding.
- `.rotating-headline__word + .rotating-headline__word { display: none; }` is the no-JS fallback. Keep it.
- `.rotating-headline__leaver { position: absolute; }` holds outgoing letters where they were while they animate away.

The marker colour is `--rh-accent` and the text on it is `--rh-accent-ink`. Pick a pair that clears 4.5:1.

### Options

Set these on the `.rotating-headline` element.

| Attribute | Values | Default | Description |
|-----------|--------|---------|-------------|
| `data-rotate-style` | `morph`, `roll`, `slot` | `morph` | Transition style. Can be changed at runtime |
| `data-rotate-marker` | `pill`, `none` | `pill` | `none` drops the pill and colours the word with `--rh-accent` instead. Can be changed at runtime |
| `data-rotate-interval` | Seconds (min `0.6`) | `2.6` | How long each word stays before the next change |
| `data-rotate-speed` | Multiplier | `1` | Transition speed. `1.5` is faster, `0.7` slower |
| `data-rotate-autoplay` | `true`, `false` | `true` | Cycle automatically. With `false` words change only on click or controls |
| `data-rotate-pause-on-hover` | `true`, `false` | `true` | Hold the current word while a mouse is over the headline |
| `data-rotate-click` | `true`, `false` | `true` | Clicking or tapping the word advances it |
| `data-rotate-reserve` | `true`, `false` | `true` | Reserve the height of the tallest wrap so content below never moves |
| `data-rotate-label` | Text | Generated | The sentence screen readers hear. Defaults to the headline with the words joined by commas |

On a `.rotating-headline__word`:

| Attribute | Values | Description |
|-----------|--------|-------------|
| `data-accent` | Any CSS colour | Marker colour while this word is showing; the marker blends between colours |

Controls (any element, connected with `aria-controls="<headline id>"`):

| Attribute | Description |
|-----------|-------------|
| `data-rotate-control="toggle"` | Pause or resume. Its text switches between Pause and Play |
| `data-rotate-control="next"` / `"prev"` | Step forwards or backwards |
| `data-rotate-style-option="morph"` | Switch style; the matching button gets `aria-pressed="true"` |
| `data-rotate-marker-option="none"` | Switch between pill and plain word; the matching button gets `aria-pressed="true"` |

### Accessibility

- **Screen readers** get a visually hidden sentence listing every word ("We design and build websites for architects, museums, record labels."). The animated copy is `aria-hidden`, so nothing is announced on each change.
- **Pause control:** content that moves on its own for more than five seconds needs a way to stop it (WCAG 2.2.2). Add a `data-rotate-control="toggle"` button, as the demo does.
- **Automatic holds:** the cycle pauses while a mouse is over the headline, while it is off-screen and while the tab is hidden.
- **Reduced motion:** with `prefers-reduced-motion: reduce` there is no auto-cycle and no transition. Next, Previous and clicks still change the word instantly, and pressing Play cycles with instant swaps. Switching the preference while the page is open rebuilds cleanly.
- **No JavaScript** (or GSAP failing to load): the headline renders as written with the first word highlighted.
- **Touch:** tap the word to advance. Hover-hold only applies to a mouse.

### Dependencies

**Required:**
- GSAP 3.12+ (the demo is pinned to 3.15.0). No plugins.

**Browser features:** `ResizeObserver`, `IntersectionObserver` and CSS `clip-path: inset()`, available in all current browsers.

## What You Get

- `index.html`: working demo page
- `assets/script.js`: commented, readable source
- `assets/style.css`: effect styles
- `README.md`: full documentation with examples and framework integration notes
- `START-HERE-AI.md`: product-specific copy-paste prompt for AI-assisted setup
- `LICENSE.txt`: standard license terms
- Lifetime updates: re-download anytime from your library

## Get the Code

This is a premium effect. The standard license costs £5 one-time and covers unlimited personal and commercial projects with no attribution required for our code. Bundled third-party assets retain their own licences and attribution requirements. The only restrictions: no redistribution of the code itself and no competing effect libraries.

- [Buy Rotating Word Headline](https://gsapvault.com/effects/rotating-word-headline)
- [The Vault (£99 one-time, best value): every collection in the Vault library, plus future items added to those collections](https://gsapvault.com/effects)

## Judge the Code Quality First

These related effects are free with complete source published, written to the same production standard (cleanup functions, reduced-motion support, framework-agnostic):

- [Typewriter Text](https://gsapvault.com/effects/typewriter-text.md): A typewriter that types a line character by character, holds it, accelerates through deletion, and cycles to the next phrase, with optional cursor, status and progress hooks.
- [Scroll Text Highlight](https://gsapvault.com/effects/scroll-text-highlight.md): A scrubbed orange-to-lime reading front lifts each active word before completed copy settles to white and unread copy remains ghosted.

---

From [GSAP Vault](https://gsapvault.com): production-ready GSAP animation effects. Full catalog for agents: https://gsapvault.com/llms-full.txt