dynamic text.md

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...