Skip to content

shadcn.io is an independent project built on shadcn/ui

Components

Free

Trace for React

Each step an AI agent takes as one line: its reasoning, tool calls, edits and sources. Lines expand or open a dialog, in React on Base UI.

On this page10 sections

Trace lists what an AI agent did on the way to its answer, one line per step: the search it ran, the file it read, the command that failed. A line can stay plain text, open onto its output, link to a page or open a dialog.

The reply itself goes in a Message. For a tool call or a chain of thought that is ready to paste, start from Tool or Chain of Thought, which are built from these parts.

Preview width

Installation

Sign in to get your install command
Free with an account. It carries your token, so the CLI installs everything in one go.

Anatomy

Trace anatomy: root, line, icon, description, trigger, content

Usage

import { SearchIcon, TerminalIcon } from "lucide-react";
import {
  Trace, TraceCollapsible, TraceCollapsibleContent,
  TraceCollapsibleTrigger, TraceIcon, TraceLine, TraceTitle,
} from "@/components/ui/trace";
<Trace className="max-w-sm">
  <TraceLine>
    <TraceIcon>
      <SearchIcon aria-hidden="true" />
    </TraceIcon>
    <TraceTitle>Searched for minimumReleaseAge</TraceTitle>
  </TraceLine>
  <TraceCollapsible>
    <TraceCollapsibleTrigger>
      <TraceLine>
        <TraceIcon>
          <TerminalIcon aria-hidden="true" />
        </TraceIcon>
        <TraceTitle>Ran node --version</TraceTitle>
      </TraceLine>
    </TraceCollapsibleTrigger>
    <TraceCollapsibleContent>v24.18.0</TraceCollapsibleContent>
  </TraceCollapsible>
</Trace>

TraceLine is the line in every case. To make it do something, put it inside that thing's trigger: TraceCollapsibleTrigger for a line that expands, as the second one here does, or a link, or a dialog's trigger.

Accessibility

Trace adds no role of its own. A TraceLine is a span, read as text and passed over by Tab, until you wrap it: inside TraceCollapsibleTrigger it becomes a <button> with aria-expanded, and inside a link or a dialog's trigger it takes that element's role and keys. TraceIcon is hidden from screen readers, so TraceTitle names the line. The red of an error and the shimmer of a running step are only visual, so put the state in the title's words: Running pnpm build, Failed to run pnpm lint. A link that opens a new tab should say so in an sr-only span, as the demos' links do.

Enter
When focus is on a line that expands, opens or closes it. On a link it follows the link, and on a dialog's or sheet's trigger it opens the overlay.
Space
When focus is on a line that expands, opens or closes it. On a dialog's or sheet's trigger, opens the overlay.
Tab
Moves focus to the next line that does something, or to anything focusable in an open line's content, such as its Code Block. Plain lines, and everything inside a closed line, are skipped.
Shift+Tab
Moves focus back through the same stops, to the previous line that does something or into an open line's content.

Demos

Static

One line, a branch icon and Created branch fix/frozen-lockfile, with nothing behind it. A TraceLine on its own is a span, so a screen reader reads it as text and Tab passes over it. Use it for a step with no output worth opening, rather than wrapping every line in a trigger so they all look clickable.

Preview width

Status

Four lines, one for each status: Ran pnpm install with none, Failed to run pnpm lint as error, Running pnpm build as running and Run pnpm test as pending. The error line turns destructive, the running title shimmers and the pending line fades. Each title is written in the tense of its state, because a screen reader hears no color.

Preview width

Description

An edited file with +48 −12 after its path, a test run that took 14s and a search that found 8 results. TraceDescription never shrinks, so on a narrow line the long file path in the title is cut short first. Keep it to a number or a word. The diff stat sets dir to ltr, so it still reads +48 −12 on a right-to-left page.

Preview width

Collapsible

Ran node --version opens onto its output in a Code Block. The TraceLine goes inside TraceCollapsibleTrigger, which adds the chevron after it, and the output goes in TraceCollapsibleContent, indented behind a thin rule. Use it when the detail is worth a look but not worth the room until someone asks for it.

Preview width

Open

Ran node --version starts open, and Ran pnpm --version opens when pressed or from the Show the pnpm output button under it. Every line starts closed unless you set defaultOpen on its TraceCollapsible. Hold the open state yourself, as the second line does, when something outside the line has to open it.

Preview width

