Streaming text

Once per app, add the registry to components.json:

{
  "registries": {
    "@pixilui": "https://pixilui.com/r/{name}.json"
  }
}

Or install from the URL, no namespace needed: npx shadcn@latest add https://pixilui.com/r/streaming-text.json

1. 1

   Install the npm packages.

   TerminalCopy

   npm install motion clsx tailwind-merge

2. 2

   Add the items it depends on, the same way.

   • Foundation
3. 3

   Copy each file to the path shown.

   components/pixilui/streaming-text.tsxCopy

   "use client";
   
   import {
     Fragment,
     forwardRef,
     useEffect,
     useLayoutEffect,
     useMemo,
     useRef,
     useState,
     useSyncExternalStore,
     type ComponentPropsWithoutRef,
     type PointerEvent,
   } from "react";
   import { AnimatePresence, motion, useReducedMotion } from "motion/react";
   import { cn } from "./lib/utils";
   import { motionTokens, reducedTransition } from "./motion-tokens";
   
   const noSubscription = () => () => {};
   
   /**
    * useReducedMotion, held at false until hydration finishes. The server cannot know the
    * preference, so reading it on the first client render would change the markup and break
    * hydration; the reduced branch takes over on the next render instead.
    */
   function useReducedMotionAfterHydration() {
     const hydrated = useSyncExternalStore(noSubscription, () => true, () => false);
     const reduced = useReducedMotion();
     return hydrated && (reduced ?? false);
   }
   
   export type StreamingTextProps = Omit<ComponentPropsWithoutRef<"div">, "children"> & {
     /** Everything received so far. Pass the growing string on every chunk; only the new words animate. */
     text: string;
     /** More text is on its way: shows the caret and holds back a word that has not finished arriving. */
     streaming?: boolean;
     /** Show a caret at the end while streaming. */
     caret?: boolean;
     /** Milliseconds between words as they reveal. A large chunk speeds up until the reveal is back within about 1.5s of the stream. */
     speed?: number;
     /** Pause the reveal while a mouse rests on the text, so people can read; it catches up on leave. */
     pauseOnHover?: boolean;
     /** Render text between backticks as inline code. */
     inlineCode?: boolean;
     /** Called once every word has revealed after streaming ends. */
     onRevealComplete?: () => void;
   };
   
   type Token = {
     /** The word, without the whitespace after it. */
     word: string;
     /** Whitespace after the word (may hold newlines). Rendered as plain text, never animated. */
     space: string;
     code: boolean;
   };
   
   type Reveal = {
     tokens: Token[];
     /** Tokens on screen. */
     released: number;
     /** Tokens that have finished animating and render as plain text. */
     settled: number;
     /** The tokens released in the last tick, spread across it. */
     batchFrom: number;
     batchSize: number;
     /** Words per tick while catching up. Held steady until the backlog is back inside the window. */
     rate: number;
   };
   
   /** A large chunk speeds the reveal up until it is back within this many milliseconds of words. */
   const MAX_LAG_MS = 1500;
   
   function tokenize(text: string, inlineCode: boolean): Token[] {
     const tokens: Token[] = [];
     const parts = inlineCode ? text.split("`") : [text];
     parts.forEach((part, index) => {
       if (!part) return;
       const code = inlineCode && index % 2 === 1;
       const lead = /^\s+/.exec(part);
       if (lead) tokens.push({ word: "", space: lead[0], code });
       for (const match of part.slice(lead ? lead[0].length : 0).matchAll(/(\S+)(\s*)/g)) {
         tokens.push({ word: match[1]!, space: match[2]!, code });
       }
     });
     return tokens;
   }
   
   /** How many leading tokens two token lists share (words and code only; trailing space may grow). */
   function sharedPrefix(a: Token[], b: Token[]) {
     const max = Math.min(a.length, b.length);
     let i = 0;
     while (i < max && a[i]!.word === b[i]!.word && a[i]!.code === b[i]!.code) i++;
     return i;
   }
   
   /** Settled tokens as a few plain runs: one text node per run, however long the text gets. */
   function runs(tokens: Token[]) {
     const out: { text: string; code: boolean }[] = [];
     for (const token of tokens) {
       const last = out[out.length - 1];
       if (last && last.code === token.code) last.text += token.word + token.space;
       else out.push({ text: token.word + token.space, code: token.code });
     }
     return out;
   }
   
   const codeClass = "rounded-control bg-surface-muted px-1 py-px font-mono";
   const codeStyle = { fontSize: "0.9em" };
   
   export const StreamingText = forwardRef<HTMLDivElement, StreamingTextProps>(function StreamingText(
     {
       text,
       streaming = false,
       caret = true,
       speed = 50,
       pauseOnHover = false,
       inlineCode = true,
       onRevealComplete,
       className,
       onPointerEnter,
       onPointerLeave,
       ...rest
     },
     ref,
   ) {
     const reduced = useReducedMotionAfterHydration();
     const tokens = useMemo(() => tokenize(text, inlineCode), [text, inlineCode]);
     const last = tokens[tokens.length - 1];
     // A word without whitespace after it may still be arriving ("Searc" then "hed"): hold it back.
     const available = streaming && last && last.space === "" ? tokens.length - 1 : tokens.length;
   
     const [state, setState] = useState<Reveal>(() => ({ tokens, released: 0, settled: 0, batchFrom: 0, batchSize: 0, rate: 1 }));
     const [paused, setPaused] = useState(false);
   
     // Append-only diff, during render: keep what still matches, rewind past anything that changed.
     let reveal = state;
     if (state.tokens !== tokens) {
       const keep = sharedPrefix(state.tokens, tokens);
       reveal = {
         tokens,
         released: Math.min(state.released, keep),
         settled: Math.min(state.settled, keep),
         batchFrom: state.batchFrom,
         batchSize: state.batchSize,
         rate: state.rate,
       };
       setState(reveal);
     }
   
     const released = reduced ? available : Math.min(reveal.released, tokens.length);
     const settled = reduced ? available : Math.min(reveal.settled, released);
     const hasBacklog = !reduced && reveal.released < available;
   
     const availableRef = useRef(available);
     const generation = useRef(0);
     useLayoutEffect(() => {
       availableRef.current = available;
     }, [available]);
     useLayoutEffect(() => {
       generation.current += 1;
     }, [tokens]);
   
     // The clock: one tick per `speed` ms while there is a backlog. New chunks never restart it.
     useEffect(() => {
       if (!hasBacklog || paused) return;
       const id = setTimeout(() => {
         setState((prev) => {
           const backlog = availableRef.current - prev.released;
           if (backlog <= 0) return prev;
           // Inside the window: one word per tick. Beyond it: a steady rate that drains the excess in about one window.
           const inWindow = Math.max(1, Math.floor(MAX_LAG_MS / speed));
           const rate = backlog <= inWindow ? 1 : Math.max(prev.rate, Math.ceil(backlog / inWindow));
           const size = Math.min(backlog, rate);
           return { ...prev, released: prev.released + size, batchFrom: prev.released, batchSize: size, rate };
         });
       }, speed);
       return () => clearTimeout(id);
     }, [hasBacklog, paused, reveal.released, speed]);
   
     // Words settle into plain text once their rise has finished, so the DOM stays a few nodes deep.
     const settleTimers = useRef(new Set<ReturnType<typeof setTimeout>>());
     useEffect(() => {
       if (reduced || reveal.released <= reveal.settled) return;
       const target = reveal.released;
       const gen = generation.current;
       const timers = settleTimers.current;
       const id = setTimeout(() => {
         timers.delete(id);
         if (gen !== generation.current) return;
         setState((prev) => ({ ...prev, settled: Math.max(prev.settled, Math.min(target, prev.released)) }));
       }, motionTokens.duration.fast * 1000 + speed);
       timers.add(id);
     }, [reduced, reveal.released, reveal.settled, speed]);
     useEffect(() => {
       const timers = settleTimers.current;
       return () => timers.forEach(clearTimeout);
     }, []);
   
     const complete = !streaming && released >= tokens.length;
     const completeRef = useRef(complete);
     useEffect(() => {
       if (complete && !completeRef.current) onRevealComplete?.();
       completeRef.current = complete;
     }, [complete, onRevealComplete]);
   
     const plain = useMemo(() => runs(tokens.slice(0, settled)), [tokens, settled]);
     const tail = tokens.slice(settled, released);
   
     const handleEnter = (event: PointerEvent<HTMLDivElement>) => {
       onPointerEnter?.(event);
       if (pauseOnHover && event.pointerType === "mouse") setPaused(true);
     };
     const handleLeave = (event: PointerEvent<HTMLDivElement>) => {
       onPointerLeave?.(event);
       setPaused(false);
     };
   
     const spread = reveal.batchSize > 1 ? speed / reveal.batchSize / 1000 : 0;
   
     return (
       <div
         ref={ref}
         data-status={complete ? "done" : "streaming"}
         data-paused={paused || undefined}
         aria-busy={!complete}
         className={cn("min-w-0 whitespace-pre-wrap break-words font-body text-16 text-pretty text-foreground", className)}
         onPointerEnter={handleEnter}
         onPointerLeave={handleLeave}
         {...rest}
       >
         {plain.map((run, index) =>
           run.code ? (
             <code key={index} className={codeClass} style={codeStyle}>
               {run.text}
             </code>
           ) : (
             <Fragment key={index}>{run.text}</Fragment>
           ),
         )}
         {tail.map((token, offset) => {
           const index = settled + offset;
           const inBatch = index - reveal.batchFrom;
           const delay = inBatch > 0 && inBatch < reveal.batchSize ? inBatch * spread : 0;
           return (
             <Fragment key={index}>
               {token.word ? (
                 <motion.span
                   data-slot="streaming-text-word"
                   className={cn("inline-block", token.code && codeClass)}
                   style={token.code ? codeStyle : undefined}
                   initial={{ opacity: 0, y: "0.3em", filter: `blur(${motionTokens.blur.soft}px)` }}
                   animate={{ opacity: 1, y: 0, filter: "blur(0px)" }}
                   transition={{ duration: motionTokens.duration.fast, ease: motionTokens.ease.enter, delay }}
                 >
                   {token.word}
                 </motion.span>
               ) : null}
               {token.space}
             </Fragment>
           );
         })}
         <AnimatePresence initial={false}>
           {caret && !complete ? (
             <motion.span
               key="caret"
               aria-hidden="true"
               data-slot="streaming-text-caret"
               className="ms-0.5 inline-block h-[1.1em] w-0.5 translate-y-[0.2em] rounded-pill bg-foreground/70"
               initial={{ opacity: 0 }}
               animate={{ opacity: 1 }}
               exit={{ opacity: 0 }}
               transition={reduced ? reducedTransition : { duration: motionTokens.duration.quick, ease: motionTokens.ease.swap }}
             />
           ) : null}
         </AnimatePresence>
       </div>
     );
   });

4. 4

   Check that your global stylesheet imports the foundation, after Tailwind.

   app/globals.cssCopy

   @import "tailwindcss";
   @import "../components/pixilui/foundation.css";