About
A live agent trace: steps arrive with spinners and ticking timers, land with final times, retry when they fail and open to show detail.
Built with React and Tailwind. Copy the prompt and paste it into Claude Code, Cursor or Lovable: your agent adds Trace to your project and fits it to your theme.
Code
How Trace is used: the demo's code. The component's own source comes with a free account.
Usage.tsx
"use client"
import * as React from "react"
import { CheckIcon, Icon, IconNode, Trace, TraceStatus, TraceStep, createIcon } from "@/components/ui/trace"
type Phase = "running" | "error" | "retrying"
const reducedMotion = () => window.matchMedia("(prefers-reduced-motion: reduce)").matches
interface Step {
key: string
label: string
/** The label while the step runs. */
active: string
detail: string
icon: React.ReactNode
/** How long the step runs in the demo; its final time is the time you watched. */
ms: number
/** A step that fails once, then retries and lands. */
flaky?: boolean
content?: React.ReactNode
}
const iconNode: IconNode = [
["path", {"d":"M10.38 4.94a3.25 3.25 0 0 0-4.44 4.44L5 9.97a3.5 3.5 0 0 0 .55 6.32l1.12.27a2.75 2.75 0 0 0 3.29 3.6"}],
["path", {"d":"M13.62 4.94a3.25 3.25 0 0 1 4.44 4.44l.94.59a3.5 3.5 0 0 1-.55 6.32l-1.12.27a2.75 2.75 0 0 1-3.29 3.6"}],
["path", {"d":"M12 4.75V20.5"}],
]
const BrainIcon: Icon = /* @__PURE__ */ createIcon("brain", iconNode)
const iconNode2: IconNode = [
["path", {"d":"M7 2.5h5.88a1.5 1.5 0 0 1 1.06.44l5.12 5.12a1.5 1.5 0 0 1 .44 1.06V19a2.5 2.5 0 0 1-2.5 2.5H7A2.5 2.5 0 0 1 4.5 19V5A2.5 2.5 0 0 1 7 2.5"}],
["path", {"d":"M13.5 3.25v3.5a1.75 1.75 0 0 0 1.75 1.75h3.5"}],
["path", {"d":"M8.25 12.5h7.5"}],
["path", {"d":"M8.25 16.5h7.5"}],
["path", {"d":"M8.25 8.5H10"}],
]
const FileTextIcon: Icon = /* @__PURE__ */ createIcon("file-text", iconNode2)
const iconNode3: IconNode = [
["path", {"d":"M4 10.75a6.75 6.75 0 1 0 13.5 0 6.75 6.75 0 1 0-13.5 0"}],
["path", {"d":"m15.75 15.75 4.5 4.5"}],
]
const SearchIcon: Icon = /* @__PURE__ */ createIcon("search", iconNode3)
const iconNode4: IconNode = [
["path", {"d":"M3 12a9 9 0 1 0 18 0 9 9 0 1 0-18 0"}],
["path", {"d":"M12.72 3.8a11.9 11.9 0 0 1 0 16.4 1 1 0 0 1-1.44 0 11.9 11.9 0 0 1 0-16.4 1 1 0 0 1 1.44 0"}],
["path", {"d":"M3 12h2.25"}],
["path", {"d":"M10.75 12h2.5"}],
["path", {"d":"M18.75 12H21"}],
]
const GlobeIcon: Icon = /* @__PURE__ */ createIcon("globe", iconNode4)
const iconNode5: IconNode = [
["path", {"d":"m3 6.5 1.04 1.04a1 1 0 0 0 1.42 0L8.5 4.5"}],
["path", {"d":"m3 17.5 1.04 1.04a1 1 0 0 0 1.42 0L8.5 15.5"}],
["path", {"d":"M12.5 6h8"}],
["path", {"d":"M12.5 12h8"}],
["path", {"d":"M12.5 18h8"}],
]
const ListChecksIcon: Icon = /* @__PURE__ */ createIcon("list-checks", iconNode5)
const iconNode6: IconNode = [
["path", {"d":"M4.5 12.75V5A2.5 2.5 0 0 1 7 2.5h5.88a1.5 1.5 0 0 1 1.06.44l5.12 5.12a1.5 1.5 0 0 1 .44 1.06V19a2.5 2.5 0 0 1-2.5 2.5H8.46"}],
["path", {"d":"M13.5 3.25v3.5a1.75 1.75 0 0 0 1.75 1.75h3.5"}],
["path", {"d":"m4.04 18.63.87-2.6a1.5 1.5 0 0 1 .36-.58l2.93-2.94a2.5 2.5 0 0 1 3.54 0 2.5 2.5 0 0 1 0 3.54L8.8 18.98a1.5 1.5 0 0 1-.58.36l-2.6.87a1.25 1.25 0 0 1-1.58-1.58"}],
]
const FilePenIcon: Icon = /* @__PURE__ */ createIcon("file-pen", iconNode6)
const iconNode7: IconNode = [
["path", {"d":"m4.5 6 4.09 4.09a2 2 0 0 1 0 2.82L4.5 17"}],
["path", {"d":"M12.5 18h7"}],
]
const TerminalIcon: Icon = /* @__PURE__ */ createIcon("terminal", iconNode7)
/** An agent tracking down a blank page, step by step. */
const STEPS: Step[] = [
{ key: "think", label: "Thought", active: "Thinking", detail: "Why the page paints late", icon: <BrainIcon />, ms: 1300 },
{ key: "read", label: "Read", active: "Reading", detail: "src/app/runs/layout.tsx", icon: <FileTextIcon />, ms: 500 },
{ key: "search", label: "Searched", active: "Searching", detail: "getProjects", icon: <SearchIcon />, ms: 700 },
{ key: "fetch", label: "Fetched", active: "Fetching", detail: "localhost:3000/api/projects", icon: <GlobeIcon />, ms: 900, flaky: true },
{
key: "plan",
label: "Planned",
active: "Planning",
detail: "3 changes",
icon: <ListChecksIcon />,
ms: 900,
content: (
<ol className="flex list-decimal flex-col gap-0.5 ps-4">
<li>Stop awaiting getProjects() in the runs layout.</li>
<li>Wrap the header in its own Suspense boundary.</li>
<li>Give the header skeleton its final height.</li>
</ol>
),
},
{ key: "edit", label: "Edited", active: "Editing", detail: "src/app/runs/layout.tsx", icon: <FilePenIcon />, ms: 700 },
{ key: "test", label: "Ran", active: "Running", detail: "pnpm test runs", icon: <TerminalIcon />, ms: 1300 },
]
const HOLD_MS = 3400
const FAIL_MS = 1100
const RETRY_MS = 900
const FIT_CSS = "html,body{overflow:hidden}[data-fit-small] [data-fit-hide]{display:none!important}"
/**
* 21st shows a demo in a small frame: about 674 by 421 on a component page, 358 by 224 on a
* phone and 245 by 139 on a profile card. A demo taller than its frame gets scrollbars, which
* render white on dark pages. FitFrame fills the frame exactly instead.
*
* - "scale": the content shrinks until it fits, centered. For visuals such as orbs.
* - "crop": the content stays at full size from the top and fades out at the bottom. For text
* that streams in, where a changing scale would make the page breathe.
*
* `minWidth` lays out a wide demo (a table, a two column panel) at that width and scales it down
* to the frame, instead of letting it collapse to a narrow layout. The frame centers it, so it
* shrinks evenly on both sides.
*
* Anything marked `data-fit-hide` (state buttons, the chatcn.dev line) drops out in frames
* shorter than `hideBelow`, so a profile card shows the visual alone.
*/
function FitFrame({
children,
mode = "scale",
hideBelow = 360,
minWidth,
}: {
children: React.ReactNode
mode?: "scale" | "crop"
hideBelow?: number
minWidth?: string
}) {
const content = React.useRef<HTMLDivElement>(null)
const [cropped, setCropped] = React.useState(false)
React.useLayoutEffect(() => {
const el = content.current
if (!el) return
const measure = () => {
const vw = window.innerWidth
const vh = window.innerHeight
el.toggleAttribute("data-fit-small", vh < hideBelow)
// Layout sizes ignore the transform, so measuring never feeds back.
const w = Math.max(el.offsetWidth, el.scrollWidth)
const h = Math.max(el.offsetHeight, el.scrollHeight)
const scale = mode === "scale" ? Math.min(1, vw / w, vh / h) : 1
el.style.transform = scale < 1 ? `scale(${scale})` : ""
setCropped(mode === "crop" && h > vh + 1)
}
measure()
const observer = new ResizeObserver(measure)
observer.observe(el)
// Content that changes inside a fixed width box (a headline that cycles words) never resizes
// the box itself, so changes below it measure again on the next frame.
let frame = 0
const mutations = new MutationObserver(() => {
cancelAnimationFrame(frame)
frame = requestAnimationFrame(measure)
})
mutations.observe(el, { subtree: true, childList: true, characterData: true })
window.addEventListener("resize", measure)
return () => {
observer.disconnect()
mutations.disconnect()
cancelAnimationFrame(frame)
window.removeEventListener("resize", measure)
}
}, [mode, hideBelow])
const fade = "linear-gradient(to bottom, #000 calc(100% - 40px), transparent)"
return (
<div
className="flex w-full justify-center overflow-hidden"
style={{
height: "100dvh",
alignItems: mode === "crop" ? "flex-start" : "center",
maskImage: cropped ? fade : undefined,
WebkitMaskImage: cropped ? fade : undefined,
}}
>
<style>{FIT_CSS}</style>
<div
ref={content}
className="w-full shrink-0"
style={{ transformOrigin: mode === "crop" ? "top center" : "center", minWidth }}
>
{children}
</div>
</div>
)
}
const iconNode8: IconNode = [
["path", {"d":"M12 3a9 9 0 1 1-9 9"}],
]
const LoaderCircleIcon: Icon = /* @__PURE__ */ createIcon("loader-circle", iconNode8)
/** The line under each 21st demo that points back to the kit. */
function MoreOn({ slug, children }: { slug: string; children: React.ReactNode }) {
return (
<p data-fit-hide className="text-[0.75rem]/[1rem] text-(color:--chatcn-fg-faint) text-center text-balance">
{children}{" "}
<a
href={`https://chatcn.dev/docs/components/${slug}`}
target="_blank"
rel="noopener"
className="text-(color:--chatcn-fg-subtle) hover:text-(color:--chatcn-fg) underline underline-offset-2"
>
chatcn.dev
</a>
</p>
)
}
/**
* A live agent trace: steps arrive one at a time with a spinner and a ticking timer, then land
* with their final time. A fetch fails, retries and lands, and the plan step opens to show its
* changes. Loops.
*/
export default function TracePreview() {
// `step` is the running step; STEPS.length means the run is done.
const [run, setRun] = React.useState<{ step: number; phase: Phase; startedAt: number }>({
step: 0,
phase: "running",
startedAt: 0,
})
const [times, setTimes] = React.useState<number[]>([])
React.useEffect(() => {
if (reducedMotion()) {
setRun({ step: STEPS.length, phase: "running", startedAt: 0 })
setTimes(STEPS.map((s) => s.ms))
return
}
setRun({ step: 0, phase: "running", startedAt: Date.now() })
}, [])
React.useEffect(() => {
if (run.startedAt === 0) return
const finished = run.step >= STEPS.length
const step = STEPS[run.step]
const ms = finished ? HOLD_MS : run.phase === "error" ? FAIL_MS : run.phase === "retrying" ? RETRY_MS : step!.ms
const id = window.setTimeout(() => {
if (finished) {
setTimes([])
setRun({ step: 0, phase: "running", startedAt: Date.now() })
} else if (step!.flaky && run.phase === "running") {
setRun({ step: run.step, phase: "error", startedAt: run.startedAt })
} else if (run.phase === "error") {
setRun({ step: run.step, phase: "retrying", startedAt: Date.now() })
} else {
setTimes((t) => [...t, Date.now() - run.startedAt])
setRun({ step: run.step + 1, phase: "running", startedAt: Date.now() })
}
}, ms)
return () => window.clearTimeout(id)
}, [run])
const finished = run.step >= STEPS.length
const total = times.reduce((a, b) => a + b, 0)
return (
<FitFrame minWidth="36rem">
<div className="flex w-full flex-col items-center justify-center gap-4 p-6">
<div className="rounded-(--chatcn-radius-lg) bg-(color:--chatcn-card) shadow-(--chatcn-shadow-sm) flex w-full max-w-xl flex-col gap-3 p-5">
<div className="flex items-center gap-3">
<div className="min-w-0 flex-1">
<p className="text-[0.875rem]/[1.25rem] tracking-[-0.003em] text-(color:--chatcn-fg) truncate font-medium">Fix the blank runs page</p>
<p className="text-[0.75rem]/[1rem] text-(color:--chatcn-fg-subtle) truncate font-mono">tallyline/web on main</p>
</div>
<span className="bg-(color:--chatcn-fill) text-[0.75rem]/[1rem] text-(color:--chatcn-fg-muted) inline-flex items-center gap-1.5 rounded-full px-2 py-0.5 font-medium tabular-nums">
{finished ? (
<>
<CheckIcon className="text-(color:--chatcn-fg) size-3.5" aria-hidden="true" />
Done in {(total / 1000).toFixed(1)} s
</>
) : (
<>
<LoaderCircleIcon className="size-3.5 animate-spin" aria-hidden="true" />
Working
</>
)}
</span>
</div>
{/* Fixed height, so the frame never rescales as steps arrive. */}
<div className="h-[18.75rem]">
<Trace className="w-full">
{STEPS.slice(0, Math.min(run.step + 1, STEPS.length)).map((step, i) => {
const done = i < run.step
const status: TraceStatus = done
? "done"
: run.phase === "error"
? "error"
: run.phase === "retrying"
? "retrying"
: "running"
return (
<TraceStep
key={step.key}
status={status}
label={done ? step.label : status === "error" ? "Fetch" : step.active}
detail={step.detail}
icon={step.icon}
durationMs={done ? times[i] : undefined}
startedAt={done || status === "error" ? undefined : run.startedAt}
attempt={status === "retrying" ? { current: 2, total: 3 } : undefined}
open={step.content ? done : undefined}
>
{step.content ?? (step.flaky && status === "error" ? (
<p className="text-(color:--chatcn-fg)">Connection refused. Starting the dev server, then trying again.</p>
) : undefined)}
</TraceStep>
)
})}
</Trace>
</div>
</div>
<MoreOn slug="trace">An agent's steps as a live trace, with timings and retries. On</MoreOn>
</div>
</FitFrame>
)
}
















