Trace

Rows for agent steps — reasoning, tool calls, sources, and plans. Each line shares the same shape; wrap it in a collapsible, link, or overlay trigger to add behavior. Use Message for replies and Marker for notes between turns. Layout uses logical properties so nested borders and chevrons stay correct in RTL.

Basic

A TraceLine with an icon and title — plain text when nothing expands.

Installation

CLI

npx @sonojs/ui@latest add trace

Also needsnpx @sonojs/ui@latest add collapsible && npm i lucide-react

Composition

structure

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

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

Usage

trace.tsx

import { SearchIcon } from "lucide-react"

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

export function Example() {
  return (
    <Trace>
      <TraceLine>
        <TraceIcon>
          <SearchIcon />
        </TraceIcon>
        <TraceTitle>Searched for minimumReleaseAge</TraceTitle>
      </TraceLine>
    </Trace>
  )
}

Direction

Expand detail uses a start-edge border and start padding. The collapsible chevron is marked icon-dir so it mirrors in RTL.

direction.tsx

// Logical layout: start/end padding, border-s, ms/me, text-start.
// Chevron uses icon-dir so it flips correctly in RTL.
<Trace>
  <TraceCollapsible>
    <TraceCollapsibleTrigger>
      <TraceLine>…</TraceLine>
    </TraceCollapsibleTrigger>
    <TraceCollapsibleContent>Detail</TraceCollapsibleContent>
  </TraceCollapsible>
</Trace>

Props

Prop	Type	Default	Description
status	"running" · "error" · "pending"	—	On `TraceLine` — running shimmer, error color, or pending opacity. Omit when the step is done.
open	boolean	—	On `TraceCollapsible` — controlled open state (pair with `onOpenChange`).
defaultOpen	boolean	false	On `TraceCollapsible` — start expanded.
onOpenChange	(open: boolean) => void	—	On `TraceCollapsible` — called when open changes.