Trace

The Trace component lists the steps an assistant took to answer: searches, tool calls, reads, and plans. Each TraceLine has an icon, a one-line title, an optional description, and a status. Wrap a line in TraceCollapsible to let the reader expand its detail.

Usage

import {
  Trace,
  TraceCollapsible,
  TraceCollapsibleContent,
  TraceCollapsibleTrigger,
  TraceDescription,
  TraceIcon,
  TraceLine,
  TraceTitle,
} from '@epilot/spark-ui/trace'
import { Search } from '@epilot/spark-icons'

function AssistantSteps() {
  return (
    <Trace>
      <TraceLine>
        <TraceIcon>
          <Search />
        </TraceIcon>
        <TraceTitle>Searched contracts for Musterstraße 12</TraceTitle>
        <TraceDescription>1 result</TraceDescription>
      </TraceLine>
    </Trace>
  )
}

Use Trace for a sequence of steps that belong to one assistant turn. Use Marker for a single inline status or system note between messages, and Stepper for a process the user moves through.

Composition

Trace
└── TraceLine
    ├── TraceIcon
    ├── TraceTitle
    └── TraceDescription

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

Examples

Status

Set status on TraceLine. No status means the step is done. running adds the shimmer effect to the title, error switches to the error color, and pending dims the icon (the title keeps full contrast so it stays readable).

Write the title to match the status: present tense while running ("Checking the payment status"), past tense when done ("Loaded the March invoice"), and name the failure on error ("Could not reach the billing system").

Expandable steps

Wrap a TraceLine in TraceCollapsibleTrigger inside a TraceCollapsible to show the step's input or output on demand. The trigger adds a chevron that rotates when open. An error line inside a trigger keeps the error color on the chevron too.

TraceCollapsibleContent unmounts while closed. Pass keepMounted when the content holds its own state (a nested collapsible, a scroll position) that must survive closing.

Links and dialogs

TraceLine is a span, so it is never a tab stop by itself. To make a line open a page or a dialog, wrap it in an <a> or in the trigger of a Dialog, Sheet, or Popover. Trace gives any direct child that wraps a TraceLine a focus ring and a hover color.

<Trace>
  <a href="/invoices/2026-03">
    <TraceLine>
      <TraceIcon>
        <Receipt />
      </TraceIcon>
      <TraceTitle>Loaded the March invoice</TraceTitle>
    </TraceLine>
  </a>
</Trace>

Accessibility

• Decorative icons. TraceIcon is aria-hidden, so the title carries the meaning. Do not put information in the icon alone.
• Status in words. Color and shimmer are not announced. Put the outcome in the title ("Tariff lookup failed"), not only in status.
• Live updates. A trace that grows while the assistant works does not announce itself. Put role="status" or aria-live="polite" on a container if each new step must be announced, or announce only the final answer.
• Keyboard. TraceCollapsibleTrigger is a native button with aria-expanded; Enter and Space toggle it. Wrapped links and dialog triggers keep their own keyboard behavior.
• Reduced motion. The shimmer, the chevron rotation, and the height transition are turned off under prefers-reduced-motion.

API Reference

Trace

The list of steps.

TraceLine

One step.

TraceIcon

A 16px icon slot, hidden from assistive tech. Place a second TraceIcon after the title for a trailing icon.

TraceTitle

The step's one-line title. Truncates with an ellipsis when it overflows.

TraceDescription

Secondary text such as a count or a duration. Does not truncate and uses tabular numbers.

TraceCollapsible

Wraps the Base UI Collapsible.Root.

TraceCollapsibleTrigger

The button that toggles the step. Appends a chevron after its children.

TraceCollapsibleContent

The detail area, indented under the line with a left rule.