Reasoning

npx shadcn@latest add "@assistant-ui/reasoning"

npx assistant-ui@latest init

import { AssistantRuntimeProvider } from "@assistant-ui/react";
import { useChatRuntime, AssistantChatTransport } from "@assistant-ui/ai-sdk";

export default function App() {
  const runtime = useChatRuntime({
    transport: new AssistantChatTransport({ api: "/api/chat" }),
  });

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      {/* your components */}
    </AssistantRuntimeProvider>
  );
}

npx shadcn@latest add "@assistant-ui/elements-reasoning"

Reasoning gives a model's chain of thought its own track: a shimmering trigger while it streams, a scrollable trace once opened, and a plain collapsed row once the model moves on. With a runtime it follows the active reasoning message part; standalone you drive the same disclosure from props you own. It comes in two designs: the runtime variant renders one continuous markdown trace, and the static variant, ReasoningPanel, renders discrete titled steps along a timeline (see The step-panel design).

Getting started

import { MessagePrimitive, groupPartByType } from "@assistant-ui/react";
import {
  ReasoningContent,
  ReasoningRoot,
  ReasoningText,
  ReasoningTrigger,
} from "@/components/assistant-ui/elements/reasoning.aui";

<MessagePrimitive.GroupedParts
  groupBy={groupPartByType({ reasoning: ["group-reasoning"] })}
>
  {({ part, children }) => {
    if (part.type !== "group-reasoning") return null;
    const running = part.status.type === "running";
    return (
      <ReasoningRoot streaming={running}>
        <ReasoningTrigger active={running} />
        <ReasoningContent aria-busy={running}>
          <ReasoningText>{children}</ReasoningText>
        </ReasoningContent>
      </ReasoningRoot>
    );
  }}
</MessagePrimitive.GroupedParts>

case "reasoning":
  return <Reasoning {...part} />;

"use client";

import {
  ReasoningContent,
  ReasoningRoot,
  ReasoningText,
  ReasoningTrigger,
} from "@/components/assistant-ui/elements/reasoning";

export function Trace({
  text,
  streaming,
}: {
  text: string;
  streaming: boolean;
}) {
  return (
    <ReasoningRoot streaming={streaming}>
      <ReasoningTrigger active={streaming} />
      <ReasoningContent aria-busy={streaming}>
        <ReasoningText>{text}</ReasoningText>
      </ReasoningContent>
    </ReasoningRoot>
  );
}

const [open, setOpen] = useState(false);

<ReasoningRoot open={open} onOpenChange={setOpen} streaming={streaming}>
  {/* ... */}
</ReasoningRoot>;

Anatomy

<div data-slot="reasoning-root" data-variant="outline">
  <button data-slot="reasoning-trigger">
    <BrainIcon />
    <span>{/* "Reasoning" or "Reasoning (12s)" */}</span>
    <ChevronDownIcon />
  </button>
  <div data-slot="reasoning-content">
    <div data-slot="reasoning-fade" /> {/* top edge, always */}
    <div data-slot="reasoning-text">{/* the trace */}</div>
    <div data-slot="reasoning-fade" /> {/* bottom edge, streaming only */}
  </div>
</div>

While streaming is true and the panel is open, the trace is a live, bottom-pinned preview: it autoscrolls to the newest tokens as they arrive and only stops if the reader scrolls up manually, resuming once they scroll back to the bottom. When streaming ends, the open state returns to defaultOpen, unless the reader has already toggled the disclosure by hand at least once, at which point their choice sticks and streaming no longer overrides it. ReasoningTrigger's active prop drives both the shimmering label and the timing text; the chevron rotates on open regardless. The runtime ReasoningRoot additionally locks the surrounding thread viewport's scroll position for the duration of each open or close animation, so expanding a trace never yanks the message list; the standalone root has no viewport to lock, so it skips that.

Examples

Variants

ReasoningRoot takes a variant: outline draws a border and padding (the default), ghost adds neither, and muted fills a soft background instead of a border.

<ReasoningRoot variant="muted" streaming={streaming}>
  {/* ... */}
</ReasoningRoot>

Trigger duration

Pass duration (seconds) to append a timing suffix to the trigger label:

<ReasoningTrigger active={streaming} duration={12} />
// renders: Reasoning (12s)

Where reasoning parts come from

const running = part.status.type === "running";
<ReasoningTrigger active={running} duration={running ? undefined : elapsedSeconds} />

API reference

The step-panel design

The Static variant in the rail is a second design for the same disclosure: ReasoningPanel renders an ordered list of titled steps with a shimmering "Thinking" trigger that settles into a resting summary, instead of one continuous markdown trace. It is a single props-driven component with no runtime dependency:

npx shadcn@latest add "@assistant-ui/elements-reasoning-panel"

"use client";

import { useMemo, useState } from "react";
import { useAuiState, useMessageTiming } from "@assistant-ui/react";
import {
  ReasoningPanel,
  type ReasoningStep,
} from "@/components/assistant-ui/elements/reasoning-panel";

function AssistantReasoning() {
  const parts = useAuiState((s) => s.message.parts);
  const steps = useMemo<ReasoningStep[]>(
    () =>
      parts.flatMap((part) =>
        part.type === "reasoning"
          ? [{ title: part.unstable_summary ?? "Thinking", body: part.text }]
          : [],
      ),
    [parts],
  );
  const streaming = useAuiState((s) => {
    if (s.message.status?.type !== "running") return false;
    return s.message.parts.some(
      (part) => part.type === "reasoning" && part.status.type === "running",
    );
  });
  const timing = useMessageTiming();
  const [userOpen, setUserOpen] = useState<boolean | null>(null);

  if (steps.length === 0) return null;

  return (
    <ReasoningPanel
      steps={steps}
      visibleSteps={steps.length}
      streaming={streaming}
      open={userOpen ?? streaming}
      onOpenChange={setUserOpen}
      restingLabel={
        timing?.totalStreamTime
          ? `Thought for ${Math.round(timing.totalStreamTime / 1000)}s`
          : "Done thinking"
      }
    />
  );
}

"use client";

import { useState } from "react";
import {
  ReasoningPanel,
  type ReasoningStep,
} from "@/components/assistant-ui/elements/reasoning-panel";

const STEPS: ReasoningStep[] = [
  { title: "Reading the request", body: "Working out what changed and why." },
  { title: "Locating the seam", body: "Finding where the fix actually belongs." },
];

export function Trace() {
  const [open, setOpen] = useState(true);
  return (
    <ReasoningPanel
      steps={STEPS}
      visibleSteps={STEPS.length}
      streaming={false}
      open={open}
      onOpenChange={setOpen}
      restingLabel="Thought for 4s"
    />
  );
}

The trigger swaps between the shimmering live label (plus the elapsed badge, when given) and restingLabel, animating its own width rather than jumping. visibleSteps clamps between 0 and steps.length; while streaming is true only the last shown step gets the pulsing marker.

ReasoningPanel