For the complete documentation index, see llms.txt. Markdown variants are available by appending .md to any URL or sending an Accept: text/markdown header. An agent skill is available at /.well-known/agent-skills/site-skill.md.
FrakmentFrakment

Reasoning

Show an agent thinking block as a collapsible trace with streaming status.

Why is the checkout deploy so slow?
The deploy log has three phases. Install takes 38s and next build takes 52s, both normal for this repo. Image optimization takes 3m 50s. It reruns on every deploy because its cache key includes the commit hash, so the cache never hits.

Image optimization is the bottleneck. Key its cache on the lockfile and the image directory instead of the commit hash, and the deploy should take under two minutes.

reasoning-demo.tsx
"use client";

import { useChat } from "@ai-sdk/react";
import * as React from "react";
import { Button } from "@/components/ui/button";
import {
  Bubble,
  BubbleContent,
  Message,
  MessageContent,
} from "@/components/ui/message";
import {
  Trace,
  TraceCollapsible,
  TraceCollapsibleContent,
  TraceCollapsibleTrigger,
  TraceLine,
  TraceTitle,
} from "@/components/ui/trace";
import { createChat, getMessageText } from "@/lib/ai";

const chat = createChat()
  .user("Why is the checkout deploy so slow?")
  .assistant(({ writer }) => {
    writer.reasoning(
      "The deploy log has three phases. Install takes 38s and next build takes 52s, both normal for this repo.\n\nImage optimization takes 3m 50s. It reruns on every deploy because its cache key includes the commit hash, so the cache never hits.",
      { delayMs: 40 }
    );
    writer.sleep(400);
    writer.text(
      "Image optimization is the bottleneck. Key its cache on the lockfile and the image directory instead of the commit hash, and the deploy should take under two minutes."
    );
  });

const transcript = chat.get();
const [question] = chat.get(1);
const transport = chat.transport({ delayMs: 20 });

function ReasoningRow({
  text,
  running,
  defaultOpen,
}: {
  text: string;
  running: boolean;
  defaultOpen?: boolean;
}) {
  const [open, setOpen] = React.useState<boolean | undefined>(defaultOpen);

  const line = (
    <TraceLine status={running ? "running" : undefined}>
      <TraceTitle>{running ? "Thinking" : "Thought for 5s"}</TraceTitle>
    </TraceLine>
  );

  if (text.length === 0) {
    return line;
  }

  return (
    <TraceCollapsible onOpenChange={setOpen} open={open ?? running}>
      <TraceCollapsibleTrigger>{line}</TraceCollapsibleTrigger>
      <TraceCollapsibleContent className="text-muted-foreground whitespace-pre-wrap">
        {text}
      </TraceCollapsibleContent>
    </TraceCollapsible>
  );
}

export function ReasoningDemo() {
  const { messages, sendMessage, setMessages, status } = useChat({
    messages: transcript,
    transport,
  });
  const busy = status === "submitted" || status === "streaming";

  return (
    <div className="flex min-h-72 w-full max-w-sm flex-col gap-4 py-6 text-sm">
      {messages.map((message) => {
        if (message.role === "user") {
          return (
            <Message align="end" key={message.id}>
              <MessageContent>
                <Bubble align="end" variant="muted">
                  <BubbleContent>{getMessageText(message)}</BubbleContent>
                </Bubble>
              </MessageContent>
            </Message>
          );
        }

        const streaming = busy && message === messages.at(-1);
        const reasoning = message.parts.filter(
          (part) => part.type === "reasoning"
        );
        const text = getMessageText(message);

        return (
          <Message key={message.id}>
            <MessageContent className="gap-4">
              {reasoning.length > 0 && (
                <Trace>
                  {reasoning.map((part, index) => (
                    <ReasoningRow
                      defaultOpen={busy ? undefined : true}
                      key={index}
                      running={streaming && part.state === "streaming"}
                      text={part.text}
                    />
                  ))}
                </Trace>
              )}
              {text && <p>{text}</p>}
            </MessageContent>
          </Message>
        );
      })}
      {!busy && question && (
        <Button
          className="mt-auto self-start"
          onClick={() => {
            if (!question) {
              return;
            }
            setMessages([]);
            sendMessage(question);
          }}
          size="sm"
          variant="outline"
        >
          Replay
        </Button>
      )}
    </div>
  );
}

