{"slug":"stream-of-thought","category":"traces","job":"oversee","added":"2026-11-07T22:34Z","title":"Stream of Thought","description":"A live, timed header over reasoning that streams in as a step timeline, then folds into a \"Thought for Ns\" trace when the answer starts.","url":"https://ai-patterns.app/patterns/traces/stream-of-thought","markdown":"https://ai-patterns.app/patterns/traces/stream-of-thought.md","json":"https://ai-patterns.app/api/patterns/traces/stream-of-thought","seenIn":[{"team":"chatgpt","source":"https://help.openai.com/en/articles/11909943-gpt-5-5-in-chatgpt"},{"team":"lovable","source":"https://docs.lovable.dev/features/agent-mode"},{"team":"Perplexity","source":"https://www.perplexity.ai/help-center/en/articles/10352903-what-is-pro-search"}],"spec":"# Stream of Thought\n\n## Summary\nThe model's reasoning streams inline as a timeline of short steps, each a headline and a few lines of prose, under a live header. The header shows the title of the current step sliding into place and a ticking timer, like Thinking Loader. When the answer starts, the timeline collapses into a \"Thought for Ns\" toggle that expands into the full trace, like Expandable Trace. One component covers the wait, the live reasoning and the record afterwards.\n\n## When to use\n- Reasoning models that think for several seconds or more before answering. Watching the thoughts arrive makes the wait feel shorter and shows that work is happening.\n- When the reasoning arrives live as prose (or a live summary of it) that falls into a few named beats.\n- When people may want to check how the model reached its conclusion, but most only want the answer.\n\n## When not to use\n- When there is nothing real to stream. Don't invent placeholder thoughts to fill a wait; use Thinking Loader.\n- When the steps are discrete tool actions with results (search, read, edit) and no prose. Expandable Trace or Task List say that more plainly.\n- When the raw reasoning may contain content you can't show users (policy text, system prompt details). Stream a summary, or don't show it at all.\n\n## Anatomy\n- **Header toggle:** an icon, a label and a chevron; the whole row is the toggle.\n - While thinking: a brain icon, the current step's title shimmering and sliding in from below, and an elapsed-seconds counter on the right whose digits roll as they change.\n - When done: a sparkle icon and \"Thought for Ns\". The counter is gone.\n- **Timeline:** one step per thought, joined by a thin vertical line. Each step has a mark, a short headline and muted body text.\n- **Step mark:** a pulsing dot on the step that is still streaming; a check on finished steps.\n- **Live window:** while thinking, the timeline is capped to a few lines, with a fade at the top edge so older steps dissolve upward instead of being cut off.\n- **The answer:** below and outside the component, in full-contrast text.\n\n## Behavior\n- Open by default while thinking. New text appends at the bottom and the window stays scrolled to the newest line. If the person scrolls up inside it, stop auto-scrolling until they return to the bottom.\n- When a new step starts, its title replaces the header label, and the previous step's dot turns into a check.\n- The timer counts whole seconds from when thinking started. It freezes when thinking ends, and that number becomes \"Thought for Ns\". Pass the server's duration instead when you have it.\n- When thinking ends, the last dot turns into a check and the timeline collapses with a short height animation. The answer then fades in below.\n- After completion, the expanded timeline shows every step in full, with no height cap and no fade.\n- If the person toggles the header at any point, keep their choice. Don't auto-collapse something they just opened, or reopen something they closed.\n- Text appears in small chunks (words or tokens), following the model's rhythm, not letter by letter at a fixed speed.\n- With reduced motion, drop the shimmer and the height animation; the text still streams and the labels still change.\n\n## Content guidelines\n- Step titles are short gerund phrases (\"Weighing the options\"), at most about five words. They double as the live header label, so they must fit on one line.\n- Body text can be first person and informal. It's thinking, not the answer, and should read that way.\n- Use the real elapsed time (\"Thought for 9s\"). Round to whole seconds, and switch to minutes past 60s (\"Thought for 2m\").\n- The answer must not depend on the reasoning: it repeats any conclusion it needs, so nobody has to expand the trace to understand it.\n\n## Accessibility\n- The header is a real `button` with `aria-expanded` and `aria-controls` pointing at the timeline.\n- Announce state through a visually hidden `role=\"status\"` (\"Thinking\", then \"Thought for N seconds\"). Hide the sliding label and the ticking timer from assistive tech, and don't make the streaming body a live region: announcing every token or second is unusable.\n- Mark the timeline `aria-busy=\"true\"` while it streams, and make the live window focusable so keyboard users can scroll it.\n- Use an ordered list for the steps. Shimmer and pulse are decorative; labels must read at sufficient contrast without them.\n\n## Related patterns\n- **Thinking Loader** — Use it instead when there is no reasoning text to show, just the live header.\n- **Expandable Trace** — Use it instead when the reasoning is already complete and doesn't need to stream.\n- **Streaming Text** — Use it as well below for the answer itself as it streams in.\n","code":"\"use client\";\n\nimport * as React from \"react\";\nimport { AnimatePresence, motion, useReducedMotion } from \"motion/react\";\nimport { Brain, Check, ChevronDown, Sparkles } from \"lucide-react\";\n\nimport { cn } from \"@/lib/utils\";\n\nexport interface Thought {\n /** A short headline for this beat of reasoning, e.g. \"Comparing the two options\". */\n title: string;\n /** The reasoning text itself. Pass the partial string while it streams. */\n body: string;\n}\n\nexport interface StreamOfThoughtProps {\n /** Thoughts streamed so far. The last one is still growing while `thinking` is true. */\n thoughts: Thought[];\n /** True while the model is still reasoning. */\n thinking: boolean;\n /** Overrides the measured duration shown once thinking finishes (\"Thought for 12s\"). */\n durationSeconds?: number;\n /** Max height of the live window while streaming, in px. */\n liveHeight?: number;\n className?: string;\n}\n\nexport function StreamOfThought({\n thoughts,\n thinking,\n durationSeconds,\n liveHeight = 148,\n className,\n}: StreamOfThoughtProps) {\n const reduceMotion = useReducedMotion();\n const bodyId = React.useId();\n const elapsed = useElapsedSeconds(thinking);\n const seconds = durationSeconds ?? elapsed;\n\n // `null` = follow the default (open while thinking, closed when done).\n // Once the person toggles, their choice wins.\n const [userOpen, setUserOpen] = React.useState(null);\n const open = userOpen ?? thinking;\n\n const scrollRef = React.useRef(null);\n const pinned = React.useRef(true);\n\n // Keep the live window scrolled to the newest line, unless the person\n // scrolled up to re-read something.\n React.useLayoutEffect(() => {\n const el = scrollRef.current;\n if (!el || !thinking || !pinned.current) return;\n el.scrollTop = el.scrollHeight;\n }, [thoughts, thinking, open]);\n\n function onScroll() {\n const el = scrollRef.current;\n if (!el) return;\n pinned.current = el.scrollHeight - el.scrollTop - el.clientHeight < 8;\n }\n\n const current = thoughts.at(-1)?.title ?? \"Thinking\";\n\n return (\n
\n setUserOpen(!open)}\n aria-expanded={open}\n aria-controls={bodyId}\n className=\"flex w-full items-center gap-2 rounded-md py-1 text-left text-xs font-medium text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring\"\n >\n {thinking ? (\n \n ) : (\n \n )}\n {/* Announces \"Thinking\" once, then \"Thought for Ns\" — never the stream itself. */}\n \n {thinking ? \"Thinking\" : `Thought for ${seconds} seconds`}\n \n \n {thinking ? (\n \n ) : (\n Thought for {seconds}s\n )}\n \n \n {thinking && (\n \n s\n \n )}\n \n \n \n\n \n {open && (\n \n \n
    \n {thoughts.map((thought, i) => {\n const last = i === thoughts.length - 1;\n const live = thinking && last;\n return (\n \n
    \n \n {!last && }\n
    \n
    \n

    {thought.title}

    \n

    \n {thought.body}\n

    \n
    \n \n );\n })}\n
