# Trace

The steps an agent takes, as lines that can expand to show their detail.

Source: [trace.tsx](https://github.com/jakejarvis/jarvis-ui/blob/main/src/components/ui/trace.tsx)

```tsx
import { FileTextIcon, PencilIcon, SearchIcon, TerminalIcon } from "lucide-react";

import { CodeBlock } from "@/components/ui/code-block";
import { Spinner } from "@/components/ui/spinner";
import {
  Trace,
  TraceCollapsible,
  TraceCollapsibleContent,
  TraceCollapsibleTrigger,
  TraceDescription,
  TraceIcon,
  TraceLine,
  TraceTitle,
} from "@/components/ui/trace";

const output = `Lockfile is up to date, resolution step is skipped
Packages: +4 -1
Done in 2.1s using pnpm v10.12.1`;

export default function TraceSteps() {
  return (
    <Trace className="w-full max-w-md">
      <TraceLine>
        <TraceIcon>
          <SearchIcon />
        </TraceIcon>
        <TraceTitle>Searched for minimumReleaseAge</TraceTitle>
        <TraceDescription>3 results</TraceDescription>
      </TraceLine>
      <TraceLine>
        <TraceIcon>
          <FileTextIcon />
        </TraceIcon>
        <TraceTitle>Read pnpm-workspace.yaml</TraceTitle>
      </TraceLine>
      <TraceLine>
        <TraceIcon>
          <PencilIcon />
        </TraceIcon>
        <TraceTitle>Edited pnpm-workspace.yaml</TraceTitle>
        <TraceDescription>
          <span className="text-success">+2</span> <span className="text-destructive">−1</span>
        </TraceDescription>
      </TraceLine>
      <TraceCollapsible>
        <TraceCollapsibleTrigger>
          <TraceLine>
            <TraceIcon>
              <TerminalIcon />
            </TraceIcon>
            <TraceTitle>Ran pnpm install</TraceTitle>
            <TraceDescription>2.1s</TraceDescription>
          </TraceLine>
        </TraceCollapsibleTrigger>
        <TraceCollapsibleContent>
          <CodeBlock code={output} />
        </TraceCollapsibleContent>
      </TraceCollapsible>
      <TraceLine status="running">
        <TraceIcon>
          <Spinner />
        </TraceIcon>
        <TraceTitle>Running pnpm build</TraceTitle>
      </TraceLine>
    </Trace>
  );
}
```

## Installation

Add the registry, once per project:

```bash
npx shadcn@latest registry add @jarvis=https://ui.jarv.is/r/{name}.json
```

Then add the component:

```bash
npx shadcn@latest add @jarvis/trace
```

## Usage

```tsx
import { SearchIcon, TerminalIcon } from "lucide-react";

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

export function AgentSteps() {
  return (
    <Trace>
      <TraceLine>
        <TraceIcon>
          <SearchIcon />
        </TraceIcon>
        <TraceTitle>Searched for createInvoice</TraceTitle>
        <TraceDescription>3 results</TraceDescription>
      </TraceLine>
      <TraceCollapsible>
        <TraceCollapsibleTrigger>
          <TraceLine>
            <TraceIcon>
              <TerminalIcon />
            </TraceIcon>
            <TraceTitle>Ran node --version</TraceTitle>
          </TraceLine>
        </TraceCollapsibleTrigger>
        <TraceCollapsibleContent>v24.18.0</TraceCollapsibleContent>
      </TraceCollapsible>
    </Trace>
  );
}
```

A line is text, not a control. To make a line expandable, put it in a `TraceCollapsibleTrigger`,
which turns it into a button and adds a caret. To make a line open a page, a
[Dialog](https://ui.jarv.is/components/dialog.md) or a [Sheet](https://ui.jarv.is/components/sheet.md), put it in a link or in that
component's trigger instead.

`TraceTitle` stays on one line and truncates. `TraceDescription` doesn't truncate, so keep it
short, such as a duration or a count.

## Composition

- `Trace`
  - `TraceLine`
    - `TraceIcon`
    - `TraceTitle`
    - `TraceDescription`
  - `TraceCollapsible`
    - `TraceCollapsibleTrigger`
      - `TraceLine`
    - `TraceCollapsibleContent`

## Examples

### States

`status` sets the state of the work: `pending` before it starts, `running` while it happens, and
`error` when it failed. `running` adds a shimmer to the title. Leave `status` out once the work is
done. The color and motion aren't announced, so say the state in the title too, as in "Running
pnpm test" or "Failed to run pnpm typecheck". The shimmer stops when reduced motion is preferred.

```tsx
import { CircleCheckIcon, CircleDashedIcon, CircleXIcon } from "lucide-react";

import { Spinner } from "@/components/ui/spinner";
import { Trace, TraceIcon, TraceLine, TraceTitle } from "@/components/ui/trace";

export default function TraceStates() {
  return (
    <Trace>
      <TraceLine>
        <TraceIcon>
          <CircleCheckIcon />
        </TraceIcon>
        <TraceTitle>Ran pnpm lint</TraceTitle>
      </TraceLine>
      <TraceLine status="error">
        <TraceIcon>
          <CircleXIcon />
        </TraceIcon>
        <TraceTitle>Failed to run pnpm typecheck</TraceTitle>
      </TraceLine>
      <TraceLine status="running">
        <TraceIcon>
          <Spinner />
        </TraceIcon>
        <TraceTitle>Running pnpm test</TraceTitle>
      </TraceLine>
      <TraceLine status="pending">
        <TraceIcon>
          <CircleDashedIcon />
        </TraceIcon>
        <TraceTitle>Deploy a preview</TraceTitle>
      </TraceLine>
    </Trace>
  );
}
```

### Reasoning

Show a model's reasoning as a line that expands to show its thoughts. While the reasoning streams,
title the line "Thinking" and give it the `running` status. Once it's done, say how long it took.

```tsx
import { BrainIcon } from "lucide-react";

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

const thoughts = `The person wants to know why the build is slow. The log shows the type check takes 41 of the 58 seconds, so that's the place to start.

Skipping the library check would hide errors in our own declaration files, so caching the build info with incremental is the safer fix.`;

export default function TraceReasoning() {
  return (
    <Trace className="w-full max-w-md">
      <TraceCollapsible defaultOpen>
        <TraceCollapsibleTrigger>
          <TraceLine>
            <TraceIcon>
              <BrainIcon />
            </TraceIcon>
            <TraceTitle>Thought for 6 seconds</TraceTitle>
          </TraceLine>
        </TraceCollapsibleTrigger>
        <TraceCollapsibleContent className="whitespace-pre-wrap">
          {thoughts}
        </TraceCollapsibleContent>
      </TraceCollapsible>
    </Trace>
  );
}
```

To open the line while the thoughts stream and close it when they finish, control `open`. Once
someone opens or closes it themselves, keep their choice. Until the first thoughts arrive, show the
line on its own, since there's nothing to expand.

```tsx
"use client";

import { BrainIcon } from "lucide-react";
import * as React from "react";

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

export function Reasoning({
  text,
  streaming,
  seconds,
}: {
  text: string;
  streaming: boolean;
  seconds?: number;
}) {
  const [open, setOpen] = React.useState<boolean>();

  const line = (
    <TraceLine status={streaming ? "running" : undefined}>
      <TraceIcon>
        <BrainIcon />
      </TraceIcon>
      <TraceTitle>
        {streaming ? "Thinking" : seconds ? `Thought for ${seconds} seconds` : "Thought"}
      </TraceTitle>
    </TraceLine>
  );

  if (!text) return line;

  return (
    <TraceCollapsible open={open ?? streaming} onOpenChange={setOpen}>
      <TraceCollapsibleTrigger>{line}</TraceCollapsibleTrigger>
      <TraceCollapsibleContent className="whitespace-pre-wrap">{text}</TraceCollapsibleContent>
    </TraceCollapsible>
  );
}
```

### Sources

The sources a reply read can go under a single line that expands to show a link for each one.
Render each source's line as a link with `render`, and give it a focus ring, since a plain line has
none.

```tsx
import { GlobeIcon, LinkIcon } from "lucide-react";

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

const sources = [
  { title: "Rate limits", site: "example.com", href: "#rate-limits" },
  { title: "Errors", site: "example.com", href: "#errors" },
  { title: "Retrying requests", site: "docs.example.org", href: "#retrying-requests" },
];

export default function TraceSources() {
  return (
    <Trace className="w-full max-w-md">
      <TraceCollapsible defaultOpen>
        <TraceCollapsibleTrigger>
          <TraceLine>
            <TraceIcon>
              <GlobeIcon />
            </TraceIcon>
            <TraceTitle>Read {sources.length} sources</TraceTitle>
          </TraceLine>
        </TraceCollapsibleTrigger>
        <TraceCollapsibleContent>
          <Trace>
            {sources.map((source) => (
              <TraceLine
                key={source.title}
                render={<a href={source.href} />}
                className="cursor-pointer rounded-sm hover:text-foreground focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring"
              >
                <TraceIcon>
                  <LinkIcon />
                </TraceIcon>
                <TraceTitle>{source.title}</TraceTitle>
                <TraceDescription>{source.site}</TraceDescription>
              </TraceLine>
            ))}
          </Trace>
        </TraceCollapsibleContent>
      </TraceCollapsible>
    </Trace>
  );
}
```

To cite a source within the reply itself, use a [Citation](https://ui.jarv.is/components/citation.md).

### Nested

Put a `Trace` in `TraceCollapsibleContent` to group steps under one line, such as a subagent's
steps. The nested content is indented to align with the title above it.

```tsx
import { BotIcon, FileTextIcon, SearchIcon } from "lucide-react";

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

export default function TraceNested() {
  return (
    <Trace className="w-full max-w-md">
      <TraceCollapsible defaultOpen>
        <TraceCollapsibleTrigger>
          <TraceLine>
            <TraceIcon>
              <BotIcon />
            </TraceIcon>
            <TraceTitle>Explored the billing code</TraceTitle>
            <TraceDescription>3 steps</TraceDescription>
          </TraceLine>
        </TraceCollapsibleTrigger>
        <TraceCollapsibleContent>
          <Trace>
            <TraceLine>
              <TraceIcon>
                <SearchIcon />
              </TraceIcon>
              <TraceTitle>Searched for createInvoice</TraceTitle>
            </TraceLine>
            <TraceLine>
              <TraceIcon>
                <FileTextIcon />
              </TraceIcon>
              <TraceTitle>Read src/billing/invoices.ts</TraceTitle>
            </TraceLine>
            <TraceLine>
              <TraceIcon>
                <FileTextIcon />
              </TraceIcon>
              <TraceTitle>Read src/billing/plans.ts</TraceTitle>
            </TraceLine>
          </Trace>
        </TraceCollapsibleContent>
      </TraceCollapsible>
    </Trace>
  );
}
```

## Props

| Part | Extends |
| --- | --- |
| `Trace` | `<div>` |
| `TraceLine` | `<span>` |
| `TraceIcon` | `<span>` |
| `TraceTitle` | `<span>` |
| `TraceDescription` | `<span>` |
| `TraceCollapsible` | [`Collapsible`](https://ui.jarv.is/components/collapsible.md) |
| `TraceCollapsibleTrigger` | [`CollapsibleTrigger`](https://ui.jarv.is/components/collapsible.md) |
| `TraceCollapsibleContent` | `<div>` |

Base UI's [styling](https://base-ui.com/react/handbook/styling) and [composition](https://base-ui.com/react/handbook/composition) guides say more about `className`, `style` and `render`.

### Trace

| Prop         | Type                                                     | Default | Description                                                                                                                                                                               |
| ------------ | -------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `className?` | `string`                                                 | —       | CSS class applied to the element.                                                                                                                                                         |
| `style?`     | `React.CSSProperties`                                    | —       | Style applied to the element.                                                                                                                                                             |
| `render?`    | `ComponentRenderFn<HTMLProps, {}> \| React.ReactElement` | —       | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

### TraceLine

| Prop           | Type                                                     | Default | Description                                                                                                                                                                                         |
| -------------- | -------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status?`      | `"error" \| "pending" \| "running"`                      | —       | The state of the work the line reports: `running` while it happens, `error` when it failed and `pending` before it starts. Leave it out for work that's done.                                       |
| `statusLabel?` | `string`                                                 | —       | Read by screen readers before the line while it has a `status`, since the status otherwise shows only as color. Defaults to "Running", "Failed" or "Pending". Pass an empty string to read nothing. |
| `className?`   | `string`                                                 | —       | CSS class applied to the element.                                                                                                                                                                   |
| `style?`       | `React.CSSProperties`                                    | —       | Style applied to the element.                                                                                                                                                                       |
| `render?`      | `ComponentRenderFn<HTMLProps, {}> \| React.ReactElement` | —       | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.           |

### TraceIcon

| Prop         | Type                                                     | Default | Description                                                                                                                                                                               |
| ------------ | -------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `className?` | `string`                                                 | —       | CSS class applied to the element.                                                                                                                                                         |
| `style?`     | `React.CSSProperties`                                    | —       | Style applied to the element.                                                                                                                                                             |
| `render?`    | `ComponentRenderFn<HTMLProps, {}> \| React.ReactElement` | —       | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

### TraceTitle

| Prop         | Type                                                     | Default | Description                                                                                                                                                                               |
| ------------ | -------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `className?` | `string`                                                 | —       | CSS class applied to the element.                                                                                                                                                         |
| `style?`     | `React.CSSProperties`                                    | —       | Style applied to the element.                                                                                                                                                             |
| `render?`    | `ComponentRenderFn<HTMLProps, {}> \| React.ReactElement` | —       | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

### TraceDescription

| Prop         | Type                                                     | Default | Description                                                                                                                                                                               |
| ------------ | -------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `className?` | `string`                                                 | —       | CSS class applied to the element.                                                                                                                                                         |
| `style?`     | `React.CSSProperties`                                    | —       | Style applied to the element.                                                                                                                                                             |
| `render?`    | `ComponentRenderFn<HTMLProps, {}> \| React.ReactElement` | —       | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

### TraceCollapsible

| Prop            | Type                                                                                         | Default | Description                                                                                                                                                                               |
| --------------- | -------------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `open?`         | `boolean`                                                                                    | —       | Whether the collapsible panel is currently open. To render an uncontrolled collapsible, use the `defaultOpen` prop instead.                                                               |
| `defaultOpen?`  | `boolean`                                                                                    | `false` | Whether the collapsible panel is initially open. To render a controlled collapsible, use the `open` prop instead.                                                                         |
| `onOpenChange?` | `((open: boolean, eventDetails: CollapsibleRootChangeEventDetails) => void)`                 | —       | Event handler called when the panel is opened or closed.                                                                                                                                  |
| `disabled?`     | `boolean`                                                                                    | `false` | Whether the component should ignore user interaction.                                                                                                                                     |
| `className?`    | `string \| ((state: CollapsibleRootState) => string \| undefined)`                           | —       | CSS class applied to the element, or a function that returns a class based on the component's state.                                                                                      |
| `style?`        | `React.CSSProperties \| ((state: CollapsibleRootState) => React.CSSProperties \| undefined)` | —       | Style applied to the element, or a function that returns a style object based on the component's state.                                                                                   |
| `render?`       | `ComponentRenderFn<HTMLProps, CollapsibleRootState> \| React.ReactElement`                   | —       | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

### TraceCollapsibleTrigger

| Prop            | Type                                                                                            | Default | Description                                                                                                                                                                               |
| --------------- | ----------------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `nativeButton?` | `boolean`                                                                                       | `true`  | 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>`).         |
| `className?`    | `string \| ((state: CollapsibleTriggerState) => string \| undefined)`                           | —       | CSS class applied to the element, or a function that returns a class based on the component's state.                                                                                      |
| `style?`        | `React.CSSProperties \| ((state: CollapsibleTriggerState) => React.CSSProperties \| undefined)` | —       | Style applied to the element, or a function that returns a style object based on the component's state.                                                                                   |
| `render?`       | `ComponentRenderFn<HTMLProps, CollapsibleTriggerState> \| React.ReactElement`                   | —       | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

### TraceCollapsibleContent

| Prop                | Type                                                     | Default | Description                                                                                                                                                                                             |
| ------------------- | -------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `hiddenUntilFound?` | `boolean`                                                | `false` | 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. |
| `keepMounted?`      | `boolean`                                                | `false` | Whether to keep the element in the DOM while the panel is hidden. This prop is ignored when `hiddenUntilFound` is used.                                                                                 |
| `className?`        | `string`                                                 | —       | CSS class applied to the element.                                                                                                                                                                       |
| `style?`            | `React.CSSProperties`                                    | —       | Style applied to the element.                                                                                                                                                                           |
| `render?`           | `ComponentRenderFn<HTMLProps, {}> \| React.ReactElement` | —       | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.               |