Reasoning renders an agent thinking block as a collapsible trace line. While streaming, the line shimmers and stays open. Once done, it collapses to a single row and the body can be expanded on demand.

Reasoning is a composition, not a primitive. It composes Trace and drives its streaming state through a chat transport.

Installation

Usage

reasoning.tsx
import {
  Trace,
  TraceCollapsible,
  TraceCollapsibleContent,
  TraceCollapsibleTrigger,
  TraceLine,
  TraceTitle,
} from "@/components/ui/trace";
reasoning.tsx
<Trace>
  <TraceCollapsible open={running} onOpenChange={setOpen}>
    <TraceCollapsibleTrigger>
      <TraceLine status={running ? "running" : undefined}>
        <TraceTitle>{running ? "Thinking" : "Thought for 5s"}</TraceTitle>
      </TraceLine>
    </TraceCollapsibleTrigger>
    <TraceCollapsibleContent className="whitespace-pre-wrap">
      {text}
    </TraceCollapsibleContent>
  </TraceCollapsible>
</Trace>

Anatomy

reasoning.tsx
<Trace>
  <TraceCollapsible>
    <TraceCollapsibleTrigger>
      <TraceLine>
        <TraceIcon />
        <TraceTitle />
        <TraceDescription />
      </TraceLine>
    </TraceCollapsibleTrigger>
    <TraceCollapsibleContent />
  </TraceCollapsible>
</Trace>
  • Trace — wrapper for one or more reasoning runs
  • TraceCollapsible — the thinking block, controlled via open
  • TraceCollapsibleTrigger — the header row, one line
  • TraceLine — accepts status so the running row shimmers
  • TraceTitle — "Thinking" while running, "Thought" once done
  • TraceDescription — optional duration on the right
  • TraceCollapsibleContent — the reasoning body, plain text in text-muted-foreground

Streaming

While the model streams reasoning, the part carries state === "streaming". Pass that to TraceLine as status="running" so the title shimmers, and keep the collapsible open until the run finishes.

With duration

Add a TraceDescription after the title to show how long the model thought. Pair with a CircleCheckIcon to signal the run is complete.

The build log shows install and compile finish in under a minute. Image optimization takes almost four, and it reruns on every deploy because the cache key includes the commit hash.
reasoning-duration.tsx
import { CircleCheckIcon } from "lucide-react";

import {
  Trace,
  TraceCollapsible,
  TraceCollapsibleContent,
  TraceCollapsibleTrigger,
  TraceDescription,
  TraceIcon,
  TraceLine,
  TraceTitle,
} from "@/components/ui/trace";

export function ReasoningDuration() {
  return (
    <Trace className="max-w-sm">
      <TraceCollapsible>
        <TraceCollapsibleTrigger>
          <TraceLine>
            <TraceIcon>
              <CircleCheckIcon />
            </TraceIcon>
            <TraceTitle>Thought</TraceTitle>
            <TraceDescription>12s</TraceDescription>
          </TraceLine>
        </TraceCollapsibleTrigger>
        <TraceCollapsibleContent className="text-muted-foreground whitespace-pre-wrap">
          {
            "The build log shows install and compile finish in under a minute.\n\nImage optimization takes almost four, and it reruns on every deploy because the cache key includes the commit hash."
          }
        </TraceCollapsibleContent>
      </TraceCollapsible>
    </Trace>
  );
}

Controlled open

The demo keeps the block open while streaming and collapses once done. Pass open and onOpenChange when the parent wants to control visibility, or use defaultOpen for an uncontrolled block that starts expanded.

Accessibility

  • The reasoning body is plain text. Write it as a paragraph, not a bullet list.
  • Status is conveyed by shimmer and header text. Do not rely on color alone.
  • The collapsible trigger is keyboard-focusable and toggles with Enter or Space.
  • prefers-reduced-motion disables shimmer and collapse animation.

Best Practices

  • Keep reasoning collapsed by default. Users scan the answer, not the path.
  • Open while streaming. A live thinking block signals progress. Collapse it when the text arrives.
  • Do not edit reasoning. Render the raw text. Summaries belong in the message body.
  • One Trace per turn. Group multiple reasoning parts inside a single Trace so the spacing stays even.