split flap text.md

Split Flap Text

Departure-board lettering for headlines and status lines. Each tile flips only as far as its new letter, on a hinge, a beat after its neighbour.

Source: https://kokonutui.com/docs/texts/split-flap-text

Installation

npx shadcn@latest add @kokonutui/split-flap-text

Props

Prop Type Default Description
text? string Show this text. Leave out to cycle through words.
words? string[] [NOW BOARDING, GATE 12, ON TIME, LAST CA…` Lines to cycle through when text isn't set.
interval? number 3800 Time each word stays up, in ms.
length? number Tiles always shown, so the board doesn't change width. Defaults to the longest word.
className? string Extra classes for the root element.
tileClassName? string Classes for each tile, to recolor the board.

Source

"use client";

/**
 * @author: @dorianbaffier
 * @description: Split Flap Text
 * @version: 1.0.0
 * @date: 2026-10-22
 * @license: MIT
 * @website: https://kokonutui.com
 * @github: https://github.com/kokonut-labs/kokonutui
 */

import {
  type CSSProperties,
  type Ref,
  useEffect,
  useLayoutEffect,
  useRef,
  useState,
} from "react";
import { cn } from "@/lib/utils";

/** The order the flaps are printed in. A tile can only flip forward. */
const CHARSET = " ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789:.-/&!?";
/** One flap falling, in ms. Quick, so long trips round the drum still feel brisk. */
const FLIP = 56;
/** Tiles start a beat apart, left to right. */
const STAGGER = 40;

export interface SplitFlapTextProps {
  /** Show this text. Leave out to cycle through `words`. */
  text?: string;
  /** Lines to cycle through when `text` isn't set. */
  words?: string[];
  /** Time each word stays up, in ms. */
  interval?: number;
  /** Tiles always shown, so the board doesn't change width. Defaults to the longest word. */
  length?: number;
  className?: string;
  /** Classes for each tile, to recolor the board. */
  tileClassName?: string;
}

const clean = (value: string) =>
  [...value.toUpperCase()].map((c) => (CHARSET.includes(c) ? c : " ")).join("");

function Half({
  char,
  half,
  className,
  ref,
  style,
}: {
  char: string;
  half: "top" | "bottom";
  className?: string;
  ref?: Ref<HTMLSpanElement>;
  style?: CSSProperties;
}) {
  return (
    <span
      className={cn(
        "backface-hidden absolute inset-x-0 h-1/2 overflow-hidden bg-inherit",
        half === "top"
          ? "top-0 rounded-t-[0.12em]"
          : "bottom-0 rounded-b-[0.12em]",
        className
      )}
      ref={ref}
      style={style}
    >
      <span
        className={cn(
          "absolute inset-x-0 flex h-[200%] items-center justify-center",
          half === "top" ? "top-0" : "bottom-0"
        )}
      >
        {char}
      </span>
    </span>
  );
}

interface Flip {
  id: number;
  from: string;
  to: string;
}

function Tile({
  target,
  delay,
  reduceMotion,
  className,
}: {
  target: string;
  delay: number;
  reduceMotion: boolean;
  className?: string;
}) {
  const [shown, setShown] = useState(target);
  const [flip, setFlip] = useState<Flip | null>(null);
  const shownRef = useRef(target);
  const topRef = useRef<HTMLSpanElement>(null);
  const bottomRef = useRef<HTMLSpanElement>(null);
  const shadeRef = useRef<HTMLSpanElement>(null);

useEffect(() => {
    if (reduceMotion) {
      shownRef.current = target;
      setShown(target);
      return;
    }
    let timer: ReturnType<typeof setTimeout>;
    let id = 0;
    // Step through the drum one flap at a time until the target is up.
    const step = () => {
      const from = shownRef.current;
      if (from === target) {
        setFlip(null);
        return;
      }
      const to = CHARSET[(CHARSET.indexOf(from) + 1) % CHARSET.length];
      id += 1;
      setFlip({ id, from, to });
      timer = setTimeout(() => {
        shownRef.current = to;
        setShown(to);
        step();
      }, FLIP);
    };
    timer = setTimeout(step, delay);
    return () => clearTimeout(timer);
  }, [target, delay, reduceMotion]);

// The top flap falls on its hinge, the bottom of the next letter lands,
  // and the lower half darkens for a moment under the falling flap.
  useLayoutEffect(() => {
    if (!flip) {
      return;
    }
    const half = FLIP / 2;
    topRef.current?.animate(
      [{ transform: "rotateX(0deg)" }, { transform: "rotateX(-90deg)" }],
      {
        duration: half,
        easing: "cubic-bezier(0.5, 0, 0.9, 0.6)",
        fill: "forwards",
      }
    );
    bottomRef.current?.animate(
      [{ transform: "rotateX(90deg)" }, { transform: "rotateX(0deg)" }],
      {
        duration: half,
        delay: half,
        easing: "cubic-bezier(0.2, 0.6, 0.3, 1)",
        fill: "both",
      }
    );
    shadeRef.current?.animate(
      [{ opacity: 0 }, { opacity: 1 }, { opacity: 0 }],
      {
        duration: FLIP,
        easing: "linear",
      }
    );
  }, [flip]);

const front = flip ? flip.to : shown;
  const back = flip ? flip.from : shown;

return (
    <span
      aria-hidden="true"
      className={cn(
        "relative inline-block h-[1.15em] w-[0.72em] rounded-[0.12em] bg-zinc-900 text-zinc-50 shadow-[inset_0_0_0_1px_rgb(255_255_255/0.06)] [perspective:5em]",
        className
      )}
    >
      {/* Still halves: the next letter's top, the old letter's bottom. */}
      <Half char={front} half="top" />
      <Half char={back} half="bottom" />
      <span
        className="pointer-events-none absolute inset-x-0 bottom-0 h-1/2 rounded-b-[0.12em] bg-black/50 opacity-0"
        ref={shadeRef}
      />
      {flip && (
        <> 
          <Half
            char={flip.from}
            half="top"
            key={`t-${flip.id}`}
            ref={topRef}
            style={{ transformOrigin: "50% 100%" }}
          />
          <Half
            char={flip.to}
            half="bottom"
            key={`b-${flip.id}`}
            ref={bottomRef}
            style={{ transformOrigin: "50% 0%", transform: "rotateX(90deg)" }}
          />
        </>
      )}
      {/* The hinge. */}
      <span className="pointer-events-none absolute inset-x-0 top-1/2 h-[0.04em] -translate-y-1/2 bg-black/70" />
    </span>
  );
}

/**
 * Departure-board lettering. Each tile flips through its drum only as far
 * as its new letter, the tiles start a beat apart, and the flaps fall on a
 * real hinge with the half below darkening under them.
 */
export default function SplitFlapText({
  text,
  words = ["NOW BOARDING", "GATE 12", "ON TIME", "LAST CALL"],
  interval = 3800,
  length,
  className,
  tileClassName,
}: SplitFlapTextProps) {
  const [index, setIndex] = useState(0);
  const [reduceMotion, setReduceMotion] = useState(false);

useEffect(() => {
    const query = window.matchMedia("(prefers-reduced-motion: reduce)");
    setReduceMotion(query.matches);
    const onChange = () => setReduceMotion(query.matches);
    query.addEventListener("change", onChange);
    return () => query.removeEventListener("change", onChange);
  }, []);

useEffect(() => {
    if (text !== undefined || words.length < 2) {
      return;
    }
    const id = window.setInterval(
      () => setIndex((i) => (i + 1) % words.length),
      interval
    );
    return () => window.clearInterval(id);
  }, [text, words.length, interval]);

const value = clean(text ?? words[index] ?? "");
  const size =
    length ??
    Math.max(
      value.length,
      ...(text === undefined ? words.map((w) => w.length) : [0])
    );
  const padded = value.padEnd(size, " ");

return (
    <span
      className={cn(
        "inline-flex gap-[0.08em] font-semibold text-3xl tabular-nums leading-none sm:text-5xl",
        className
      )}
    >
      {/* Only announce text the app sets; a board cycling on its own would
          talk over the reader every few seconds. */}
      <span
        aria-live={text === undefined ? "off" : "polite"}
        className="sr-only"
      >
        {value}
      </span>
      {[...padded].map((char, i) => (
        <Tile
          className={tileClassName}
          delay={i * STAGGER}
          key={i.toString()}
          reduceMotion={reduceMotion}
          target={char}
        />
      ))}
    </span>
  );
}