\n
\n \n )}\n \n \n );\n}\n\n/** A pulsing dot while the step streams; a check once it's done. */\nfunction StepMark({ live }: { live: boolean }) {\n return (\n \n \n {live ? (\n \n ) : (\n \n \n \n )}\n \n \n );\n}\n\n/** Counts whole seconds while `running`, and freezes when it stops. */\nfunction useElapsedSeconds(running: boolean) {\n const [elapsed, setElapsed] = React.useState(0);\n\n React.useEffect(() => {\n if (!running) return;\n const start = Date.now();\n const id = window.setInterval(() => {\n setElapsed(Math.floor((Date.now() - start) / 1000));\n }, 250);\n return () => window.clearInterval(id);\n }, [running]);\n\n return elapsed;\n}\n\n/** The current thought's title slides in from below and shimmers. */\nfunction SlidingLabel({ label, shimmer }: { label: string; shimmer: boolean }) {\n return (\n \n \n \n {label}\n \n \n \n );\n}\n\n/** Each digit slides up and out when it changes. */\nfunction SlidingNumber({ value }: { value: string }) {\n return (\n \n {value.split(\"\").map((char, i) => (\n \n \n \n {char}\n \n \n \n ))}\n \n );\n}\n","dependencies":["lucide-react","motion"],"localImports":["@/lib/utils"]}