Trace

10.18.0

 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

ERR_PNPM_OUTDATED_LOCKFILE  Cannot install with "frozen-lockfile" because pnpm-lock.yaml is not up to date with package.json

"use client"

import * as React from "react"

Trace is a list of lines. Each line has an icon, a title, and an optional description and status. A line can expand to show more detail, link to a page, or open a dialog or sheet.

Every line has the same shape, so reasoning, tool calls, sources and plans built from Trace look and behave the same.

Use Trace for the steps an agent takes, like calling a tool, running a subagent or editing a file. Use Message for its reply, and Marker for notes and dividers between turns.

Built with Trace#

Every pattern below is a composition of Trace parts. See AI Elements for examples and code.

Installation#

pnpmnpmyarnbun
pnpm dlx shadcn@latest add trace
Copy

Usage#

Use a TraceLine for a single step:

Copyimport { Trace, TraceIcon, TraceLine, TraceTitle } from "@/components/ui/trace"

Copy<Trace>
  <TraceLine>
    <TraceIcon>
      <SearchIcon />
    </TraceIcon>
    <TraceTitle>Searched for minimumReleaseAge</TraceTitle>
  </TraceLine>
</Trace>

Wrap the line in a TraceCollapsible to show more detail when it expands:

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

Copy<Trace>
  <TraceCollapsible>
    <TraceCollapsibleTrigger>
      <TraceLine>
        <TraceIcon>
          <TerminalIcon />
        </TraceIcon>
        <TraceTitle>Ran node --version</TraceTitle>
      </TraceLine>
    </TraceCollapsibleTrigger>
    <TraceCollapsibleContent>v24.18.0</TraceCollapsibleContent>
  </TraceCollapsible>
</Trace>

Composition#

Use the following composition to build a trace line:

CopyTrace
└── TraceLine
    ├── TraceIcon
    ├── TraceTitle
    ├── TraceDescription
    └── TraceIcon

Wrap the line in a TraceCollapsible to show more detail when it expands:

CopyTrace
└── TraceCollapsible
    ├── TraceCollapsibleTrigger
    │   └── TraceLine
    └── TraceCollapsibleContent

TraceLine is always the line. To make a line do something, wrap it in that thing's trigger.

Features#

• One row for reasoning, tool calls, sources, plans and tasks
• Rows that expand, link out, or open a dialog, sheet, drawer or popover
• running, error and pending states, with a shimmer while running
• Nested rows, so a summary expands into steps and a step into its output
• Works with reasoning, tool and source parts from the AI SDK
• Keyboard and screen reader support from the trigger that wraps each row
• Customizable styling through the className prop on every part

Trace Line#

Use a TraceLine on its own for a step with no detail to show. It reads as plain text.

import { GitBranchIcon } from "lucide-react"

