Trace
One row for an agent's reasoning, tool calls, sources, and plan.
$ pnpm install --frozen-lockfile
ERR_PNPM_OUTDATED_LOCKFILE Cannot install with "frozen-lockfile" because pnpm-lock.yaml is not up to date with package.jsonimport { Div } from "@implementjs/core";
import {
FilePenIcon,
FileTextIcon,
LoaderCircleIcon,
SearchIcon,
TerminalIcon,
} from "@implementjs/lucide";
import { CodeBlock, CodeBlockContent } from "@/lib/components/ui/code-block";
import {
Trace,
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceDescription,
TraceIcon,
TraceLine,
TraceTitle,
} from "@/lib/components/ui/trace";
export default function TraceDemo() {
return Div(
{ class: "w-full max-w-md" },
Trace(
TraceLine(
TraceIcon(SearchIcon()),
TraceTitle("Searched for frozen-lockfile"),
TraceDescription("3 results"),
),
TraceLine(TraceIcon(FileTextIcon()), TraceTitle("Read .github/workflows/ci.yml")),
TraceCollapsible(
TraceCollapsibleTrigger(
TraceLine(
{ status: "error" },
TraceIcon(TerminalIcon()),
TraceTitle("Failed to run pnpm install --frozen-lockfile"),
),
),
TraceCollapsibleContent(
CodeBlock(
{ size: "sm", variant: "destructive" },
CodeBlockContent(
{ wrap: true, class: "max-h-64" },
'$ pnpm install --frozen-lockfile\nERR_PNPM_OUTDATED_LOCKFILE Cannot install with "frozen-lockfile" because pnpm-lock.yaml is not up to date with package.json',
),
),
),
),
TraceLine(
TraceIcon(FilePenIcon()),
TraceTitle("Edited pnpm-lock.yaml"),
TraceDescription({ class: "font-mono" }, "+12 −4"),
),
TraceLine(
{ status: "running" },
TraceIcon(LoaderCircleIcon({ class: "animate-spin" })),
TraceTitle("Running pnpm install --frozen-lockfile"),
),
),
);
}Installation
npx jsrepo add @implementjs/ui/trace
It installs @implementjs/lucide for the chevron on an expanding row.
Copy the file below to src/lib/components/ui/trace.ts. It imports cn from @implementjs/cn. Then, on top of @implementjs/core and @implementjs/primitives:
npm install @implementjs/lucide
import {
Div,
Span,
type Bindable,
type Child,
type ComponentProps,
type ElementProps,
} from "@implementjs/core";
import { ChevronRightIcon } from "@implementjs/lucide";
import {
Collapsible as CollapsiblePrimitive,
CollapsibleContent as CollapsibleContentPrimitive,
CollapsibleTrigger as CollapsibleTriggerPrimitive,
createComponent,
} from "@implementjs/primitives";
import { cn } from "@implementjs/cn";
/**
* Where a step stands. Leave it unset for work that is done: the line reads
* as plain text.
*/
export type TraceStatus = "running" | "error" | "pending";
export type TraceProps = ElementProps<"div">;
export type TraceLineProps = ElementProps<"span"> & {
/**
* `running` shimmers the title, `error` turns the line destructive, and
* `pending` dims it. Pass a readable to move a step along as it runs.
*/
status?: Bindable<TraceStatus | undefined>;
};
export type TraceIconProps = ElementProps<"span">;
export type TraceTitleProps = ElementProps<"span">;
export type TraceDescriptionProps = ElementProps<"span">;
export type TraceCollapsibleProps = ComponentProps<typeof CollapsiblePrimitive>;
export type TraceCollapsibleTriggerProps = ComponentProps<typeof CollapsibleTriggerPrimitive>;
export type TraceCollapsibleContentProps = ComponentProps<typeof CollapsibleContentPrimitive>;
/**
* A list of steps: reasoning, tool calls, sources, the plan an agent is
* working through. Each step is a `TraceLine`, on its own or wrapped in
* whatever makes it do something — a `TraceCollapsible` to expand it, an `A`
* to link out, a dialog or popover trigger to open one.
*/
export const Trace = createComponent(function Trace(
{ class: className, ...props }: TraceProps,
...children: Child[]
) {
return Div(
{
...props,
"data-slot": "trace",
class: cn(
"flex w-full min-w-0 flex-col gap-2",
// a line wrapped in a link or a trigger: the wrapper takes the
// line's footprint, and the focus ring, so the line stays text
"*:has-[>[data-slot=trace-line]]:flex *:has-[>[data-slot=trace-line]]:w-fit *:has-[>[data-slot=trace-line]]:max-w-full *:has-[>[data-slot=trace-line]]:min-w-0 *:has-[>[data-slot=trace-line]]:rounded-md *:has-[>[data-slot=trace-line]]:text-left *:has-[>[data-slot=trace-line]]:outline-none *:has-[>[data-slot=trace-line]]:focus-visible:ring-[3px] *:has-[>[data-slot=trace-line]]:focus-visible:ring-ring/50",
className,
),
},
...children,
);
});
/** One step: an icon, a title, and optionally a description beside it. */
export const TraceLine = createComponent(function TraceLine(
{ class: className, status, ...props }: TraceLineProps,
...children: Child[]
) {
return Span(
{
...props,
"data-slot": "trace-line",
"data-status": status,
class: cn(
"flex w-fit max-w-full min-w-0 items-center gap-2 text-sm text-muted-foreground transition-colors",
"in-[a,button]:cursor-pointer in-[a:hover,button:hover]:text-foreground",
"data-[status=error]:text-destructive data-[status=error]:in-[a:hover,button:hover]:text-destructive",
"data-[status=pending]:opacity-60 data-[status=running]:*:data-[slot=trace-title]:shimmer",
className,
),
},
...children,
);
});
/** A 16px slot for an icon, before the title or after it. Hidden from screen readers. */
export const TraceIcon = createComponent(function TraceIcon(
{ class: className, ...props }: TraceIconProps,
...children: Child[]
) {
return Span(
{
"aria-hidden": "true",
...props,
"data-slot": "trace-icon",
class: cn(
"flex size-4 shrink-0 items-center justify-center [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4",
// an icon after the title sits a little closer to it
"[[data-slot=trace-title]~&]:-ml-1",
className,
),
},
...children,
);
});
/**
* What the step did, in one line. It truncates rather than wrapping, and
* shimmers while its line is `running`.
*/
export const TraceTitle = createComponent(function TraceTitle(
{ class: className, ...props }: TraceTitleProps,
...children: Child[]
) {
return Span(
{
...props,
"data-slot": "trace-title",
class: cn("min-w-0 truncate motion-reduce:shimmer-none", className),
},
...children,
);
});
/** A short aside after the title: a duration, a count, a file size. */
export const TraceDescription = createComponent(function TraceDescription(
{ class: className, ...props }: TraceDescriptionProps,
...children: Child[]
) {
return Span(
{
...props,
"data-slot": "trace-description",
class: cn("shrink-0 text-muted-foreground/70 tabular-nums", className),
},
...children,
);
});
/** A step that expands to show more: its output, its reasoning, the steps under it. */
export const TraceCollapsible = createComponent(function TraceCollapsible(
{ class: className, ...props }: TraceCollapsibleProps,
...children: Child[]
) {
return CollapsiblePrimitive(
{
...props,
"data-slot": "trace-collapsible",
class: cn("flex w-full min-w-0 flex-col", className),
},
...children,
);
});
/** Wraps the step's `TraceLine` and puts a chevron after it that turns as it opens. */
export const TraceCollapsibleTrigger = createComponent(function TraceCollapsibleTrigger(
{ class: className, type = "button", ...props }: TraceCollapsibleTriggerProps,
...children: Child[]
) {
return CollapsibleTriggerPrimitive(
{
type,
...props,
"data-slot": "trace-collapsible-trigger",
class: cn(
"group/trace-collapsible-trigger flex w-fit max-w-full min-w-0 cursor-pointer items-center gap-1 rounded-md text-left text-muted-foreground transition-colors outline-none hover:text-foreground focus-visible:ring-[3px] focus-visible:ring-ring/50 has-[[data-status=error]]:text-destructive",
className,
),
},
...children,
TraceIcon(
{
class: "transition-transform group-aria-expanded/trace-collapsible-trigger:rotate-90",
},
ChevronRightIcon(),
),
);
});
/**
* The detail under a step, indented behind a rule. `class` lands on an inner
* `Div`, so padding you add does not fight the height animation.
*/
export const TraceCollapsibleContent = createComponent(function TraceCollapsibleContent(
{ class: className, ...props }: TraceCollapsibleContentProps,
...children: Child[]
) {
return CollapsibleContentPrimitive(
{
...props,
"data-slot": "trace-collapsible-content",
class:
"min-w-0 overflow-hidden motion-reduce:animate-none data-[state=closed]:animate-collapsible-up data-[state=open]:animate-collapsible-down",
},
Div(
{
"data-slot": "trace-collapsible-content-inner",
class: cn(
"mt-2 mb-1 ml-[calc(--spacing(2)-1px)] min-w-0 border-l pr-1 pl-4 leading-relaxed wrap-break-word text-muted-foreground",
className,
),
},
...children,
),
);
});Then add the shimmer to your stylesheet.
Usage
A Trace is a list of TraceLines, and a line is an icon, a title, and optionally a description. That one row covers everything an agent shows while it works: a thought, a search, a command, a file it read or edited, a step in its plan.
import { Trace, TraceIcon, TraceLine, TraceTitle } from "@/lib/components/ui/trace";
Trace(TraceLine(TraceIcon(SearchIcon()), TraceTitle("Searched for minimumReleaseAge")));
TraceLine is always the line. To make it do something, wrap it in the thing that does it: a TraceCollapsible to expand it, an A to link out, a dialog, drawer, or popover trigger to open one. A wrapper that is a direct child of Trace takes the line's footprint and its focus ring, so the line inside it still reads as text.
Trace
├── TraceLine
│ ├── TraceIcon
│ ├── TraceTitle
│ └── TraceDescription
└── TraceCollapsible
├── TraceCollapsibleTrigger
│ └── TraceLine
└── TraceCollapsibleContent
Status
status says where a step stands. Leave it unset for work that is done.
import {
CircleAlertIcon,
CircleCheckIcon,
CircleIcon,
LoaderCircleIcon,
} from "@implementjs/lucide";
import { Trace, TraceIcon, TraceLine, TraceTitle } from "@/lib/components/ui/trace";
export default function TraceStatusDemo() {
return Trace(
{ class: "max-w-sm" },
TraceLine(TraceIcon(CircleCheckIcon()), TraceTitle("Ran pnpm install")),
TraceLine(
{ status: "error" },
TraceIcon(CircleAlertIcon()),
TraceTitle("Failed to run pnpm lint"),
),
TraceLine(
{ status: "running" },
TraceIcon(LoaderCircleIcon({ class: "animate-spin" })),
TraceTitle("Running pnpm build"),
),
TraceLine({ status: "pending" }, TraceIcon(CircleIcon()), TraceTitle("Run pnpm test")),
);
}| Status | Use for |
|---|---|
| none | Work that is done: "Ran pnpm install". |
"error" | Work that failed. Say so in the title: "Failed to run pnpm lint". |
"running" | Work in progress, in the present tense: "Running pnpm build". |
"pending" | Work that has not started, such as a step of a plan: "Run pnpm test". |
It takes a readable, so a step can move along as the work does without rebuilding the line:
const status = signal<TraceStatus | undefined>("running");
TraceLine({ status }, TraceIcon(TerminalIcon()), TraceTitle("pnpm build"));
// later
status.set(undefined);
Description
A TraceDescription after the title holds the aside: a duration, a count, a diff stat. It does not shrink, so a long title truncates before it does.
TraceLine(
TraceIcon(FilePenIcon()),
TraceTitle("Edited src/lib/components/settings/notification-preferences-form.ts"),
TraceDescription({ class: "font-mono" }, "+48 −12"),
);
Expanding a step
Wrap the line in a TraceCollapsibleTrigger, and put the detail in a TraceCollapsibleContent beside it. The trigger adds a chevron after the line that turns while the step is open. A small code block is the usual detail for a command:
TraceCollapsible(
TraceCollapsibleTrigger(TraceLine(TraceIcon(TerminalIcon()), TraceTitle("Ran node --version"))),
TraceCollapsibleContent(
CodeBlock({ size: "sm" }, CodeBlockContent({ wrap: true }, "$ node --version\nv24.18.0")),
),
);
Steps start closed. TraceCollapsible is the Collapsible primitive underneath, so open takes a signal to start one open or drive it from outside, and onOpenChange hears about every change. The content slides with the collapsible-down / collapsible-up keyframes from the introduction.
Steps nest: a TraceCollapsibleContent can hold another Trace, so a summary expands into its steps and a step into its output.
Shimmer
A running line's title shimmers: a highlight sweeps across the text, built on currentColor so it suits whatever color the line already is. It is a Tailwind utility rather than a class the component carries, so paste it into your stylesheet beside the rest. Without it, a running line just reads as plain text.
/* shimmer: a highlight that sweeps across text, for work in flight — the title
of a running trace line. Built on currentColor, so it takes on whatever
color the text already is. Ported from shadcn's `shadcn/tailwind.css`. */
@property --shimmer-image {
syntax: "*";
inherits: false;
}
@property --shimmer-text-fill {
syntax: "*";
inherits: false;
}
@theme inline {
@keyframes shimmer {
from {
background-position: 100% 0;
}
to {
background-position: 0 0;
}
}
}
@utility shimmer {
--_spread: var(--shimmer-spread, calc(3ch + 40px));
--_base: currentColor;
--_highlight: var(--shimmer-color, oklch(from currentColor l c h / calc(alpha* 0.2)));
background-image: var(
--shimmer-image,
linear-gradient(
110deg,
var(--_base) calc(50% - var(--_spread)),
color-mix(in oklch, var(--_highlight), var(--_base) 50%) calc(50% - var(--_spread) * 0.5),
var(--_highlight) 50%,
color-mix(in oklch, var(--_highlight), var(--_base) 50%) calc(50% + var(--_spread) * 0.5),
var(--_base) calc(50% + var(--_spread))
)
);
background-repeat: no-repeat;
background-size: calc(200% + var(--_spread) * 2) 100%;
background-position: 0 0;
background-clip: text;
-webkit-text-fill-color: var(--shimmer-text-fill, transparent);
animation: shimmer var(--shimmer-duration, 2s) linear infinite;
@variant dark {
--_highlight: var(
--shimmer-color,
oklch(from currentColor max(0.8, calc(l + 0.4)) c h / calc(alpha + 0.4))
);
}
&:where([dir="rtl"], [dir="rtl"] *) {
animation-direction: reverse;
}
}
/* Turns a shimmer off and leaves the text plain. */
@utility shimmer-none {
--shimmer-image: none;
--shimmer-text-fill: currentColor;
animation: none;
}
The shimmer stops for a reader who prefers reduced motion; the title still says what is happening.
Accessibility
TraceIconisaria-hidden. The title says what the step is, so the icon adds nothing a screen reader should read.- An expanding step is a real button with
aria-expandedandaria-controls, from the Collapsible primitive. - Say the status in the title as well as with it — "Failed to run pnpm lint", not just a red line — so it does not rest on color alone.
API Reference
Trace
A column of steps. A direct child that wraps a TraceLine — a link, a dialog trigger — takes the line's footprint and its focus ring, so the line inside stays text. Renders a Div; extra props are forwarded onto it.
TraceLine
One step: an icon, a title, and an optional description. It brightens on hover once it sits inside an A or a button. Renders a Span; extra props are forwarded onto it.
| Prop | Type | Default | Description |
|---|---|---|---|
status | Bindable<"running" | "error" | "pending" | undefined> | — | running shimmers the title, error turns the line destructive, pending dims it. Leave it unset for work that is done. Also set as data-status. |
TraceIcon
A 16px slot for an icon, before the title or after it. Sets aria-hidden, and sizes an svg inside it unless the svg has a size class of its own. Renders a Span; extra props are forwarded onto it.
TraceTitle
What the step did, on one line. Truncates rather than wrapping, and shimmers while its line is running — unless the reader prefers reduced motion. Renders a Span; extra props are forwarded onto it.
TraceDescription
A short aside after the title — a duration, a count, a diff stat. It does not shrink, so the title truncates first. Renders a Span; extra props are forwarded onto it.
TraceCollapsible
A step that expands. Every prop is the Collapsible primitive's, open and onOpenChange included. Renders a Div; extra props are forwarded onto it.
| Prop | Type | Default | Description |
|---|---|---|---|
open | Signal<boolean> | boolean | false | The open state. Pass a signal to control it from outside; a boolean seeds uncontrolled state. |
onOpenChange | (open: boolean) => void | — | Runs whenever the collapsible opens or closes. |
| Data attribute | Value |
|---|---|
[data-collapsible-root] | Present |
[data-state] | "open" | "closed" |
TraceCollapsibleTrigger
Wraps the step's TraceLine, and puts a chevron after it that turns while the step is open. Turns destructive when the line inside it has an error status. Renders a Button; extra props are forwarded onto it.
| Data attribute | Value |
|---|---|
[data-collapsible-trigger] | Present |
[data-state] | "open" | "closed" |
TraceCollapsibleContent
The detail under a step, indented behind a rule. class lands on an inner Div, so the animated element keeps the overflow and height classes it needs. The slide comes from the collapsible keyframes in your stylesheet. Renders a Div; extra props are forwarded onto it.
| Prop | Type | Default | Description |
|---|---|---|---|
hiddenUntilFound | boolean | false | Closed content uses hidden="until-found" so find-in-page can reveal it. |
| Data attribute | Value |
|---|---|
[data-collapsible-content] | Present |
[data-state] | "open" | "closed" |
| CSS variable | Description |
|---|---|
--ip-collapsible-content-height | The natural height of the content, for open/close animations. |
--ip-collapsible-content-width | The natural width of the content, for open/close animations. |