Skip to content
Shaken UI
Sign in

Reasoning

Save

The agent's thinking as it streams, in a quiet collapsible block that reads Thinking with the live mark, then the time it took, and folds itself away when done.

Category
AI elements
Version
0.1.0
Frameworks
Next.js, Vite + React
Styling
Tailwind CSS v4

Preview

Reasoning preview
Thinking

Opens while streaming, folds away 1.2 s after it ends.

Installation

npx @shakenui/cli add reasoning

Review the plan first. A dry run lists every file and package without changing anything:

npx @shakenui/cli add reasoning --dry-run

Usage

reasoning-example.tsx
import { Reasoning } from "@/components/shaken/agent/reasoning";

export default function ReasoningExample() {
  return (
    <div className="grid w-full max-w-lg gap-3">
      <Reasoning duration={6} defaultOpen>
        {
          "The user wants to know why the nightly export job failed. The log shows the job started at 02:00 and stopped after 41 seconds with a 403 from the storage bucket.\n\nA 403 rather than a 404 means the bucket exists but the service account cannot write to it. The credentials were rotated yesterday, so the new key probably lacks the storage writer role."
        }
      </Reasoning>
      <p className="text-sm leading-relaxed text-zinc-950 dark:text-white">
        The export failed because the rotated service account key cannot write to the bucket. Grant it the storage writer role, then rerun the job.
      </p>
    </div>
  );
}

API

PropTypeDefaultDescription
childrenReactNode—The reasoning text or any content. Plain strings keep their line breaks.
streamingbooleanfalseTrue while reasoning arrives. The trigger reads "Thinking…" with the animated thinking mark; afterwards the mark holds still.
durationnumber—Seconds spent thinking, shown as "Thought for 6 s". Measured from streaming on to off when omitted.
autoCollapseboolean | numbertrueCloses the block after streaming ends: true waits 1000ms, a number sets the delay, false keeps it open. Skipped if the reader toggled it during the stream.
open / defaultOpen / onOpenChangeboolean / boolean / (open) => void—Controlled or uncontrolled open state. defaultOpen falls back to streaming, so a live block starts open.
labelReactNode—Replaces the trigger text.
formatThinkingTime(seconds) => string—The trigger's wording on its own: "Thought for 6 s", "Thought for 1 min 12 s", "Thought for a moment".

Accessibility

  • Built on Base UI Collapsible: the trigger is a button with aria-expanded and aria-controls, operable with Enter and Space.
  • A polite status region announces "Thinking" and then "Thought for 6 seconds"; the streamed text itself is not announced word by word.
  • The panel is aria-busy while streaming. The mark is decorative.
  • With reduced motion the mark renders a still frame and the panel opens and closes without a height animation.

Files

Installed into src/components/shaken, or components/shaken when the project has no src directory.

  • src/components/shaken/agent/reasoning.tsxreasoning
  • Also installs agent-state@0.1.0registry dependency
  • npm packages: @base-ui/react@^1.9.0React and Tailwind CSS v4 required

Source

The exact source the CLI installs, from /r/items/react/reasoning/0.1.0.json.

agent/reasoning.tsxShow
agent/reasoning.tsx
"use client";

import { Collapsible } from "@base-ui/react/collapsible";
import { type ReactNode, useEffect, useRef, useState } from "react";
import { AgentMark } from "./agent-state";

function cx(...classes: Array<string | false | null | undefined>) {
  return classes.filter(Boolean).join(" ");
}

const ease = "ease-[cubic-bezier(0.23,1,0.32,1)]";

/**
 * "Thought for 6 s", "Thought for 1 min 12 s", or "Thought for a moment" under a second.
 * Exported so a message footer or a trace can use the same wording.
 */
export function formatThinkingTime(seconds: number): string {
  if (!Number.isFinite(seconds) || seconds < 1) return "Thought for a moment";
  const total = Math.round(seconds);
  if (total < 60) return `Thought for ${total} s`;
  const minutes = Math.floor(total / 60);
  const rest = total % 60;
  return rest ? `Thought for ${minutes} min ${rest} s` : `Thought for ${minutes} min`;
}

