implement
Trace

Trace

One row for an agent's reasoning, tool calls, sources, and plan.

Searched for frozen-lockfile3 resultsRead .github/workflows/ci.yml
Edited pnpm-lock.yaml+12 −4Running pnpm install --frozen-lockfile
import { 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.

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.

Ran pnpm installFailed to run pnpm lintRunning pnpm buildRun pnpm test
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")),
	);
}
StatusUse for
noneWork 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

  • TraceIcon is aria-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-expanded and aria-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.

PropTypeDefaultDescription
statusBindable<"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.

PropTypeDefaultDescription
openSignal<boolean> | booleanfalseThe 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 attributeValue
[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 attributeValue
[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.

PropTypeDefaultDescription
hiddenUntilFoundbooleanfalseClosed content uses hidden="until-found" so find-in-page can reveal it.
Data attributeValue
[data-collapsible-content]Present
[data-state]"open" | "closed"
CSS variableDescription
--ip-collapsible-content-heightThe natural height of the content, for open/close animations.
--ip-collapsible-content-widthThe natural width of the content, for open/close animations.