# Trace

The primitive for rendering collapsible agent trace lines with icons, titles, and status.

> For the complete documentation index, see [llms.txt](/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](/.well-known/agent-skills/site-skill.md).

<ComponentPreview name="trace" title="trace.tsx" previewClassName="h-auto">
<TraceDemo />
</ComponentPreview>

Trace is the foundational primitive behind [Chain of Thought](/docs/ai-elements/chain-of-thought) and any vertical step list. It composes a flex column of lines, each with an icon, title, and optional status.

## Installation [#installation]

<CodeTabs>
<TabsList>
<TabsTrigger value="cli">
Command
</TabsTrigger>

<TabsTrigger value="manual">
Manual
</TabsTrigger>
</TabsList>

<TabsContent value="cli">
~~~bash
npx frakment add trace
~~~
</TabsContent>

<TabsContent value="manual">
<Steps>
<Step>
Install the following dependencies:
</Step>

~~~bash
npm install lucide-react
~~~

<Step>
Copy and paste the following code into your project.
</Step>

<ComponentSource name="trace" title="components/ui/trace.tsx" />

<Step>
Update the import paths to match your project setup.
</Step>
</Steps>
</TabsContent>
</CodeTabs>

## Usage [#usage]

~~~tsx title="trace.tsx"
import { Trace, TraceLine, TraceIcon, TraceTitle } from "@/components/ui/trace";
<DocsBaseSwitcher base="web" component="trace" className="mb-6" />
~~~

~~~tsx title="trace.tsx"
<Trace>
  <TraceLine>
    <TraceIcon>
      <SearchIcon />
    </TraceIcon>
    <TraceTitle>Searched for 3 sources</TraceTitle>
  </TraceLine>
</Trace>
~~~
## Composition [#composition]

```text
Trace
├── TraceLine
│   ├── TraceIcon
│   ├── TraceTitle
│   └── TraceDescription
└── TraceCollapsible
    ├── TraceCollapsibleTrigger
    └── TraceCollapsibleContent
```

## Static line [#static-line]

The smallest trace: an icon and a sentence.

<ComponentPreview name="trace-static" title="trace-static.tsx" src="examples/trace-static.tsx" previewClassName="h-auto">
<r />
</ComponentPreview>

## Status [#status]

Use `status` on **TraceLine** to convey state without extra markup.

| Status | Effect |
| :-- | :-- |
| `running` | Foreground color, shimmer on title |
| `error` | Destructive color |
| `pending` | 60% opacity |

<ComponentPreview name="trace-status" title="trace-status.tsx" src="examples/trace-status.tsx" previewClassName="h-auto">
<c />
</ComponentPreview>

## With description [#with-description]

Place a `TraceDescription` after the title to show a secondary value, such as a duration or byte count.

<ComponentPreview name="trace-description" title="trace-description.tsx" src="examples/trace-description.tsx" previewClassName="h-auto">
<x />
</ComponentPreview>

## Collapsible [#collapsible]

Wrap a **TraceLine** in **TraceCollapsibleTrigger** to make it expand into nested steps.

<ComponentPreview name="trace-collapsible" title="trace-collapsible.tsx" src="examples/trace-collapsible.tsx" previewClassName="h-auto">
<m />
</ComponentPreview>

## Controlled open [#controlled-open]

Pass `open` and `onOpenChange` to control the collapsible from outside.

<ComponentPreview name="trace-open" title="trace-open.tsx" src="examples/trace-open.tsx" previewClassName="h-auto">
<TraceOpen />
</ComponentPreview>

## Links [#links]

Wrap a **TraceLine** in an anchor to make it navigable.

<ComponentPreview name="trace-link" title="trace-link.tsx" src="examples/trace-link.tsx" previewClassName="h-auto">
<b />
</ComponentPreview>

## Group [#group]

Stack multiple lines to form a group of related steps.

<ComponentPreview name="trace-group" title="trace-group.tsx" src="examples/trace-group.tsx" previewClassName="h-auto">
<F />
</ComponentPreview>

## Sources [#sources]

Group source links inside a collapsible trace.