/** The same duration spelled out for screen readers ("6 seconds" rather than "6 s"). */
function spokenTime(seconds: number): string {
  if (!Number.isFinite(seconds) || seconds < 1) return "Thought for a moment";
  const total = Math.round(seconds);
  const minutes = Math.floor(total / 60);
  const rest = total % 60;
  const parts = [
    minutes ? `${minutes} ${minutes === 1 ? "minute" : "minutes"}` : "",
    rest ? `${rest} ${rest === 1 ? "second" : "seconds"}` : "",
  ].filter(Boolean);
  return `Thought for ${parts.join(" ")}`;
}

export interface ReasoningProps {
  /** The reasoning text, or any content. Plain strings keep their line breaks. */
  children?: ReactNode;
  /** True while reasoning tokens are arriving. The trigger reads "Thinking…" with the live mark. */
  streaming?: boolean;
  /**
   * Seconds spent thinking, shown once streaming ends. When omitted, the block measures the
   * time between `streaming` turning on and off itself.
   */
  duration?: number;
  /**
   * Closes the block after streaming ends. `true` waits 1000ms, a number sets the delay in ms,
   * `false` leaves it open. Skipped when the reader opened or closed the block during the stream.
   * @default true
   */
  autoCollapse?: boolean | number;
  /** Controlled open state. Pair with `onOpenChange`. */
  open?: boolean;
  /** Initial open state when uncontrolled. Defaults to `streaming`, so a live block starts open. */
  defaultOpen?: boolean;
  /** Called with the next open state, from the trigger or from auto open and collapse. */
  onOpenChange?: (open: boolean) => void;
  /** Replaces the trigger text, for example "Reasoning hidden by policy". */
  label?: ReactNode;
  /** Classes for the outer element. */
  className?: string;
  /** Classes for the content wrapper inside the panel. */
  contentClassName?: string;
}

/**
 * The agent's thinking as it streams: a quiet disclosure that reads "Thinking…" next to the
 * animated thinking mark, then "Thought for 6 s" with the mark held still. It opens while the
 * stream runs and folds itself away shortly after, unless the reader took control of it.
 */
