Epicenter
Local-first, open source apps
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
Install the required shadcn-svelte dependencies:
Copy and paste the following code into your project.
Usage
Use a Trace.Line for a single step:
<script lang="ts">
import * as Trace from "$lib/components/ui/trace/index.js";
</script><Trace.Root>
<Trace.Line>
<Trace.Icon>
<SearchIcon />
</Trace.Icon>
<Trace.Title>Searched for minimumReleaseAge</Trace.Title>
</Trace.Line>
</Trace.Root>Wrap the line in a Trace.Collapsible to show more detail when it expands:
<Trace.Root>
<Trace.Collapsible>
<Trace.CollapsibleTrigger>
<Trace.Line>
<Trace.Icon>
<TerminalIcon />
</Trace.Icon>
<Trace.Title>Ran node --version</Trace.Title>
</Trace.Line>
</Trace.CollapsibleTrigger>
<Trace.CollapsibleContent>v24.18.0</Trace.CollapsibleContent>
</Trace.Collapsible>
</Trace.Root>Composition
Use the following composition to build a trace line:
Trace.Root
└── Trace.Line
├── Trace.Icon
├── Trace.Title
├── Trace.Description
└── Trace.IconWrap the line in a Trace.Collapsible to show more detail when it expands:
Trace.Root
└── Trace.Collapsible
├── Trace.CollapsibleTrigger
│ └── Trace.Line
└── Trace.CollapsibleContentTrace.Line 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,errorandpendingstates, with a shimmer while running- Nested rows, so a summary expands into steps and a step into its output
- Keyboard and screen reader support from the trigger that wraps each row
- Customizable styling through the
classprop on every part
Trace Line
Use a Trace.Line on its own for a step with no detail to show. It reads as plain text.
Status
Set status on Trace.Line when a step is running, has failed or hasn't started yet.
Description
Put secondary text such as a diff stat, a duration or a count in a Trace.Description after the Trace.Title. It does not truncate.
Collapsible
Wrap the line in a Trace.Collapsible to show more detail when it expands. Put the Trace.Line inside Trace.CollapsibleTrigger and the detail in Trace.CollapsibleContent.
$ node --version
v24.18.0Open State
Rows start closed. Bind open on Trace.Collapsible to start open or to control a row.
$ node --version
v24.18.0$ pnpm --version
10.33.4To open a row while it streams and let the reader's click win, pass open ?? running.
<script lang="ts">
let open = $state<boolean>();
</script>
<Trace.Collapsible
open={open ?? running}
onOpenChange={(value) => (open = value)}
>
<Trace.CollapsibleTrigger>
<Trace.Line status={running ? "running" : undefined}>…</Trace.Line>
</Trace.CollapsibleTrigger>
<Trace.CollapsibleContent>{text}</Trace.CollapsibleContent>
</Trace.Collapsible>Link
Wrap the Trace.Line in an anchor. For a new tab, use an arrow-up-right icon and sr-only "(opens in a new tab)".
<a href="https://docs.astro.build" target="_blank" rel="noreferrer">
<Trace.Line>
<Trace.Title>
Install Astro
<span class="sr-only"> (opens in a new tab)</span>
</Trace.Title>
<Trace.Icon>
<ArrowUpRightIcon />
</Trace.Icon>
</Trace.Line>
</a>Dialog
Wrap the Trace.Line in the dialog's trigger. The dialog owns its open state, Escape and focus return.
<Dialog.Root>
<Dialog.Trigger>
<Trace.Line>
<Trace.Title>Searched the web for cache keys</Trace.Title>
<Trace.Icon>
<ChevronRightIcon />
</Trace.Icon>
</Trace.Line>
</Dialog.Trigger>
<Dialog.Content>…</Dialog.Content>
</Dialog.Root>Sheet
The same shape as the dialog. Drawer and Popover work the same way.
Group
Put rows that sit next to each other in a Trace.Root. It also styles any trigger or link that wraps a Trace.Line.
Sources
A collapsible row whose detail is a Trace.Root of link rows.
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.
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.
Whole Turn
Three levels: the turn, a summary, and the rows. Text between steps sits between two Trace.Root lists.
Reasoning
Render a reasoning part from the AI SDK. The row is a Trace.Line until the first text arrives. See Open State.
See Reasoning for more examples.
Tool
Render tool parts from the AI SDK. Map the tool part as in Tool.
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
Trace.Lineon its own is aspan. It is read as text and is not a tab stop. - Wrap it in a
Trace.CollapsibleTriggerand it becomes a button witharia-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. Trace.Iconis hidden from assistive tech, soTrace.Titleis the accessible name. Write it as a sentence that says what happened, like "Edited trace.svelte", not just "trace.svelte".- 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.
Trace.CollapsibleContentmutes its text. If you put a block with a muted background inside it, give the blocktext-foregroundso it keeps its contrast. Code Block sets its own text color.
API Reference
Trace.Root
A list of rows. It also styles any trigger or link that wraps a Trace.Line.
Trace.Line
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.
Trace.Icon
A decorative icon slot, hidden from assistive tech. Before the title it names the action; after it, it is the indicator.
Trace.Title
One sentence on one line. It truncates and shimmers while the line is running.
Trace.Description
Secondary text after the title, such as a count or a duration. It does not truncate.
Trace.Collapsible
A row that expands. It accepts the props of Collapsible.
Trace.CollapsibleTrigger
The button that opens and closes the row. Put a Trace.Line inside it. It adds a chevron after the line.
Trace.CollapsibleContent
The detail of a row that expands.