Two lines wrapped in links. Read apps/v4/lib/docs.ts goes to a page in the app and ends in a chevron, while the Astro install guide opens in a new tab, ends in an arrow pointing up and out, and tells screen readers so. Each link sits directly inside Trace, which lays it out as a row with a focus ring.

Preview width

Dialog

Searched the web for cache keys opens a Dialog listing the three results the reply used, each a link that opens in a new tab. The line goes in the dialog's trigger, and the dialog brings its own focus trap, Escape and return of focus. Use it when the detail needs a surface of its own.

Preview width

Sheet

Explored 4 files opens a Sheet from the side of the screen, with the paths of the four files the agent read. It is built the same way as the Dialog demo, with the line in the sheet's trigger. Pick a sheet when the detail is long, such as a diff or a file, and the reader wants the chat still in sight behind it.

Preview width

Group

Searched for minimumReleaseAge, Read pnpm-workspace.yaml and Ran pnpm install, three plain lines in one Trace. Lines that follow each other belong in one list, which spaces them evenly and styles any link or trigger that wraps one. Start a new Trace where the reply's own text breaks the run, as the Turn demo does.

Preview width

Sources

Used 3 sources starts open and holds a second Trace of links, one for each page the reply drew on, each opening in a new tab. Put it under an answer for its citations, and keep the count in the title so the line says how many there are while it is closed. The Sources pattern is built this way.

Preview width

Steps

Looking into the slow deploy is a running summary that opens onto three steps: a search that expands into the two domains it hit, a link to the last twelve deploys, and a search still running. Trace doesn't read the steps, so set the summary's status and title from them yourself. Chain of Thought is this shape.

Preview width

Commit

Committed a1b2c3: Fix the login redirect opens onto a line per changed file, with Added or Edited in the title and the line counts after it. Each file opens its diff in a Sheet. Show it after an agent commits, so the reader can check the change without leaving the chat.

Preview width

Turn

A whole turn in three levels: Worked for 2m 4s, 1 command failed, then a thought and a summary of two commands, then the commands, where pnpm --version failed. The demo sets status to error on each line above the failure by hand, because Trace doesn't carry a child's state up. The agent's sentence between the steps sits between two Trace lists, not inside one.

Preview width

Thinking

Press Send message to watch the reasoning stream in under the question. The line reads Thinking with a shimmer and stays open while the words arrive, then reads Thought and folds shut once the reasoning is done, unless the reader opened or closed it first. With the AI SDK this is a reasoning part, shown as a plain line until its first text arrives.

Preview width

Tool calls

Press Send message and three commands run one after another: node --version and npm --version answer, and pnpm --version fails because pnpm isn't installed. Each line reads Running while it waits, then Ran or Failed to run, and opens onto its output in a Code Block. With the AI SDK these are tool parts, running in input-available and done in output-available or output-error.

Preview width

Patterns built from these parts

These pages have no component of their own. Each is a composition of Trace's parts, sometimes with a Code Block or a Badge, and the code to copy is in its demos.

PatternShows
Chain of ThoughtA summary that expands into the steps behind it.
PlanThe steps the agent plans to take, and how far it has got.
QueueThe agent's todo list, split into what is left and what is done.
ReasoningThe agent's thinking as it streams.
SourcesThe links the agent used for a reply.
Stack TraceA failed tool call and its stack frames.
SubagentA subagent run, with its tool calls and result.
TaskThe steps the agent takes, as it takes them.
TerminalA command the agent runs, with its output as it streams.
Test ResultsA test run by the agent, with its suites and failures.
ToolA tool call the agent makes, from input to output.

FAQ

When should I use Trace instead of Steps or an Accordion?

Use Trace for a record of what an agent did or is doing: one line per step, with the detail a click away and most lines closed. Lines can nest, link out or open an overlay, and the list grows as the agent works.

Steps is a numbered flow a person works through, such as a checkout or an onboarding form. An Accordion is a set of headed sections, like an FAQ, where the headings are the content people scan. For a single note between turns, use a Marker.

How do I make a Trace line expand in React?

Put the line inside a collapsible: TraceCollapsible around a TraceCollapsibleTrigger that holds the TraceLine, then the detail in TraceCollapsibleContent, as the Collapsible demo does. The trigger is the button, and it adds a chevron after the line that turns when the line opens.

Keep the TraceLine inside the trigger rather than giving the line a click handler. It is a span, so on its own it takes no focus and answers no keys.

