Text Dice Rotator
The Text Rotator is a 3D “rolling dice” effect, powered by GSAP, that makes individual letters tumble into place as a word flips to the next one, cycling through a list of words you define. It also respects the user’s `prefers-reduced-motion` setting, so visitors who prefer less animation simply see the words swap without the spinning motion.
Unique components for WP.
ONLY FOR
BREAKDANCE
THIS IS AMAZING STUFF
Instructions
"wordClass": "tr-word"
The class name used to find the element that actually holds the text inside the container. The script looks for an element with this class inside the selector's element (e.g., <h1><span class="tr-word">Hello</span></h1>). If the container itself has the class, the container is used directly. A leading dot is stripped automatically, so .tr-word and tr-word both work. If no element with this class exists, initialization fails with a warning.
"words": ["OXYGEN 6"]
The array of words/phrases to rotate between. Each entry can be plain text or HTML (like "<b>Bold</b>"), since the parser walks the HTML and splits it into individual characters while preserving inline tags. Note the interesting logic: the text currently inside the tr-word element is treated as the first word in the sequence, and any entries in words whose plain text differs from it are appended after it. So the sequence is: existing content first, then the configured words that aren't duplicates.
"speed": 0.22
The duration, in seconds, of one full 90° face rotation of each character die. The total roll duration is calculated as spins × 4 + 1 quarter-turns multiplied by this value. With the defaults (spins: 1), the roll takes 5 × 0.22 = 1.1 seconds per character. Lower values = faster, snappier flipping; higher values = slower, more dramatic rolling.
"spins": 1
How many full 360° revolutions each character makes during a single word transition. Each spin is 4 quarter-turns, and one extra quarter-turn is always added so the die lands on the correct face. spins: 0 means a minimal single quarter-turn flip; spins: 3 means each character tumbles three full times before settling — much more theatrical.
"stagger": 0.06
The delay, in seconds, between the start of one character's roll and the next. This creates the cascading "wave" effect where letters flip one after another rather than all simultaneously. With 0.06, each subsequent character starts its animation 60ms after the previous one. Set to 0 and all characters roll in perfect unison.
"letterSpacing": 0
Extra horizontal space added between characters, in pixels (a number), or as a string with units. If a string ends in em, it's calculated relative to the rotator element's font size; if it ends in rem, relative to the root font size; otherwise it's treated as pixels. This matters because each character is rendered in its own fixed-width box — this value is added to each character's measured width so spacing looks natural. 0 means use only the natural glyph width (the element's original CSS letter-spacing is deliberately neutralized during animation).
"hold": 1.4
How long, in seconds, each word stays fully visible before rolling to the next one. This pause applies both after the initial word displays and between every subsequent transition. With 1.4, viewers get about a second and a half to read each word.
"startDelay": 0
An additional delay, in seconds, before the animation sequence begins at all. The first transition happens at startDelay + hold seconds after initialization. Useful for coordinating with page load animations or giving readers time to absorb the initial text before it starts cycling.
"loop": true
Whether the rotation repeats forever. When true, after the last word in the sequence it wraps around to the first and keeps going indefinitely. When false, the rotator stops once it reaches the final word — the sequence plays through once and holds on the last word.
"reverse": false
The direction the dice tumble. When false, characters rotate backward (negative X rotation, rolling "up and over" toward the viewer). When true, they roll the opposite direction. Purely a visual preference — it changes which way the faces appear to flip.
"ease": "power2.inOut"
The GSAP easing function applied to each character's rotation and width change. "power2.inOut" means the roll starts slow, accelerates through the middle, and decelerates into the landing — a smooth, mechanical feel. Any valid GSAP ease string works here: "power3.out", "elastic.out", "bounce.out", "none" (linear), etc. This dramatically affects the character of the animation.
"shade": 0.55
The intensity of the shading effect on the dice faces. As each character rotates, a gradient overlay (dark at top/bottom edges, a subtle light band in the middle) fades in and out based on the face's angle, simulating light hitting a 3D object. The value must be between 0 and 1: 0 disables shading entirely (flat, clean look), while values approaching 1 create strong, dramatic shadowing on the faces as they turn.
"faceBg": "auto"
The background color applied to each rotating face. This matters because the faces use backface-visibility: hidden — without an opaque background, you'd see through a character to the face behind it mid-roll, creating a messy overlap.
"auto"— the script walks up the DOM tree from the container, finds the first ancestor with a non-transparent background color, and uses that. This makes the dice blend invisibly into the page.- Any CSS color string (
"#fff","rgba(0,0,0,0.8)","transparent", etc.) — used as-is for the face background.
Honorable mention: prefers-reduced-motion
Not an option you set, but worth knowing: if the visitor has "reduce motion" enabled in their OS/browser settings, the script skips the 3D dice animation entirely and simply swaps words instantly at each hold interval. Accessibility is built in.
How options merge
The initTextRotator function does Object.assign({}, BASE, options), meaning the global TEXT_ROTATOR_OPTIONS acts as defaults, and any object you pass when calling initTextRotator(options) overrides individual keys. Missing keys fall back to hardcoded fallbacks inside the functions themselves (e.g., o.hold || 0, o.ease || "power2.inOut"), so even a partially-specified options object works safely.