<ComponentPreview name="trace-sources" title="trace-sources.tsx" src="examples/trace-sources.tsx" previewClassName="h-auto">
<C />
</ComponentPreview>

## Steps [#steps]

Model a multi-step task with nested collapsibles and a running status.

<ComponentPreview name="trace-steps" title="trace-steps.tsx" src="examples/trace-steps.tsx" previewClassName="h-auto">
<A />
</ComponentPreview>

## Commit [#commit]

Show a commit with per-file diffs inside a sheet.

<ComponentPreview name="trace-commit" title="trace-commit.tsx" src="examples/trace-commit.tsx" previewClassName="h-auto">
<L />
</ComponentPreview>

## Dialog [#dialog]

Open a full result set from a trace line using a dialog.

<ComponentPreview name="trace-dialog" title="trace-dialog.tsx" src="examples/trace-dialog.tsx" previewClassName="h-auto">
<G />
</ComponentPreview>

## Sheet [#sheet]

Open a list of files from a trace line using a sheet.

<ComponentPreview name="trace-sheet" title="trace-sheet.tsx" src="examples/trace-sheet.tsx" previewClassName="h-auto">
<q />
</ComponentPreview>

## Full turn [#full-turn]

Nest traces to model a full agent turn with reasoning, tool calls, and output.

<ComponentPreview name="trace-turn" title="trace-turn.tsx" src="examples/trace-turn.tsx" previewClassName="h-auto">
<K />
</ComponentPreview>

## Thinking [#thinking]

Stream a reasoning block as it is generated.

<ComponentPreview name="trace-thinking" title="trace-thinking.tsx" src="examples/trace-thinking.tsx" previewClassName="h-auto">
<TraceThinking />
</ComponentPreview>

## Tool calls [#tool-calls]

Track tool invocations with running, done, and failed states.

<ComponentPreview name="trace-tool-calls" title="trace-tool-calls.tsx" src="examples/trace-tool-calls.tsx" previewClassName="h-auto">
<TraceToolCalls />
</ComponentPreview>

## In Context [#in-context]

### Agent step list [#agent-step-list]

<ComponentPreview name="trace-agent-step" title="trace-agent-step.tsx" src="examples/trace-agent-step.tsx">
<TraceAgentStep />
</ComponentPreview>

## Motion [#motion]

`TraceCollapsible` accepts `motion` on the root, inherited by content.

## API Reference [#api-reference]

### Trace / TraceIcon / TraceTitle / TraceDescription [#trace--traceicon--tracetitle--tracedescription]

Extend `React.ComponentProps<"div">` and `React.ComponentProps<"span">`. **TraceIcon** is `aria-hidden`. **TraceTitle** wraps its children in a shimmer when the parent line is `running`.

### TraceLine [#traceline]

<PropsTable rows={[{"name":"status","type":"running | error | pending","description":"Controls color and shimmer behavior of the line."}]} />

### TraceCollapsible [#tracecollapsible]

Extends `React.ComponentProps<"div">`. Supports `open`, `defaultOpen`, `onOpenChange`, `motion` (inherited by content), and deprecated `animation` (BC).

### TraceCollapsibleTrigger [#tracecollapsibletrigger]

Renders a native `<button>`. Chevron rotates 90° when open via a CSS transform.
### TraceCollapsibleContent [#tracecollapsiblecontent]

Extends `React.ComponentProps<"div">`. Animates height via CSS grid rows (`0fr` ↔ `1fr`) with an opacity fade, re-targeting on content growth automatically. Accepts `motion` (per-instance override), `animation` (deprecated BC), and `animateHeight` (pass `false` to render plain show/hide).

## Accessibility [#accessibility]

- `TraceIcon` is `aria-hidden`. Use `TraceTitle` as the accessible name — write it as a sentence.
- Status is conveyed by icon shape and color, not color alone.
- `prefers-reduced-motion` disables shimmer and collapse animation.

## Best Practices [#best-practices]

- **One line per step.** Do not merge unrelated actions into one line.
- **Wrap trace in a collapsible for long runs.** Ten lines collapse the transcript.
- **Mark running steps.** `status="running"` triggers the shimmer and spinner.
- **Keep titles verb-first.** "Ran pnpm test", not "pnpm test status".