How do I keep a Trace line open while the agent is still streaming?

Keep the reader's choice in state that starts as undefined. Pass open as that state once it is set and as your running flag until then, and store the boolean that onOpenChange receives.

The line then opens while the step runs and folds shut when it ends. Once the reader opens or closes it, their choice wins, as in the Thinking demo.

Do nested Trace lines keep their state when their parent closes?

Yes. The Collapsible that Trace builds on passes keepMounted to Base UI's panel, so a closed TraceCollapsibleContent stays in the page, hidden, and the lines inside keep whatever the reader opened. Set keepMounted to false on TraceCollapsibleContent to remove it once it closes.

While the parent is closed, the lines inside it are out of the tab order and hidden from screen readers.

How do I open a dialog or a sheet from a Trace line?

Put the TraceLine inside the overlay's trigger, DialogTrigger or SheetTrigger, as the Dialog and Sheet demos do. The trigger renders a button around the line, so it takes focus, opens on Enter or Space, and gets focus back when the overlay closes.

Keep the trigger a direct child of Trace, and it lays out as a row with the same focus ring as the lines that expand.

How do I show that a Trace step is running or failed?

Set status on TraceLine to running, error or pending. A running line sweeps a shimmer across its title, an error turns the line and its trigger's chevron destructive, and a pending one fades. Trace tracks no work itself, so the value comes from your data, and a summary line above a failure needs its own status, as in the Turn demo.

Say the state in the title as well, because color and motion don't reach a screen reader. The shimmer is the shimmer utility, which the install adds with Trace, and it stops for readers who ask for reduced motion.

API Reference

Trace

<div> data-slot="trace"

PropType
className?string

Merged with the part's classes.

TraceCollapsible

PropType
open?boolean

Whether the collapsible panel is currently open. To render an uncontrolled collapsible, use the defaultOpen prop instead.

defaultOpen?boolean

Whether the collapsible panel is initially open. To render a controlled collapsible, use the open prop instead.

Default
false
onOpenChange?(open: boolean, eventDetails: CollapsibleRootChangeEventDetails) → void

Event handler called when the panel is opened or closed.

Type
(open: boolean, eventDetails: CollapsibleRootChangeEventDetails) → void
Parameters

open – boolean

eventDetails – CollapsibleRootChangeEventDetails

Returns
void
disabled?boolean

Whether the component should ignore user interaction.

Default
false
render?ReactElement | ((props: object, state: object) => ReactElement)

Replace the host element or compose it with another component.

Type
ReactElement | ((props: object, state: object) => ReactElement)
className?string

Merged with the part's classes.

TraceCollapsibleContent

data-slot="trace-collapsible-content"

PropType
disableAnimation?boolean

Opens and closes it at once, without the height animation.

hiddenUntilFound?boolean

Allows the browser's built-in page search to find and expand the panel contents. Overrides the keepMounted prop and uses hidden="until-found" to hide the element without removing it from the DOM.

Default
false
keepMounted?boolean

Whether to keep the element in the DOM while the panel is hidden. This prop is ignored when hiddenUntilFound is used.

Default
false
render?ReactElement | ((props: object, state: object) => ReactElement)

Replace the host element or compose it with another component.

Type
ReactElement | ((props: object, state: object) => ReactElement)
className?string

Merged with the part's classes.

CSS variableType
--collapsible-panel-heightstring

TraceCollapsibleTrigger

data-slot="trace-collapsible-trigger"

PropType
nativeButton?boolean

Whether the component renders a native <button> element when replacing it via the render prop. Set to false if the rendered element is not a button (for example, <div>).

Default
true
render?ReactElement | ((props: object, state: object) => ReactElement)

Replace the host element or compose it with another component.

Type
ReactElement | ((props: object, state: object) => ReactElement)
className?string

Merged with the part's classes.

TraceDescription

<span> data-slot="trace-description"

PropType
className?string

Merged with the part's classes.

TraceIcon

<span> data-slot="trace-icon"

PropType
className?string

Merged with the part's classes.

TraceLine

<span> data-slot="trace-line"

PropType
status?"running" | "error" | "pending"

The state of the work the line reports.

Type
"running" | "error" | "pending"
className?string

Merged with the part's classes.

AttributeType
data-status?string

Mirrors status.

TraceTitle

<span> data-slot="trace-title"

PropType
className?string

Merged with the part's classes.