Thinking UI

Streaming Text

Tokens fade in from a soft blur as an LLM response streams in.

Code

components/thinking-ui/streaming-text.tsx
"use client";

import { motion } from "motion/react";
import { Fragment, useEffect, useMemo, useState } from "react";
import { useMotion } from "@/lib/motion";
import { cn } from "@/lib/utils";

type Granularity = "word" | "char";

function tokenize(text: string, by: Granularity) {
  return by === "word" ? text.split(/(\s+)/).filter(Boolean) : Array.from(text);
}

export type StreamingTextProps = {
  /** The text received so far. New tokens animate in as it grows. */
  text: string;
  /** Show a blinking caret while more text is expected. */
  streaming?: boolean;
  /** Animate each word or each character. */
  by?: Granularity;
  className?: string;
};

export function StreamingText({ text, streaming = false, by = "word", className }: StreamingTextProps) {
  const m = useMotion();
  const tokens = useMemo(() => tokenize(text, by), [text, by]);

  return (
    <span className={cn("whitespace-pre-wrap", className)}>
      {tokens.map((token, i) =>
        /^\s+$/.test(token) ? (
          <Fragment key={i}>{token}</Fragment>
        ) : (
          <motion.span
            key={i}
            initial={m.reduce ? false : { opacity: 0, filter: m.blur(Math.max(m.personality.blur, 4)) }}
            animate={{ opacity: 1, filter: m.blur(0) }}
            transition={m.tween("slower")}
          >
            {token}
          </motion.span>
        ),
      )}
      {streaming && (
        <motion.span
          aria-hidden
          className="ml-0.5 inline-block h-[1.05em] w-0.5 translate-y-[0.18em] rounded-full bg-current"
          animate={{ opacity: [1, 0.15] }}
          transition={{ duration: 0.5 * m.scale, repeat: Infinity, repeatType: "reverse" }}
        />
      )}
    </span>
  );
}

/** Simulates a token stream from a full string — useful for demos and tests. */
export function useSimulatedStream(
  fullText: string,
  { interval = 40, by = "word", enabled = true }: { interval?: number; by?: Granularity; enabled?: boolean } = {},
) {
  const m = useMotion();
  const tokens = useMemo(() => tokenize(fullText, by), [fullText, by]);
  const [count, setCount] = useState(0);
  const visible = m.reduce && enabled ? tokens.length : count;
  const { ms, reduce } = m;

  useEffect(() => {
    if (!enabled || reduce || count >= tokens.length) return;
    const id = setTimeout(() => setCount((c) => c + 1), ms(interval));
    return () => clearTimeout(id);
  }, [enabled, reduce, count, tokens.length, interval, ms]);

  return { text: tokens.slice(0, visible).join(""), done: visible >= tokens.length };
}

Motion notes

  • Each token animates once, when it first appears. Text already on screen never moves.
  • Blur plus opacity, with no vertical motion, so lines don't jitter while you read.
  • 350ms ease-out per token: long enough to feel soft, short enough not to trail behind the stream.
  • With reduced motion, text appears instantly and the caret stops blinking smoothly.

Installation

  1. 1

    Install dependencies

    Terminal
    npm install motion clsx tailwind-merge
  2. 2

    Add the design tokens and motion system (once per project)

    Copy styles/tokens/*, lib/motion.tsx and lib/utils.ts from Get started.

  3. 3

    Paste the source into components/thinking-ui/streaming-text.tsx

    Copy it from the Code tab, or use Copy prompt to let your coding agent do all of this.

Usage

Example
const { text, done } = useSimulatedStream(answer);

<StreamingText text={text} streaming={!done} />

Props

PropTypeDefaultDescription
textstring—The text received so far. Pass the growing string from your stream.
streamingbooleanfalseShows a blinking caret while more text is expected.
by"word" | "char""word"Animate per word or per character.
classNamestring—Classes for the wrapping span.