export function Reasoning({
  children,
  streaming = false,
  duration,
  autoCollapse = true,
  open: openProp,
  defaultOpen,
  onOpenChange,
  label,
  className,
  contentClassName,
}: ReasoningProps) {
  const [uncontrolledOpen, setUncontrolledOpen] = useState(defaultOpen ?? streaming);
  const controlled = openProp !== undefined;
  const open = controlled ? openProp : uncontrolledOpen;

  const [measured, setMeasured] = useState<number | undefined>(undefined);
  const startedAt = useRef<number | null>(streaming ? performance.now() : null);
  const touched = useRef(false);
  const wasStreaming = useRef(streaming);

  // Keep the latest handlers in refs so the streaming effect only depends on `streaming`.
  const setOpenRef = useRef<(next: boolean) => void>(() => {});
  setOpenRef.current = (next: boolean) => {
    if (!controlled) setUncontrolledOpen(next);
    onOpenChange?.(next);
  };
  const delay = autoCollapse === false ? null : autoCollapse === true ? 1000 : Math.max(0, autoCollapse);
  const delayRef = useRef(delay);
  delayRef.current = delay;

  // Bumped when a stream ends; the timer lives in its own effect so it survives Strict Mode.
  const [collapseRequest, setCollapseRequest] = useState(0);

  useEffect(() => {
    if (streaming === wasStreaming.current) return;
    wasStreaming.current = streaming;
    if (streaming) {
      startedAt.current = performance.now();
      touched.current = false;
      setMeasured(undefined);
      setOpenRef.current(true);
      return;
    }
    if (startedAt.current != null) setMeasured((performance.now() - startedAt.current) / 1000);
    startedAt.current = null;
    if (!touched.current) setCollapseRequest((count) => count + 1);
  }, [streaming]);

  useEffect(() => {
    if (!collapseRequest || delayRef.current == null) return;
    const timer = setTimeout(() => {
      if (!touched.current && !wasStreaming.current) setOpenRef.current(false);
    }, delayRef.current);
    return () => clearTimeout(timer);
  }, [collapseRequest]);

  const seconds = duration ?? measured;
  const text = label ?? (streaming ? "Thinking" : seconds != null ? formatThinkingTime(seconds) : "Reasoning");
  const announcement = streaming ? "Thinking" : seconds != null ? spokenTime(seconds) : "";

  return (
    <Collapsible.Root
      open={open}
      onOpenChange={(next) => {
        touched.current = true;
        setOpenRef.current(next);
      }}
      data-streaming={streaming || undefined}
      className={cx("w-full min-w-0", className)}
    >
      <Collapsible.Trigger
        className={cx(
          "group -mx-1.5 inline-flex h-7 max-w-[calc(100%+0.75rem)] cursor-pointer items-center gap-2 rounded-md px-1.5 text-sm select-none",
          "text-zinc-600 transition-[background-color,color] duration-150 ease-out motion-reduce:transition-none",
          "hover:bg-zinc-950/[0.04] hover:text-zinc-950 data-[panel-open]:text-zinc-950",
          "dark:text-zinc-400 dark:hover:bg-white/[0.06] dark:hover:text-white dark:data-[panel-open]:text-white",
          "focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-sky-500",
        )}
      >
        <span aria-hidden="true" className="inline-flex shrink-0">
          {/* One mark throughout: it moves while the model thinks and holds still afterwards. */}
          <AgentMark
            activity="thinking"
            size={16}
            paused={!streaming}
            className={cx(
              "transition-colors duration-300 motion-reduce:transition-none",
              streaming ? "text-zinc-950 dark:text-white" : "text-zinc-950/40 dark:text-white/40",
            )}
          />
        </span>
        <span
          key={typeof text === "string" ? text : undefined}
          className={cx(
            "min-w-0 truncate",
            streaming && label == null ? "after:content-['…']" : "",
            `transition-[opacity,filter,translate] duration-300 ${ease} starting:translate-y-[3px] starting:opacity-0 starting:blur-[2px] motion-reduce:transition-none`,
          )}
        >
          {text}
        </span>
        <svg
          aria-hidden="true"
          viewBox="0 0 16 16"
          fill="none"
          className={cx(
            "size-3.5 shrink-0 text-zinc-400 dark:text-zinc-500",
            `transition-[rotate,color] duration-220 ${ease} motion-reduce:transition-none`,
            "group-hover:text-current group-data-[panel-open]:rotate-180 group-data-[panel-open]:text-current",
          )}
        >
          <path d="m4.5 6.25 3.5 3.5 3.5-3.5" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" />
        </svg>
      </Collapsible.Trigger>

      {/* Announces the switch from "Thinking" to the elapsed time, not the streamed text. */}
      <span role="status" className="sr-only">
        {announcement}
      </span>

      <Collapsible.Panel
        aria-busy={streaming || undefined}
        className={cx(
          "h-(--collapsible-panel-height) overflow-hidden",
          `transition-[height,opacity] duration-220 ${ease} motion-reduce:transition-none`,
          "data-[starting-style]:h-0 data-[starting-style]:opacity-0",
          "data-[ending-style]:h-0 data-[ending-style]:opacity-0 data-[ending-style]:duration-180",
        )}
      >
        {/* The rail lines up with the center of the mark above it. */}
        <div
          className={cx(
            "mt-1.5 ml-[7.5px] border-l border-zinc-950/10 pl-[18px] text-sm leading-relaxed whitespace-pre-wrap text-zinc-600 dark:border-white/10 dark:text-zinc-400",
            contentClassName,
          )}
        >
          {children}
        </div>
      </Collapsible.Panel>
    </Collapsible.Root>
  );
}