import {

Status#

Set status on TraceLine when a step is running, has failed or hasn't started yet.

import {
  CircleAlertIcon,
  CircleCheckIcon,

Description#

Put secondary text such as a diff stat, a duration or a count in a TraceDescription after the TraceTitle. It does not truncate.

import { FilePenIcon, SearchIcon, TerminalIcon } from "lucide-react"

import {

Collapsible#

Wrap the line in a TraceCollapsible to show more detail when it expands. Put the TraceLine inside TraceCollapsibleTrigger and the detail in TraceCollapsibleContent.

$ node --version
v24.18.0

import { TerminalIcon } from "lucide-react"

import { CodeBlock, CodeBlockContent } from "@/components/ui/code-block"

Open State#

Rows start closed. Use defaultExpanded on TraceCollapsible to start open, or isExpanded with onExpandedChange to control a row.

$ node --version
v24.18.0

$ pnpm --version
10.33.4

"use client"

import * as React from "react"

To open a row while it streams and let the reader's click win, pass open ?? running.

Copyconst [open, setOpen] = React.useState<boolean>()
 
<TraceCollapsible
  isExpanded={open ?? running}
  onExpandedChange={setOpen}
>
  <TraceCollapsibleTrigger>
    <TraceLine status={running ? "running" : undefined}>…</TraceLine>
  </TraceCollapsibleTrigger>
  <TraceCollapsibleContent>{text}</TraceCollapsibleContent>
</TraceCollapsible>

Link#

Wrap the TraceLine in an anchor. For a new tab, use an arrow-up-right icon and sr-only "(opens in a new tab)".

import {
  ArrowUpRightIcon,
  ChevronRightIcon,

Copy<a href="https://docs.astro.build" target="_blank" rel="noreferrer">
  <TraceLine>
    <TraceTitle>
      Install Astro
      <span className="sr-only"> (opens in a new tab)</span>
    </TraceTitle>
    <TraceIcon>
      <ArrowUpRightIcon />
    </TraceIcon>
  </TraceLine>
</a>

Dialog#

Wrap the TraceLine in the dialog's trigger. The dialog owns its open state, Escape and focus return.

"use client"

import { ArrowUpRightIcon, ChevronRightIcon, GlobeIcon } from "lucide-react"

Copy<DialogTrigger>
  <Button>
    <TraceLine>
      <TraceTitle>Searched the web for cache keys</TraceTitle>
      <TraceIcon>
        <ChevronRightIcon />
      </TraceIcon>
    </TraceLine>
  </Button>
  <Dialog>…</Dialog>
</DialogTrigger>

Note: Button is React Aria's Button. DialogTrigger needs a pressable child, and a plain button or a TraceLine is not one. React Aria's Button is a client component, so the file needs "use client".

Sheet#

The same shape as the dialog. Popover works the same way. Drawer is a Base UI drawer, so its trigger wraps the line directly: <Drawer><DrawerTrigger><TraceLine>…</TraceLine></DrawerTrigger><DrawerContent>…</DrawerContent></Drawer>.

"use client"

import { ChevronRightIcon, FolderSearchIcon } from "lucide-react"

Group#

Put rows that sit next to each other in a Trace. It also styles any trigger or link that wraps a TraceLine.

import { FileTextIcon, SearchIcon, TerminalIcon } from "lucide-react"

import {

Sources#

A collapsible row whose detail is a Trace of link rows.

import { ArrowUpRightIcon, GlobeIcon } from "lucide-react"

import {

See Sources for more examples.

Chain of Thought#

A chain of thought is a collapsible row with step rows inside. Set the parent's status and title from its children.

cache key image optimization

import { ChevronRightIcon, FileTextIcon, SearchIcon } from "lucide-react"

import { Badge } from "@/components/ui/badge"

See Chain of Thought and Task for more examples.

Commit#

A commit is a collapsible row with a line for each changed file. Say what changed in the title, Added, Edited or Deleted, and put the line counts in the description. Each file opens its diff in a Sheet.

"use client"

import {

Whole Turn#

Three levels: the turn, a summary, and the rows. Text between steps sits between two Trace lists.

command not found: pnpm

import {
  BrainIcon,
  ChevronRightIcon,

Reasoning#

Render a reasoning part from the AI SDK. The row is a TraceLine until the first text arrives. See Open State.

"use client"

import * as React from "react"

See Reasoning for more examples.

Tool#

Render tool parts from the AI SDK. Map the tool part as in Tool.

"use client"

import * as React from "react"

See Tool for more examples.

Accessibility#

Trace adds no roles of its own. Each line gets its semantics from the element that wraps it.

• A TraceLine on its own is a span. It is read as text and is not a tab stop.
• Wrap it in a TraceCollapsibleTrigger and it becomes a button with aria-expanded. Wrap it in a link, or in the trigger for a dialog or sheet, and it takes the keyboard and focus behavior of that element.
• TraceIcon is hidden from assistive tech, so TraceTitle is the accessible name. Write it as a sentence that says what happened, like "Edited trace.tsx", not just "trace.tsx".
• When a link opens a new tab, add "(opens in a new tab)" to the title with sr-only.
• Status is shown with color and motion, so put it in the title too. Write "Running pnpm build" while it runs and "Failed to run pnpm build" when it errors.
• The shimmer on a running title stops when the reader prefers reduced motion. The title still says what is happening.
• Inside a Message Scroller, each line is announced once when it is added.
• TraceCollapsibleContent mutes its text. If you put a block with a muted background inside it, give the block text-foreground so it keeps its contrast. CodeBlock sets its own text color.

API Reference#

Trace#

A list of rows. It also styles any trigger or link that wraps a TraceLine.

TraceLine#

One line: an icon and a title. It is a span, so it is not a button or a tab stop. Wrap it in a trigger or a link to make it do something.

TraceIcon#

A decorative icon slot, hidden from assistive tech. Before the title it names the action; after it, it is the indicator.

TraceTitle#

One sentence on one line. It truncates and shimmers while the line is running.

TraceDescription#

Secondary text after the title, such as a count or a duration. It does not truncate.

TraceCollapsible#

A row that expands. It accepts the props of Collapsible. className takes a string only.

TraceCollapsibleTrigger#

The button that opens and closes the row. Put a TraceLine inside it. It adds a chevron after the line.

TraceCollapsibleContent#

The detail of a row that expands.