Dynamic Text
Morphing text where shared letters travel, old ones fall and new ones land, with decode and cycle modes.
Installation
npx shadcn@latest add @kokonutui/dynamic-text
Props
| Prop |
Type |
Default |
Description |
mode? |
DynamicTextMode |
"morph" |
morph: letters travel, fall and land. decode: monospace cells scramble and lock left to right. cycle: morphs through words with a greeting rhythm. |
text? |
string |
|
The string to show. Change it to animate. When set, words is ignored. |
words? |
(string | Greeting)[] |
|
Words to rotate through when text is not set. |
interval? |
number |
|
Milliseconds each word holds. In cycle mode this is the first word's hold; the middle words speed up from there. |
loop? |
boolean |
|
Start over after the last word. Defaults to true, except in cycle. |
onComplete? |
() => void |
|
Called once the last word is shown. Never called when looping. |
className? |
string |
|
Extra classes for the root element. |
DynamicTextMode
type DynamicTextMode = "morph" | "decode" | "cycle";
Greeting
| Field |
Type |
Description |
text |
string |
|
lang? |
string |
BCP 47 language tag, so screen readers pronounce each word correctly. |
Source
"use client";
/**
* @author: @dorianbaffier
* @description: Dynamic Text. Morphing text where letters are physical
* objects: shared letters travel to their new place on a spring arc, leaving
* letters fall off the baseline, entering letters drop in and land, and digits
* roll like a counter. Also has a `decode` mode (cells scramble and lock left
* to right) and a `cycle` mode (the greeting rhythm).
* @version: 2.0.0
* @date: 2026-10-14
* @license: MIT
* @website: https://kokonutui.com
* @github: https://github.com/kokonut-labs/kokonutui
*/
import {
type RefObject,
useEffect,
useLayoutEffect,
useRef,
useState,
} from "react";
import { cn } from "@/lib/utils";
export interface Greeting {
text: string;
/** BCP 47 language tag, so screen readers pronounce each word correctly. */
lang?: string;
}
export type DynamicTextMode = "morph" | "decode" | "cycle";
export interface DynamicTextProps {
/**
* `morph`: letters travel, fall and land. `decode`: monospace cells scramble
* and lock left to right. `cycle`: morphs through `words` with a greeting
* rhythm (a long first word, faster middle words, a hold on the last).
*/
mode?: DynamicTextMode;
/** The string to show. Change it to animate. When set, `words` is ignored. */
text?: string;
/** Words to rotate through when `text` is not set. */
words?: (string | Greeting)[];
/**
* Milliseconds each word holds. In `cycle` mode this is the first word's
* hold; the middle words speed up from there.
*/
interval?: number;
/** Start over after the last word. Defaults to true, except in `cycle`. */
loop?: boolean;
/** Called once the last word is shown. Never called when looping. */
onComplete?: () => void;
className?: string;
}
const DEFAULT_WORDS: Record<DynamicTextMode, (string | Greeting)[]> = {
morph: ["Create", "Iterate", "Repeat", "Ship"],
decode: ["Hello, world", "Build 4096 ready", "All systems go"],
cycle: [
{ text: "Hello", lang: "en" },
{ text: "こんにちは", lang: "ja" },
{ text: "Bonjour", lang: "fr" },
{ text: "Hola", lang: "es" },
{ text: "안녕하세요", lang: "ko" },
{ text: "Ciao", lang: "it" },
{ text: "Hallo", lang: "de" },
],
};
const DEFAULT_INTERVAL: Record<DynamicTextMode, number> = {
morph: 2200,
decode: 2800,
cycle: 900,
};
/
* Text helpers ---------------------------------------------------------- */
// Function implementations and logic continue from here...