# Dynamic Text
> Morphing text where shared letters travel, old ones fall and new ones land, with decode and cycle modes.

## Installation

```bash
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

```ts
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

```tsx
"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... 
```
