About
Groups an agent's repeated steps into one line per kind, showing what it is on right now and settling into a summary that opens to the full list.
Built with React and Tailwind. Copy the prompt and paste it into Claude Code, Cursor or Lovable: your agent adds Trace Group to your project and fits it to your theme.
Code
How Trace Group 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 { cn } from "@/lib/utils"
import { Collapsible } from "@base-ui/react/collapsible"
import { CheckIcon, ChevronDownIcon, Icon, IconNode, StepTimer, Trace, TraceConnector, TraceContext, TraceGroup, TraceStatus, TraceStatusGlyph, createIcon } from "@/components/ui/trace-group"
const reducedMotion = () => window.matchMedia("(prefers-reduced-motion: reduce)").matches
const SITES = ["react.dev/reference/react/Suspense", "nextjs.org/docs/app/loading-ui", "web.dev/articles/cls", "tallyline.app/changelog"]
/** The run as a timeline of ticks: sites, then files, then the edit, then a hold. */
const SEARCH_END = SITES.length
const FILES = [
"src/app/layout.tsx",
"src/app/runs/layout.tsx",
"src/app/runs/page.tsx",
"src/app/runs/loading.tsx",
"src/app/runs/[id]/page.tsx",
"src/lib/runs.ts",
"src/lib/projects.ts",
"src/components/runs-header.tsx",
]
const READ_END = SEARCH_END + FILES.length
const EDIT_END = READ_END + 1
const SITE_MS = 520
const FILE_MS = 300
const EDIT_MS = 1100
const HOLD_MS = 3200
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 iconNode: IconNode = [
["path", {"d":"M12 3a9 9 0 1 1-9 9"}],
]
const LoaderCircleIcon: Icon = /* @__PURE__ */ createIcon("loader-circle", iconNode)
const iconNode2: 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"}],
["path", {"d":"M10.75 6.25C12 7.5 12.5 9 12.5 10.75s-.5 3.25-1.75 4.5"}],
["path", {"d":"M10.75 6.25C9.5 7.5 9 9 9 10.75s.5 3.25 1.75 4.5"}],
["path", {"d":"M6.5 10.75H15"}],
]
const WebSearchIcon: Icon = /* @__PURE__ */ createIcon("web-search", iconNode2)
/* -------------------------------------------------------------------------------------------------
* TraceStep
* -----------------------------------------------------------------------------------------------*/
interface TraceStepProps extends Omit<React.ComponentProps<"li">, "title"> {
status: TraceStatus
/** What the step does, for example "Read". Set in medium weight. */
label?: React.ReactNode
/** Context in mono: a path, a query, a command. Truncates. */
detail?: React.ReactNode
/** Glyph at rest (done). Defaults to a check, or a dot in compact traces. */
icon?: React.ReactNode
/** Replaces the status text and timer at the end of the row. */
meta?: React.ReactNode
/** Final duration in ms, shown when done. */
durationMs?: number
/** Epoch ms when the step started. Drives the live timer while running. */
startedAt?: number
/** Retry attempt, shown as "Retry 2 of 3" while retrying. */
attempt?: { current: number; total?: number }
/** Retry a failed step. Shows Retry in place: under the step's content, or on the row itself. */
onRetry?: () => void
/** Expandable content. Without children the row is static, which keeps long traces light. */
children?: React.ReactNode
open?: boolean
defaultOpen?: boolean
onOpenChange?: (open: boolean) => void
}
const QUIET: TraceStatus[] = ["pending", "skipped", "cancelled", "denied"]
type ButtonVariant = "solid" | "outline" | "ghost" | "subtle"
type ButtonSize = "xs" | "sm" | "md" | "lg" | "icon-xs" | "icon-sm" | "icon-md" | "icon-lg"
interface ButtonProps extends React.ComponentProps<"button"> {
variant?: ButtonVariant
size?: ButtonSize
}
const base = cn(
"chatcn-focus inline-flex shrink-0 items-center justify-center gap-1.5 font-medium whitespace-nowrap select-none",
"ease-(--chatcn-ease-standard) transition-[background-color,color,box-shadow,scale] duration-150",
"active:scale-(--chatcn-press-scale) active:duration-100 disabled:pointer-events-none disabled:opacity-50",
"[&_svg]:pointer-events-none [&_svg]:shrink-0",
)
const variants: Record<ButtonVariant, string> = {
solid: "bg-(color:--chatcn-primary) text-(color:--chatcn-primary-fg) hover:bg-(color:--chatcn-primary-hover)",
outline: "bg-(color:--chatcn-card) text-(color:--chatcn-fg) shadow-(--chatcn-shadow-xs) hover:bg-(color:--chatcn-fill-hover)",
ghost: "text-(color:--chatcn-fg-muted) hover:bg-(color:--chatcn-fill-hover) hover:text-(color:--chatcn-fg)",
subtle: "bg-(color:--chatcn-fill) text-(color:--chatcn-fg) hover:bg-(color:--chatcn-fill-hover)",
}
// Heights follow the control scale: 24, 28, 32, 36. Radii stay concentric inside 12 px surfaces.
const sizes: Record<ButtonSize, string> = {
xs: "h-6 rounded-(--chatcn-radius-sm) px-2 text-[0.75rem]/[1rem] [&_svg]:size-3.5",
sm: "h-7 rounded-(--chatcn-radius-sm) px-2.5 text-[0.8125rem]/[1.25rem] [&_svg]:size-3.5",
md: "h-8 rounded-(--chatcn-radius-md) px-3 text-[0.875rem]/[1.25rem] tracking-[-0.003em] [&_svg]:size-4",
lg: "h-9 rounded-(--chatcn-radius-md) px-3.5 text-[0.875rem]/[1.25rem] tracking-[-0.003em] [&_svg]:size-4",
"icon-xs": "size-6 rounded-(--chatcn-radius-sm) active:scale-(--chatcn-press-scale-icon) [&_svg]:size-3.5",
"icon-sm": "size-7 rounded-(--chatcn-radius-sm) active:scale-(--chatcn-press-scale-icon) [&_svg]:size-3.5",
"icon-md": "size-8 rounded-(--chatcn-radius-md) active:scale-(--chatcn-press-scale-icon) [&_svg]:size-4",
"icon-lg": "size-9 rounded-(--chatcn-radius-md) active:scale-(--chatcn-press-scale-icon) [&_svg]:size-4",
}
/** Class names for anything that should look like a button, such as a link. */
function buttonVariants({
variant = "ghost",
size = "md",
}: {
variant?: ButtonVariant
size?: ButtonSize
} = {}) {
return cn(base, variants[variant], sizes[size])
}
function Button({
variant = "ghost",
size = "md",
type = "button",
className,
...props
}: ButtonProps) {
return (
<button
type={type}
data-slot="button"
data-variant={variant}
className={cn(buttonVariants({ variant, size }), className)}
{...props}
/>
)
}
const iconNode3: IconNode = [
["path", {"d":"M5.49 17.46A8.5 8.5 0 1 0 6.54 5.49"}],
["path", {"d":"m8.21 8.65-2.94-.26a2 2 0 0 1-1.82-2.16l.26-2.94"}],
]
const RotateCcwIcon: Icon = /* @__PURE__ */ createIcon("rotate-ccw", iconNode3)
const STATUS_TEXT: Record<TraceStatus, string> = {
pending: "Pending",
running: "Running",
done: "Done",
error: "Failed",
"approval-requested": "Needs approval",
"approval-responded": "Approved",
denied: "Denied",
cancelled: "Cancelled",
retrying: "Retrying",
skipped: "Skipped",
}
function TraceStepMeta({
status,
meta,
durationMs,
startedAt,
attempt,
}: Pick<TraceStepProps, "status" | "meta" | "durationMs" | "startedAt" | "attempt">) {
const { density } = React.useContext(TraceContext)
if (meta !== undefined)
return <span className="text-[0.75rem]/[1rem] text-(color:--chatcn-fg-subtle)">{meta}</span>
if (status === "running" || status === "approval-responded" || status === "done") {
// One StepTimer across running and done, so it can measure the step when no duration is given.
const label = status === "approval-responded" ? "Approved" : "Running"
return (
<StepTimer
running={status !== "done"}
startedAt={startedAt}
durationMs={durationMs}
// Compact rows are usually quick reads: no label flashing for a few hundred ms.
placeholder={density === "compact" ? null : label}
/>
)
}
if (status === "pending") return null
let text = STATUS_TEXT[status]
if (status === "retrying" && attempt) {
text = attempt.total
? `Retry ${attempt.current} of ${attempt.total}`
: `Retry ${attempt.current}`
}
return (
<span
className={cn(
"text-[0.75rem]/[1rem] tabular-nums",
status === "error" ? "text-(color:--chatcn-red)" : "text-(color:--chatcn-fg-subtle)",
)}
>
{text}
</span>
)
}
const rowBase = cn(
"flex h-(--trace-row) w-full min-w-0 items-center gap-2.5 px-2 text-start",
"rounded-(--chatcn-radius-md) select-none",
)
/**
* One agent step on the rail: status glyph, label, mono detail, duration. Steps with children
* expand to show them; the rest render as plain rows with no disclosure machinery.
*/
function TraceStep({
status,
label,
detail,
icon,
meta,
durationMs,
startedAt,
attempt,
onRetry,
children,
open,
defaultOpen,
onOpenChange,
className,
...props
}: TraceStepProps) {
const { density } = React.useContext(TraceContext)
const quiet = QUIET.includes(status)
const hasContent = children !== undefined && children !== null && children !== false
// The panel opens by the status it mounts with (an error opens it); later status changes do not
// fight an uncontrolled panel. It mounts again whenever content returns.
const initialOpen = React.useRef<boolean | undefined>(undefined)
if (!hasContent) initialOpen.current = undefined
else if (initialOpen.current === undefined)
initialOpen.current = defaultOpen ?? (status === "error" || status === "approval-requested")
const retry =
status === "error" && onRetry ? (
<Button
size="xs"
onClick={onRetry}
className="relative pointer-coarse:after:absolute pointer-coarse:after:-inset-2.5 pointer-coarse:after:content-['']"
>
<RotateCcwIcon aria-hidden="true" />
Retry
</Button>
) : null
const body = (
<>
<TraceStatusGlyph status={status} icon={icon} />
<span className="flex min-w-0 flex-1 items-baseline gap-2">
<span className="sr-only">{STATUS_TEXT[status]}: </span>
{label ? (
<span
className={cn(
"shrink-0",
density === "compact" ? "font-normal" : "font-medium",
quiet ? "text-(color:--chatcn-fg-subtle)" : "text-(color:--chatcn-fg)",
)}
>
{label}
</span>
) : null}
{detail ? (
<span
className={cn(
"truncate font-mono",
label
? "text-[0.75rem]/[1rem] text-(color:--chatcn-fg-subtle)"
: "text-[0.75rem]/[1rem] text-(color:--chatcn-fg-muted)",
quiet && "text-(color:--chatcn-fg-subtle)",
)}
>
{detail}
</span>
) : null}
</span>
<span className="shrink-0">
<TraceStepMeta
status={status}
meta={meta}
durationMs={durationMs}
startedAt={startedAt}
attempt={attempt}
/>
</span>
</>
)
return (
<li
data-slot="trace-step"
data-trace-status={status}
className={cn("group/trace-item relative min-w-0", className)}
{...props}
>
<TraceConnector />
{hasContent ? (
<Collapsible.Root
open={open}
defaultOpen={initialOpen.current}
onOpenChange={onOpenChange}
render={<div />}
className="group/trace-step"
>
<Collapsible.Trigger
className={cn(
rowBase,
"ease-(--chatcn-ease-standard) transition-colors duration-150 outline-none",
"hover:bg-(color:--chatcn-fill-hover) focus-visible:outline-(color:--chatcn-accent) focus-visible:outline-2 focus-visible:-outline-offset-2",
)}
>
{body}
<ChevronDownIcon
aria-hidden="true"
data-trace-chevron=""
className={cn(
"text-(color:--chatcn-fg-subtle) ease-(--chatcn-ease-out) size-4 shrink-0 transition-[rotate,opacity] duration-200",
"group-data-[open]/trace-step:rotate-180 motion-reduce:transition-none",
// The chevron appears on hover so a long trace is not a column of arrows.
"opacity-0 group-focus-within/trace-step:opacity-100 group-hover/trace-step:opacity-100",
"group-data-[open]/trace-step:opacity-100 pointer-coarse:opacity-100",
)}
/>
</Collapsible.Trigger>
<Collapsible.Panel
className={cn(
"h-(--collapsible-panel-height) overflow-hidden",
"ease-(--chatcn-ease-out) transition-[height,opacity] duration-200 motion-reduce:transition-none",
"data-[ending-style]:h-0 data-[ending-style]:opacity-0 data-[ending-style]:duration-150",
"data-[starting-style]:h-0 data-[starting-style]:opacity-0",
)}
>
<div
data-slot="trace-step-content"
className="border-(color:--chatcn-border) text-[0.8125rem]/[1.25rem] text-(color:--chatcn-fg-muted) ms-[15.5px] mt-1 mb-2 border-s ps-[17.5px] pt-0.5"
>
{children}
{retry ? <div className="-ms-2 mt-1.5 flex">{retry}</div> : null}
</div>
</Collapsible.Panel>
</Collapsible.Root>
) : (
<div className={rowBase}>
{body}
{retry ? <span className="-my-1 -me-1 shrink-0">{retry}</span> : null}
{/* Holds the chevron's slot when any row in the trace has one, so durations line up. */}
<span
aria-hidden="true"
className="hidden size-4 shrink-0 group-has-[[data-trace-chevron]]/trace:block"
/>
</div>
)}
</li>
)
}
const iconNode4: 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", iconNode4)
const iconNode5: 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", iconNode5)
/** 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>
)
}
/**
* Agent steps folded into one line per kind: "Searched 4 sites", "Read 8 files". While a group
* runs, its line shows what the agent is on right now; once done it settles into a summary that
* opens to the full list. Loops.
*/
export default function TraceGroupPreview() {
// The tick and when each phase started change together, so a timer never starts from zero.
const [run, setRun] = React.useState({ tick: 0, search: 0, read: 0, edit: 0 })
const tick = run.tick
React.useEffect(() => {
if (reducedMotion()) {
setRun({ tick: EDIT_END, search: 0, read: 0, edit: 0 })
return
}
setRun({ tick: 0, search: Date.now(), read: 0, edit: 0 })
}, [])
React.useEffect(() => {
if (run.search === 0) return
const t = run.tick
const ms = t < SEARCH_END ? SITE_MS : t < READ_END ? FILE_MS : t < EDIT_END ? EDIT_MS : HOLD_MS
const id = window.setTimeout(() => {
const now = Date.now()
setRun((r) => {
if (r.tick >= EDIT_END) return { tick: 0, search: now, read: 0, edit: 0 }
const next = r.tick + 1
return {
...r,
tick: next,
read: next === SEARCH_END ? now : r.read,
edit: next === READ_END ? now : r.edit,
}
})
}, ms)
return () => window.clearTimeout(id)
}, [run])
const started = run
const searching = tick < SEARCH_END
const reading = tick >= SEARCH_END && tick < READ_END
const editing = tick === READ_END
const finished = tick >= EDIT_END
const filesRead = Math.min(FILES.length, Math.max(0, tick - SEARCH_END + 1))
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">Why does the runs page flash blank?</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">
{finished ? (
<CheckIcon className="text-(color:--chatcn-fg) size-3.5" aria-hidden="true" />
) : (
<LoaderCircleIcon className="size-3.5 animate-spin" aria-hidden="true" />
)}
{finished ? "Done" : "Working"}
</span>
</div>
{/* Fixed height: the read group opens once it lands, so the frame never rescales. */}
<div className="h-[20.5rem]">
<Trace className="w-full">
<TraceGroup
status={searching ? "running" : "done"}
title={`Searched ${SITES.length} sites`}
activeTitle="Searching the web"
current={searching ? SITES[tick] : undefined}
summary="4 results"
icon={<WebSearchIcon />}
startedAt={searching ? started.search : undefined}
durationMs={searching ? undefined : SITES.length * SITE_MS}
>
{SITES.map((site) => (
<TraceStep key={site} status="done" detail={site} />
))}
</TraceGroup>
{tick >= SEARCH_END ? (
<TraceGroup
status={reading ? "running" : "done"}
title={`Read ${FILES.length} files`}
activeTitle={`Reading ${filesRead} ${filesRead === 1 ? "file" : "files"}`}
current={reading ? FILES[tick - SEARCH_END] : undefined}
summary="612 lines"
icon={<FileTextIcon />}
startedAt={reading ? started.read : undefined}
durationMs={reading ? undefined : FILES.length * FILE_MS}
open={!reading}
maxHeight="16rem"
>
{FILES.map((path) => (
<TraceStep key={path} status="done" detail={path} />
))}
</TraceGroup>
) : null}
{tick >= READ_END ? (
<TraceStep
status={editing ? "running" : "done"}
label={editing ? "Editing" : "Edited"}
detail="src/app/runs/layout.tsx"
icon={<FilePenIcon />}
startedAt={editing ? started.edit : undefined}
durationMs={editing ? undefined : EDIT_MS}
/>
) : null}
</Trace>
</div>
</div>
<MoreOn slug="trace-group">Agent steps that fold into one line per kind when done. On</MoreOn>
</div>
</FitFrame>
)
}
















