- Accordion
- Attachment
- Avatar
- Badge
- Breadcrumb
- Button
- Button Group
- Card
- Checkbox
- Code Block
- Collapsible
- Dialog
- Dropdown Menu
- Empty
- Field
- Hover Card
- Input
- Input Group
- Input OTP
- Item
- Label
- Marker
- Message
- Number Flow
- Pagination
- Popover
- Progress
- Radio Group
- Select
- Slider
- Sonner
- Spinner
- Switch
- Tooltip
- Separator
- Sheet
- Tabs
- Textarea
- Toggle
- Toggle Group
- Trace
Trace
The primitive for rendering collapsible agent trace lines with icons, titles, and status.
10.18.0 package.json | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)ERR_PNPM_OUTDATED_LOCKFILE Cannot install with "frozen-lockfile" because pnpm-lock.yaml is not up to date with package.jsonThe last commit bumped a version in package.json without updating pnpm-lock.yaml, so the frozen install fails. Run pnpm install locally and commit the lockfile.
"use client";
import { ChevronRightIcon } from "lucide-react";
import * as React from "react";
import {
Collapsible,
CollapsibleContent,
CollapsibleTrigger,
} from "@/components/ui/collapsible";
import { Shimmer } from "@/components/ui/shimmer";
import { cn } from "@/lib/utils";
const defaultTraceMotion = "450 cubic-bezier(0.32, 0.72, 0, 1)";
interface TraceCollapsibleContextValue {
motion: string;
open: boolean;
}
const TraceCollapsibleContext =
React.createContext<TraceCollapsibleContextValue>({
motion: defaultTraceMotion,
open: false,
});
const TraceLineContext = React.createContext<{
status?: "running" | "error" | "pending";
}>({});
function resolveTraceMotion(
motion: string | undefined,
animation: false | string | undefined,
fallback: string
): string {
if (motion !== undefined) {
return motion;
}
if (animation === false) {
return "off";
}
if (typeof animation === "string") {
if (/^(spring|inertia|keyframes)/u.test(animation)) {
console.warn(
`[trace] animation="${animation}" uses a motion DSL that is not supported in CSS. Falling back to default. Prefer motion="150 ease-out" instead.`
);
return fallback;
}
return animation;
}
return fallback;
}
function Trace({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn("flex w-full min-w-0 flex-col gap-1", className)}
data-slot="trace"
{...props}
/>
);
}
function TraceLine({
className,
status,
...props
}: React.ComponentProps<"span"> & {
status?: "running" | "error" | "pending";
}) {
return (
<TraceLineContext.Provider value={{ status }}>
<span
className={cn(
"text-muted-foreground flex w-fit max-w-full min-w-0 items-center gap-2",
"data-[status=error]:text-destructive",
"data-[status=pending]:opacity-60",
"data-[status=running]:text-foreground",
className
)}
data-slot="trace-line"
data-status={status}
{...props}
/>
</TraceLineContext.Provider>
);
}
function TraceIcon({ className, ...props }: React.ComponentProps<"span">) {
return (
<span
aria-hidden="true"
className={cn(
"flex shrink-0 items-center justify-center [&_svg]:pointer-events-none [&_svg]:size-4",
className
)}
data-slot="trace-icon"
{...props}
/>
);
}
function TraceTitle({
className,
children,
...props
}: React.ComponentProps<"span">) {
const { status } = React.useContext(TraceLineContext);
const content =
status === "running" ? <Shimmer>{children}</Shimmer> : children;
return (
<span
className={cn("min-w-0 truncate", className)}
data-slot="trace-title"
{...props}
>
{content}
</span>
);
}
function TraceDescription({
className,
...props
}: React.ComponentProps<"span">) {
return (
<span
className={cn(
"text-muted-foreground/70 shrink-0 text-xs tabular-nums",
className
)}
data-slot="trace-description"
{...props}
/>
);
}
type TraceCollapsibleProps = Omit<React.ComponentProps<"div">, "onChange"> & {
animation?: false | string;
defaultOpen?: boolean;
disabled?: boolean;
motion?: string;
onOpenChange?: (open: boolean) => void;
open?: boolean;
};
function TraceCollapsible({
animation,
children,
className,
defaultOpen,
disabled,
motion,
onOpenChange,
open: openProp,
...props
}: TraceCollapsibleProps) {
const [internalOpen, setInternalOpen] = React.useState(defaultOpen ?? false);
const isControlled = openProp !== undefined;
const currentOpen = isControlled ? openProp : internalOpen;
const resolvedMotion = resolveTraceMotion(
motion,
animation,
defaultTraceMotion
);
const handleOpenChange = React.useCallback(
(next: boolean) => {
if (!isControlled) {
setInternalOpen(next);
}
onOpenChange?.(next);
},
[isControlled, onOpenChange]
);
return (
<TraceCollapsibleContext.Provider
value={{ motion: resolvedMotion, open: currentOpen }}
>
<Collapsible
className={cn("flex w-full min-w-0 flex-col", className)}
data-slot="trace-collapsible"
disabled={disabled}
motion={resolvedMotion}
onOpenChange={handleOpenChange}
open={currentOpen}
{...props}
>
{children}
</Collapsible>
</TraceCollapsibleContext.Provider>
);
}
function TraceCollapsibleTrigger({
className,
children,
onClick,
...props
}: React.ComponentProps<"button">) {
const { open } = React.useContext(TraceCollapsibleContext);
return (
<CollapsibleTrigger
className={cn(
"group/trace-collapsible-trigger text-muted-foreground flex w-fit max-w-full min-w-0 cursor-pointer items-center gap-2 text-left outline-none",
"has-[[data-status=error]]:text-destructive",
className
)}
data-slot="trace-collapsible-trigger"
onClick={onClick}
{...props}
>
<span className="inline-flex items-center gap-2 transition-transform duration-200 hover:translate-x-px motion-reduce:transition-none motion-reduce:hover:translate-x-0">
{children}
</span>
<span
aria-hidden="true"
className="flex shrink-0 items-center justify-center transition-transform duration-200 data-[state=open]:rotate-90 motion-reduce:transition-none"
data-state={open ? "open" : "closed"}
>
<ChevronRightIcon className="text-muted-foreground size-3.5" />
</span>
</CollapsibleTrigger>
);
}
type TraceCollapsibleContentProps = React.ComponentProps<"div"> & {
animation?: false | string;
animateHeight?: boolean;
keepMounted?: boolean;
motion?: string;
};
function TraceCollapsibleContent({
animateHeight = true,
animation,
children,
className,
keepMounted: _keepMounted,
motion,
...props
}: TraceCollapsibleContentProps) {
const { motion: contextMotion } = React.useContext(TraceCollapsibleContext);
const resolvedMotion = resolveTraceMotion(motion, animation, contextMotion);
return (
<CollapsibleContent
motion={animateHeight ? resolvedMotion : false}
{...props}
>
<div
className={cn("border-border mt-1 ml-2 border-l pb-1 pl-4", className)}
data-slot="trace-collapsible-content"
>
{children}
</div>
</CollapsibleContent>
);
}
export {
Trace,
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceDescription,
TraceIcon,
TraceLine,
TraceTitle,
};Trace is the foundational primitive behind Chain of Thought and any vertical step list. It composes a flex column of lines, each with an icon, title, and optional status.
Installation
$ bunx --bun frakment add trace$ npx frakment add trace$ pnpm dlx frakment add trace$ yarn dlx frakment add trace
Install the following dependencies:
$ bun add lucide-react$ npm install lucide-react$ pnpm add lucide-react$ yarn add lucide-react
Copy and paste the following code into your project.
"use client";
import { ChevronRightIcon } from "lucide-react";
import * as React from "react";
import {
Collapsible,
CollapsibleContent,
CollapsibleTrigger,
} from "@/components/ui/collapsible";
import { Shimmer } from "@/components/ui/shimmer";
import { cn } from "@/lib/utils";
const defaultTraceMotion = "450 cubic-bezier(0.32, 0.72, 0, 1)";
interface TraceCollapsibleContextValue {
motion: string;
open: boolean;
}
const TraceCollapsibleContext =
React.createContext<TraceCollapsibleContextValue>({
motion: defaultTraceMotion,
open: false,
});
const TraceLineContext = React.createContext<{
status?: "running" | "error" | "pending";
}>({});
function resolveTraceMotion(
motion: string | undefined,
animation: false | string | undefined,
fallback: string
): string {
if (motion !== undefined) {
return motion;
}
if (animation === false) {
return "off";
}
if (typeof animation === "string") {
if (/^(spring|inertia|keyframes)/u.test(animation)) {
console.warn(
`[trace] animation="${animation}" uses a motion DSL that is not supported in CSS. Falling back to default. Prefer motion="150 ease-out" instead.`
);
return fallback;
}
return animation;
}
return fallback;
}
function Trace({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn("flex w-full min-w-0 flex-col gap-1", className)}
data-slot="trace"
{...props}
/>
);
}
function TraceLine({
className,
status,
...props
}: React.ComponentProps<"span"> & {
status?: "running" | "error" | "pending";
}) {
return (
<TraceLineContext.Provider value={{ status }}>
<span
className={cn(
"text-muted-foreground flex w-fit max-w-full min-w-0 items-center gap-2",
"data-[status=error]:text-destructive",
"data-[status=pending]:opacity-60",
"data-[status=running]:text-foreground",
className
)}
data-slot="trace-line"
data-status={status}
{...props}
/>
</TraceLineContext.Provider>
);
}
function TraceIcon({ className, ...props }: React.ComponentProps<"span">) {
return (
<span
aria-hidden="true"
className={cn(
"flex shrink-0 items-center justify-center [&_svg]:pointer-events-none [&_svg]:size-4",
className
)}
data-slot="trace-icon"
{...props}
/>
);
}
function TraceTitle({
className,
children,
...props
}: React.ComponentProps<"span">) {
const { status } = React.useContext(TraceLineContext);
const content =
status === "running" ? <Shimmer>{children}</Shimmer> : children;
return (
<span
className={cn("min-w-0 truncate", className)}
data-slot="trace-title"
{...props}
>
{content}
</span>
);
}
function TraceDescription({
className,
...props
}: React.ComponentProps<"span">) {
return (
<span
className={cn(
"text-muted-foreground/70 shrink-0 text-xs tabular-nums",
className
)}
data-slot="trace-description"
{...props}
/>
);
}
type TraceCollapsibleProps = Omit<React.ComponentProps<"div">, "onChange"> & {
animation?: false | string;
defaultOpen?: boolean;
disabled?: boolean;
motion?: string;
onOpenChange?: (open: boolean) => void;
open?: boolean;
};
function TraceCollapsible({
animation,
children,
className,
defaultOpen,
disabled,
motion,
onOpenChange,
open: openProp,
...props
}: TraceCollapsibleProps) {
const [internalOpen, setInternalOpen] = React.useState(defaultOpen ?? false);
const isControlled = openProp !== undefined;
const currentOpen = isControlled ? openProp : internalOpen;
const resolvedMotion = resolveTraceMotion(
motion,
animation,
defaultTraceMotion
);
const handleOpenChange = React.useCallback(
(next: boolean) => {
if (!isControlled) {
setInternalOpen(next);
}
onOpenChange?.(next);
},
[isControlled, onOpenChange]
);
return (
<TraceCollapsibleContext.Provider
value={{ motion: resolvedMotion, open: currentOpen }}
>
<Collapsible
className={cn("flex w-full min-w-0 flex-col", className)}
data-slot="trace-collapsible"
disabled={disabled}
motion={resolvedMotion}
onOpenChange={handleOpenChange}
open={currentOpen}
{...props}
>
{children}
</Collapsible>
</TraceCollapsibleContext.Provider>
);
}
function TraceCollapsibleTrigger({
className,
children,
onClick,
...props
}: React.ComponentProps<"button">) {
const { open } = React.useContext(TraceCollapsibleContext);
return (
<CollapsibleTrigger
className={cn(
"group/trace-collapsible-trigger text-muted-foreground flex w-fit max-w-full min-w-0 cursor-pointer items-center gap-2 text-left outline-none",
"has-[[data-status=error]]:text-destructive",
className
)}
data-slot="trace-collapsible-trigger"
onClick={onClick}
{...props}
>
<span className="inline-flex items-center gap-2 transition-transform duration-200 hover:translate-x-px motion-reduce:transition-none motion-reduce:hover:translate-x-0">
{children}
</span>
<span
aria-hidden="true"
className="flex shrink-0 items-center justify-center transition-transform duration-200 data-[state=open]:rotate-90 motion-reduce:transition-none"
data-state={open ? "open" : "closed"}
>
<ChevronRightIcon className="text-muted-foreground size-3.5" />
</span>
</CollapsibleTrigger>
);
}
type TraceCollapsibleContentProps = React.ComponentProps<"div"> & {
animation?: false | string;
animateHeight?: boolean;
keepMounted?: boolean;
motion?: string;
};
function TraceCollapsibleContent({
animateHeight = true,
animation,
children,
className,
keepMounted: _keepMounted,
motion,
...props
}: TraceCollapsibleContentProps) {
const { motion: contextMotion } = React.useContext(TraceCollapsibleContext);
const resolvedMotion = resolveTraceMotion(motion, animation, contextMotion);
return (
<CollapsibleContent
motion={animateHeight ? resolvedMotion : false}
{...props}
>
<div
className={cn("border-border mt-1 ml-2 border-l pb-1 pl-4", className)}
data-slot="trace-collapsible-content"
>
{children}
</div>
</CollapsibleContent>
);
}
export {
Trace,
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceDescription,
TraceIcon,
TraceLine,
TraceTitle,
};Update the import paths to match your project setup.
Usage
import { Trace, TraceLine, TraceIcon, TraceTitle } from "@/components/ui/trace";
<DocsBaseSwitcher base="web" component="trace" className="mb-6" /><Trace>
<TraceLine>
<TraceIcon>
<SearchIcon />
</TraceIcon>
<TraceTitle>Searched for 3 sources</TraceTitle>
</TraceLine>
</Trace>Composition
Trace
├── TraceLine
│ ├── TraceIcon
│ ├── TraceTitle
│ └── TraceDescription
└── TraceCollapsible
├── TraceCollapsibleTrigger
└── TraceCollapsibleContentStatic line
The smallest trace: an icon and a sentence.
import { GitBranchIcon } from "lucide-react";
import { Trace, TraceIcon, TraceLine, TraceTitle } from "@/components/ui/trace";
export function TraceStatic() {
return (
<Trace className="mx-auto w-fit max-w-full">
<TraceLine>
<TraceIcon>
<GitBranchIcon />
</TraceIcon>
<TraceTitle>Created branch fix/frozen-lockfile</TraceTitle>
</TraceLine>
</Trace>
);
}Status
Use status on TraceLine to convey state without extra markup.
| Status | Effect |
|---|---|
running | Foreground color, shimmer on title |
error | Destructive color |
pending | 60% opacity |
import { CircleAlertIcon, CircleCheckIcon, CircleIcon } from "lucide-react";
import { Spinner } from "@/components/ui/spinner";
import { Trace, TraceIcon, TraceLine, TraceTitle } from "@/components/ui/trace";
export function TraceStatus() {
return (
<Trace className="mx-auto w-fit max-w-full">
<TraceLine>
<TraceIcon>
<CircleCheckIcon />
</TraceIcon>
<TraceTitle>Ran pnpm install</TraceTitle>
</TraceLine>
<TraceLine status="error">
<TraceIcon>
<CircleAlertIcon />
</TraceIcon>
<TraceTitle>Failed to run pnpm lint</TraceTitle>
</TraceLine>
<TraceLine status="running">
<TraceIcon>
<Spinner />
</TraceIcon>
<TraceTitle>Running pnpm build</TraceTitle>
</TraceLine>
<TraceLine status="pending">
<TraceIcon>
<CircleIcon />
</TraceIcon>
<TraceTitle>Run pnpm test</TraceTitle>
</TraceLine>
</Trace>
);
}With description
Place a TraceDescription after the title to show a secondary value, such as a duration or byte count.
import { FileTextIcon, SearchIcon, TerminalIcon } from "lucide-react";
import {
Trace,
TraceDescription,
TraceIcon,
TraceLine,
TraceTitle,
} from "@/components/ui/trace";
export function TraceDescriptionDemo() {
return (
<Trace className="max-w-sm">
<TraceLine>
<TraceIcon>
<FileTextIcon />
</TraceIcon>
<TraceTitle>
Edited components/settings/notification-form.tsx
</TraceTitle>
<TraceDescription className="font-mono">+48 -12</TraceDescription>
</TraceLine>
<TraceLine>
<TraceIcon>
<TerminalIcon />
</TraceIcon>
<TraceTitle>Ran pnpm test</TraceTitle>
<TraceDescription>14s</TraceDescription>
</TraceLine>
<TraceLine>
<TraceIcon>
<SearchIcon />
</TraceIcon>
<TraceTitle>Searched for useChat</TraceTitle>
<TraceDescription>8 results</TraceDescription>
</TraceLine>
</Trace>
);
}Collapsible
Wrap a TraceLine in TraceCollapsibleTrigger to make it expand into nested steps.
$ node --version
v24.18.0import { TerminalIcon } from "lucide-react";
import { CodeBlock, CodeBlockContent } from "@/components/ui/code-block";
import {
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceIcon,
TraceLine,
TraceTitle,
} from "@/components/ui/trace";
export function TraceCollapsibleDemo() {
return (
<div className="max-w-sm">
<TraceCollapsible>
<TraceCollapsibleTrigger>
<TraceLine>
<TraceIcon>
<TerminalIcon />
</TraceIcon>
<TraceTitle>Ran node --version</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent>
<CodeBlock size="sm">
<CodeBlockContent className="max-h-64" wrap>
{"$ node --version\nv24.18.0"}
</CodeBlockContent>
</CodeBlock>
</TraceCollapsibleContent>
</TraceCollapsible>
</div>
);
}Controlled open
Pass open and onOpenChange to control the collapsible from outside.
$ node --version
v24.18.0$ pnpm --version
10.33.4"use client";
import { TerminalIcon } from "lucide-react";
import * as React from "react";
import { Button } from "@/components/ui/button";
import { CodeBlock, CodeBlockContent } from "@/components/ui/code-block";
import {
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceIcon,
TraceLine,
TraceTitle,
} from "@/components/ui/trace";
export function TraceOpen() {
const [open, setOpen] = React.useState(false);
return (
<div className="flex w-full max-w-sm flex-col items-start gap-4">
<TraceCollapsible defaultOpen>
<TraceCollapsibleTrigger>
<TraceLine>
<TraceIcon>
<TerminalIcon />
</TraceIcon>
<TraceTitle>Ran node --version</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent>
<CodeBlock size="sm">
<CodeBlockContent className="max-h-64" wrap>
{"$ node --version\nv24.18.0"}
</CodeBlockContent>
</CodeBlock>
</TraceCollapsibleContent>
</TraceCollapsible>
<TraceCollapsible onOpenChange={setOpen} open={open}>
<TraceCollapsibleTrigger>
<TraceLine>
<TraceIcon>
<TerminalIcon />
</TraceIcon>
<TraceTitle>Ran pnpm --version</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent>
<CodeBlock size="sm">
<CodeBlockContent className="max-h-64" wrap>
{"$ pnpm --version\n10.33.4"}
</CodeBlockContent>
</CodeBlock>
</TraceCollapsibleContent>
</TraceCollapsible>
<Button onClick={() => setOpen(!open)} size="sm" variant="outline">
{open ? "Hide" : "Show"} pnpm output
</Button>
</div>
);
}Links
Wrap a TraceLine in an anchor to make it navigable.
import {
ArrowUpRightIcon,
ChevronRightIcon,
FileTextIcon,
Globe,
} from "lucide-react";
import { Trace, TraceIcon, TraceLine, TraceTitle } from "@/components/ui/trace";
export function TraceLink() {
return (
<Trace className="mx-auto w-fit max-w-full">
<a
className="decoration-muted-foreground block underline-offset-4 hover:underline"
href="#link"
>
<TraceLine>
<TraceIcon>
<FileTextIcon />
</TraceIcon>
<TraceTitle>Read apps/v4/lib/docs.ts</TraceTitle>
<TraceIcon>
<ChevronRightIcon />
</TraceIcon>
</TraceLine>
</a>
<a
className="decoration-muted-foreground block underline-offset-4 hover:underline"
href="https://docs.astro.build/en/install-and-setup/"
rel="noreferrer"
target="_blank"
>
<TraceLine>
<TraceIcon>
<Globe />
</TraceIcon>
<TraceTitle>
Install Astro | docs.astro.build
<span className="sr-only"> (opens in a new tab)</span>
</TraceTitle>
<TraceIcon>
<ArrowUpRightIcon />
</TraceIcon>
</TraceLine>
</a>
</Trace>
);
}Group
Stack multiple lines to form a group of related steps.
import { FileTextIcon, SearchIcon, TerminalIcon } from "lucide-react";
import { Trace, TraceIcon, TraceLine, TraceTitle } from "@/components/ui/trace";
export function TraceGroup() {
return (
<Trace className="mx-auto w-fit max-w-full">
<TraceLine>
<TraceIcon>
<SearchIcon />
</TraceIcon>
<TraceTitle>Searched for minimumReleaseAge</TraceTitle>
</TraceLine>
<TraceLine>
<TraceIcon>
<FileTextIcon />
</TraceIcon>
<TraceTitle>Read pnpm-workspace.yaml</TraceTitle>
</TraceLine>
<TraceLine>
<TraceIcon>
<TerminalIcon />
</TraceIcon>
<TraceTitle>Ran pnpm install</TraceTitle>
</TraceLine>
</Trace>
);
}Sources
Group source links inside a collapsible trace.
import { ArrowUpRightIcon, Globe } from "lucide-react";
import {
Trace,
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceIcon,
TraceLine,
TraceTitle,
} from "@/components/ui/trace";
const SOURCES = [
{
href: "https://docs.astro.build/en/install-and-setup/",
title: "Install Astro | docs.astro.build",
},
{
href: "https://www.npmjs.com/package/create-astro",
title: "create-astro | npmjs.com",
},
{
href: "https://pnpm.io/settings#minimumreleaseage",
title: "Settings: minimumReleaseAge | pnpm.io",
},
];
export function TraceSources() {
return (
<div className="max-w-sm">
<TraceCollapsible defaultOpen>
<TraceCollapsibleTrigger>
<TraceLine>
<TraceIcon>
<Globe />
</TraceIcon>
<TraceTitle>Used {SOURCES.length} sources</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent>
<Trace>
{SOURCES.map((s) => (
<a
className="decoration-muted-foreground block underline-offset-4 hover:underline"
href={s.href}
key={s.href}
rel="noreferrer"
target="_blank"
>
<TraceLine>
<TraceIcon>
<Globe />
</TraceIcon>
<TraceTitle>
{s.title}
<span className="sr-only"> (opens in a new tab)</span>
</TraceTitle>
<TraceIcon>
<ArrowUpRightIcon />
</TraceIcon>
</TraceLine>
</a>
))}
</Trace>
</TraceCollapsibleContent>
</TraceCollapsible>
</div>
);
}Steps
Model a multi-step task with nested collapsibles and a running status.
import { ChevronRightIcon, FileTextIcon, SearchIcon } from "lucide-react";
import { Badge } from "@/components/ui/badge";
import { CodeBlock, CodeBlockContent } from "@/components/ui/code-block";
import {
Trace,
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceIcon,
TraceLine,
TraceTitle,
} from "@/components/ui/trace";
export function TraceSteps() {
return (
<div className="w-full max-w-sm">
<TraceCollapsible defaultOpen>
<TraceCollapsibleTrigger>
<TraceLine status="running">
<TraceTitle>Looking into the slow deploy</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent keepMounted>
<Trace>
<TraceCollapsible>
<TraceCollapsibleTrigger>
<TraceLine>
<TraceIcon>
<SearchIcon />
</TraceIcon>
<TraceTitle>Searched for the checkout build log</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent className="flex flex-wrap gap-1.5">
<Badge variant="secondary">vercel.com</Badge>
<Badge variant="secondary">github.com</Badge>
</TraceCollapsibleContent>
</TraceCollapsible>
<a
className="decoration-muted-foreground block underline-offset-4 hover:underline"
href="#steps"
>
<TraceLine>
<TraceIcon>
<FileTextIcon />
</TraceIcon>
<TraceTitle>Read the last twelve deploys</TraceTitle>
<TraceIcon>
<ChevronRightIcon />
</TraceIcon>
</TraceLine>
</a>
<TraceCollapsible>
<TraceCollapsibleTrigger>
<TraceLine status="running">
<TraceIcon>
<SearchIcon />
</TraceIcon>
<TraceTitle>Searching for the cache key</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent>
<CodeBlock size="sm">
<CodeBlockContent className="max-h-64" wrap>
cache key image optimization
</CodeBlockContent>
</CodeBlock>
</TraceCollapsibleContent>
</TraceCollapsible>
</Trace>
</TraceCollapsibleContent>
</TraceCollapsible>
</div>
);
}Commit
Show a commit with per-file diffs inside a sheet.
import {
ChevronRightIcon,
FilePenIcon,
FilePlusIcon,
GitCommitHorizontalIcon,
} from "lucide-react";
import {
CodeBlock,
CodeBlockContent,
CodeBlockLine,
} from "@/components/ui/code-block";
import {
Sheet,
SheetContent,
SheetDescription,
SheetHeader,
SheetTitle,
SheetTrigger,
} from "@/components/ui/sheet";
import {
Trace,
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceDescription,
TraceIcon,
TraceLine,
TraceTitle,
} from "@/components/ui/trace";
const files = [
{
added: false,
additions: 2,
deletions: 2,
diff: `@@ -14,7 +14,7 @@ export async function LoginPage({
searchParams,
}) {
const { next } = await searchParams
- const redirectTo =
- next && next.startsWith("/") ? next : "/"
+ const redirectTo = safeRedirect(next)
+
return <LoginForm redirectTo={redirectTo} />
}`,
path: "app/login/page.tsx",
},
{
added: true,
additions: 7,
deletions: 0,
diff: `@@ -0,0 +1,7 @@
+export function safeRedirect(next: string | undefined) {
+ if (!next || !next.startsWith("/") || next.startsWith("//")) {
+ return "/"
+ }
+
+ return next
+}`,
path: "lib/auth/redirect.ts",
},
];
function DiffLines({ diff }: { diff: string }) {
return diff.split("\n").map((line, index) => {
if (line.startsWith("@@")) {
return (
<CodeBlockLine className="text-muted-foreground" key={index}>
{line}
</CodeBlockLine>
);
}
return (
<CodeBlockLine
key={index}
variant={
line.startsWith("+")
? "added"
: line.startsWith("-")
? "removed"
: "default"
}
>
{line.slice(1)}
</CodeBlockLine>
);
});
}
export function TraceCommit() {
return (
<Trace className="max-w-sm">
<TraceCollapsible defaultOpen>
<TraceCollapsibleTrigger>
<TraceLine>
<TraceIcon>
<GitCommitHorizontalIcon />
</TraceIcon>
<TraceTitle>Committed a1b2c3: Fix the login redirect</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent>
<Trace>
{files.map((file) => (
<Sheet key={file.path}>
<SheetTrigger>
<TraceLine>
<TraceIcon>
{file.added ? <FilePlusIcon /> : <FilePenIcon />}
</TraceIcon>
<TraceTitle>
{file.added ? "Added" : "Edited"} {file.path}
</TraceTitle>
<TraceDescription className="font-mono">
+{file.additions} −{file.deletions}
</TraceDescription>
<TraceIcon>
<ChevronRightIcon />
</TraceIcon>
</TraceLine>
</SheetTrigger>
<SheetContent>
<SheetHeader>
<SheetTitle className="font-mono">{file.path}</SheetTitle>
<SheetDescription>
{file.additions} additions, {file.deletions} deletions
</SheetDescription>
</SheetHeader>
<CodeBlock className="mx-6 mb-6 w-auto">
<CodeBlockContent>
<DiffLines diff={file.diff} />
</CodeBlockContent>
</CodeBlock>
</SheetContent>
</Sheet>
))}
</Trace>
</TraceCollapsibleContent>
</TraceCollapsible>
</Trace>
);
}Dialog
Open a full result set from a trace line using a dialog.
import { ArrowUpRightIcon, ChevronRightIcon, GlobeIcon } from "lucide-react";
import {
Dialog,
DialogContent,
DialogDescription,
DialogHeader,
DialogTitle,
DialogTrigger,
} from "@/components/ui/dialog";
import { Trace, TraceIcon, TraceLine, TraceTitle } from "@/components/ui/trace";
const results = [
{
title: "Caching build outputs",
url: "https://nextjs.org/docs/app/guides/caching",
},
{
title: "Image optimization reference",
url: "https://nextjs.org/docs/app/api-reference/components/image",
},
{
title: "Deploy hooks and cache keys",
url: "https://vercel.com/docs/deploy-hooks",
},
];
export function TraceDialog() {
return (
<Trace className="mx-auto w-fit max-w-full">
<Dialog>
<DialogTrigger>
<TraceLine>
<TraceIcon>
<GlobeIcon />
</TraceIcon>
<TraceTitle>Searched the web for cache keys</TraceTitle>
<TraceIcon>
<ChevronRightIcon />
</TraceIcon>
</TraceLine>
</DialogTrigger>
<DialogContent>
<DialogHeader>
<DialogTitle>Searched the web for cache keys</DialogTitle>
<DialogDescription>
Three results were used in the response.
</DialogDescription>
</DialogHeader>
<Trace>
{results.map((result) => (
<a
className="decoration-muted-foreground block underline-offset-4 hover:underline"
href={result.url}
key={result.url}
rel="noreferrer"
target="_blank"
>
<TraceLine>
<TraceIcon>
<GlobeIcon />
</TraceIcon>
<TraceTitle>
{result.title}
<span className="sr-only"> (opens in a new tab)</span>
</TraceTitle>
<TraceIcon>
<ArrowUpRightIcon />
</TraceIcon>
</TraceLine>
</a>
))}
</Trace>
</DialogContent>
</Dialog>
</Trace>
);
}Sheet
Open a list of files from a trace line using a sheet.
import { ChevronRightIcon, FolderSearchIcon } from "lucide-react";
import {
Sheet,
SheetContent,
SheetDescription,
SheetHeader,
SheetTitle,
SheetTrigger,
} from "@/components/ui/sheet";
import { Trace, TraceIcon, TraceLine, TraceTitle } from "@/components/ui/trace";
export function TraceSheet() {
return (
<Trace className="mx-auto w-fit max-w-full">
<Sheet>
<SheetTrigger>
<TraceLine>
<TraceIcon>
<FolderSearchIcon />
</TraceIcon>
<TraceTitle>Explored 4 files</TraceTitle>
<TraceIcon>
<ChevronRightIcon />
</TraceIcon>
</TraceLine>
</SheetTrigger>
<SheetContent>
<SheetHeader>
<SheetTitle>Explored 4 files</SheetTitle>
<SheetDescription>
Files read while preparing the response.
</SheetDescription>
</SheetHeader>
<ul className="flex flex-col gap-2 px-6 font-mono text-xs">
<li>apps/v4/lib/docs.ts</li>
<li>apps/v4/lib/components.ts</li>
<li>apps/v4/next.config.mjs</li>
<li>apps/v4/package.json</li>
</ul>
</SheetContent>
</Sheet>
</Trace>
);
}Full turn
Nest traces to model a full agent turn with reasoning, tool calls, and output.
command not found: pnpmNode is installed and pnpm is not. Reading the docs config.
import {
ChevronRightIcon,
FileTextIcon,
SparklesIcon,
TerminalIcon,
} from "lucide-react";
import { CodeBlock, CodeBlockContent } from "@/components/ui/code-block";
import {
Trace,
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceDescription,
TraceIcon,
TraceLine,
TraceTitle,
} from "@/components/ui/trace";
export function TraceTurn() {
return (
<div className="max-w-sm">
<TraceCollapsible defaultOpen>
<TraceCollapsibleTrigger>
<TraceLine status="error">
<TraceTitle>Worked for 2m 4s, 1 command failed</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent className="flex flex-col gap-2" keepMounted>
<Trace>
<TraceCollapsible>
<TraceCollapsibleTrigger>
<TraceLine>
<TraceIcon>
<SparklesIcon />
</TraceIcon>
<TraceTitle>Thought</TraceTitle>
<TraceDescription>12s</TraceDescription>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent className="whitespace-pre-wrap">
Check which package managers are installed before scaffolding.
</TraceCollapsibleContent>
</TraceCollapsible>
<TraceCollapsible defaultOpen>
<TraceCollapsibleTrigger>
<TraceLine status="error">
<TraceIcon>
<TerminalIcon />
</TraceIcon>
<TraceTitle>Ran 2 commands, 1 failed</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent keepMounted>
<Trace>
<TraceLine>
<TraceIcon>
<TerminalIcon />
</TraceIcon>
<TraceTitle>Ran node --version</TraceTitle>
</TraceLine>
<TraceCollapsible>
<TraceCollapsibleTrigger>
<TraceLine status="error">
<TraceIcon>
<TerminalIcon />
</TraceIcon>
<TraceTitle>Failed to run pnpm --version</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent>
<CodeBlock size="sm" variant="destructive">
<CodeBlockContent className="max-h-64" wrap>
command not found: pnpm
</CodeBlockContent>
</CodeBlock>
</TraceCollapsibleContent>
</TraceCollapsible>
</Trace>
</TraceCollapsibleContent>
</TraceCollapsible>
</Trace>
<p className="text-sm">
Node is installed and pnpm is not. Reading the docs config.
</p>
<Trace>
<a
className="decoration-muted-foreground block underline-offset-4 hover:underline"
href="#turn"
>
<TraceLine>
<TraceIcon>
<FileTextIcon />
</TraceIcon>
<TraceTitle>Read apps/v4/lib/docs.ts</TraceTitle>
<TraceIcon>
<ChevronRightIcon />
</TraceIcon>
</TraceLine>
</a>
</Trace>
</TraceCollapsibleContent>
</TraceCollapsible>
</div>
);
}Thinking
Stream a reasoning block as it is generated.
"use client";
import { useChat } from "@ai-sdk/react";
import type { UIMessage } from "ai";
import { BrainIcon } from "lucide-react";
import * as React from "react";
import { Button } from "@/components/ui/button";
import {
Bubble,
BubbleContent,
Message,
MessageContent,
} from "@/components/ui/message";
import {
Trace,
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceIcon,
TraceLine,
TraceTitle,
} from "@/components/ui/trace";
import { createChat, getMessageText } from "@/lib/ai";
const chat = createChat()
.user("Why is the checkout deploy so slow?")
.assistant(({ writer }) => {
writer.reasoning(
"The build log shows install and compile finish in under a minute. Image optimization takes almost four, and it reruns on every deploy because the cache key includes the commit hash.",
{ delayMs: 60 }
);
writer.sleep(400);
writer.text(
"Image optimization is the bottleneck. Key its cache on the lockfile and the image directory instead of the commit hash."
);
});
const initialMessages = chat.get(0);
const transport = chat.transport({ delayMs: 20 });
function ThinkingTrace({ text, running }: { text: string; running: boolean }) {
const [open, setOpen] = React.useState<boolean>();
const line = (
<TraceLine status={running ? "running" : undefined}>
<TraceIcon>
<BrainIcon />
</TraceIcon>
<TraceTitle>{running ? "Thinking" : "Thought"}</TraceTitle>
</TraceLine>
);
if (text.length === 0) {
return line;
}
return (
<TraceCollapsible onOpenChange={setOpen} open={open ?? running}>
<TraceCollapsibleTrigger>{line}</TraceCollapsibleTrigger>
<TraceCollapsibleContent className="text-muted-foreground whitespace-pre-wrap">
{text}
</TraceCollapsibleContent>
</TraceCollapsible>
);
}
function groupParts(parts: UIMessage["parts"]) {
const runs: { trace: boolean; parts: UIMessage["parts"] }[] = [];
for (const part of parts) {
const trace = part.type === "reasoning";
if (!trace && part.type !== "text") {
continue;
}
const last = runs.at(-1);
if (last?.trace === trace) {
last.parts.push(part);
} else {
runs.push({ parts: [part], trace });
}
}
return runs;
}
export function TraceThinking() {
const { messages, sendMessage, setMessages, status } = useChat({
messages: initialMessages,
transport,
});
const nextMessage = chat.next(messages);
const busy = status === "submitted" || status === "streaming";
return (
<div className="flex min-h-72 w-full max-w-sm flex-col gap-4 py-6 text-sm">
{messages.map((message) => {
if (message.role === "user") {
return (
<Message align="end" key={message.id}>
<MessageContent>
<Bubble align="end" variant="muted">
<BubbleContent>{getMessageText(message)}</BubbleContent>
</Bubble>
</MessageContent>
</Message>
);
}
const live = status === "streaming" && message === messages.at(-1);
return (
<Message key={message.id}>
<MessageContent className="gap-4">
{groupParts(message.parts).map((run, runIndex) =>
run.trace ? (
<Trace key={runIndex}>
{run.parts.map((part, index) =>
part.type === "reasoning" ? (
<ThinkingTrace
key={index}
running={live && part.state === "streaming"}
text={part.text}
/>
) : null
)}
</Trace>
) : (
run.parts.map((part, index) =>
part.type === "text" ? (
<p key={`${runIndex}-${index}`}>{part.text}</p>
) : null
)
)
)}
</MessageContent>
</Message>
);
})}
{!busy && (
<Button
className="mt-auto self-start"
onClick={() =>
nextMessage
? sendMessage(nextMessage)
: setMessages(initialMessages)
}
size="sm"
variant="outline"
>
{nextMessage ? "Send message" : "Reset"}
</Button>
)}
</div>
);
}Tool calls
Track tool invocations with running, done, and failed states.
"use client";
import { useChat } from "@ai-sdk/react";
import type { DynamicToolUIPart, UIMessage } from "ai";
import { TerminalIcon } from "lucide-react";
import { Button } from "@/components/ui/button";
import { CodeBlock, CodeBlockContent } from "@/components/ui/code-block";
import {
Bubble,
BubbleContent,
Message,
MessageContent,
} from "@/components/ui/message";
import {
Trace,
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceIcon,
TraceLine,
TraceTitle,
} from "@/components/ui/trace";
import { createChat, getMessageText } from "@/lib/ai";
const chat = createChat()
.user("Which package managers are installed?")
.assistant(({ writer }) => {
writer
.tool("runCommand", {
dynamic: true,
input: { command: "node --version" },
})
.sleep(900)
.output({ stdout: "v24.18.0" });
writer
.tool("runCommand", {
dynamic: true,
input: { command: "npm --version" },
})
.sleep(900)
.output({ stdout: "11.6.2" });
writer
.tool("runCommand", {
dynamic: true,
input: { command: "pnpm --version" },
})
.sleep(900)
.error("command not found: pnpm");
writer.text("Node 24 and npm 11 are installed. pnpm is not.");
});
const initialMessages = chat.get(0);
const transport = chat.transport({ delayMs: 20 });
function ToolTrace({ part, live }: { part: DynamicToolUIPart; live: boolean }) {
const command = (part.input as { command?: string } | undefined)?.command;
if (part.state === "output-available" || part.state === "output-error") {
const failed = part.state === "output-error";
return (
<TraceCollapsible>
<TraceCollapsibleTrigger>
<TraceLine status={failed ? "error" : undefined}>
<TraceIcon>
<TerminalIcon />
</TraceIcon>
<TraceTitle>
{failed ? "Failed to run" : "Ran"} {command}
</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent>
<CodeBlock size="sm">
<CodeBlockContent className="max-h-64" wrap>
{failed
? part.errorText
: (part.output as { stdout: string }).stdout}
</CodeBlockContent>
</CodeBlock>
</TraceCollapsibleContent>
</TraceCollapsible>
);
}
if (part.state === "output-denied") {
return (
<TraceLine>
<TraceIcon>
<TerminalIcon />
</TraceIcon>
<TraceTitle>Denied {command}</TraceTitle>
</TraceLine>
);
}
return (
<TraceLine status={live ? "running" : "error"}>
<TraceIcon>
<TerminalIcon />
</TraceIcon>
<TraceTitle>
{live ? "Running" : "Failed to run"} {command}
</TraceTitle>
</TraceLine>
);
}
function groupParts(parts: UIMessage["parts"]) {
const runs: { trace: boolean; parts: UIMessage["parts"] }[] = [];
for (const part of parts) {
const trace = part.type === "dynamic-tool";
if (!trace && part.type !== "text") {
continue;
}
const last = runs.at(-1);
if (last?.trace === trace) {
last.parts.push(part);
} else {
runs.push({ parts: [part], trace });
}
}
return runs;
}
export function TraceToolCalls() {
const { messages, sendMessage, setMessages, status } = useChat({
messages: initialMessages,
transport,
});
const nextMessage = chat.next(messages);
const busy = status === "submitted" || status === "streaming";
return (
<div className="flex min-h-72 w-full max-w-sm flex-col gap-4 py-6 text-sm">
{messages.map((message) => {
if (message.role === "user") {
return (
<Message align="end" key={message.id}>
<MessageContent>
<Bubble align="end" variant="muted">
<BubbleContent>{getMessageText(message)}</BubbleContent>
</Bubble>
</MessageContent>
</Message>
);
}
const live = status === "streaming" && message === messages.at(-1);
return (
<Message key={message.id}>
<MessageContent className="gap-4">
{groupParts(message.parts).map((run, runIndex) =>
run.trace ? (
<Trace key={runIndex}>
{run.parts.map((part) =>
part.type === "dynamic-tool" ? (
<ToolTrace
key={part.toolCallId}
live={live}
part={part}
/>
) : null
)}
</Trace>
) : (
run.parts.map((part, index) =>
part.type === "text" ? (
<p key={`${runIndex}-${index}`}>{part.text}</p>
) : null
)
)
)}
</MessageContent>
</Message>
);
})}
{!busy && (
<Button
className="mt-auto self-start"
onClick={() =>
nextMessage
? sendMessage(nextMessage)
: setMessages(initialMessages)
}
size="sm"
variant="outline"
>
{nextMessage ? "Send message" : "Reset"}
</Button>
)}
</div>
);
}In Context
Agent step list
"use client";
import { CircleCheckIcon, LoaderCircleIcon } from "lucide-react";
import { Trace, TraceIcon, TraceLine, TraceTitle } from "@/components/ui/trace";
export function TraceAgentStep() {
return (
<div className="mx-auto w-fit max-w-full">
<Trace className="w-fit max-w-full">
<TraceLine>
<TraceIcon>
<CircleCheckIcon />
</TraceIcon>
<TraceTitle>Read 4 files</TraceTitle>
</TraceLine>
<TraceLine>
<TraceIcon>
<CircleCheckIcon />
</TraceIcon>
<TraceTitle>Ran pnpm test</TraceTitle>
</TraceLine>
<TraceLine status="running">
<TraceIcon>
<LoaderCircleIcon className="animate-spin" />
</TraceIcon>
<TraceTitle>Writing patch</TraceTitle>
</TraceLine>
</Trace>
</div>
);
}Motion
TraceCollapsible accepts motion on the root, inherited by content.
API Reference
Trace / TraceIcon / TraceTitle / TraceDescription
Extend React.ComponentProps<"div"> and React.ComponentProps<"span">. TraceIcon is aria-hidden. TraceTitle wraps its children in a shimmer when the parent line is running.
TraceLine
| Prop | Type | Default | Description |
|---|---|---|---|
status | runningerrorpending | — | Controls color and shimmer behavior of the line. |
TraceCollapsible
Extends React.ComponentProps<"div">. Supports open, defaultOpen, onOpenChange, motion (inherited by content), and deprecated animation (BC).
TraceCollapsibleTrigger
Renders a native <button>. Chevron rotates 90° when open via a CSS transform.
TraceCollapsibleContent
Extends React.ComponentProps<"div">. Animates height via CSS grid rows (0fr ↔ 1fr) with an opacity fade, re-targeting on content growth automatically. Accepts motion (per-instance override), animation (deprecated BC), and animateHeight (pass false to render plain show/hide).
Accessibility
TraceIconisaria-hidden. UseTraceTitleas the accessible name — write it as a sentence.- Status is conveyed by icon shape and color, not color alone.
prefers-reduced-motiondisables shimmer and collapse animation.
Best Practices
- One line per step. Do not merge unrelated actions into one line.
- Wrap trace in a collapsible for long runs. Ten lines collapse the transcript.
- Mark running steps.
status="running"triggers the shimmer and spinner. - Keep titles verb-first. "Ran pnpm test", not "pnpm test status".
On This Page
InstallationUsageCompositionStatic lineStatusWith descriptionCollapsibleControlled openLinksGroupSourcesStepsCommitDialogSheetFull turnThinkingTool callsIn ContextAgent step listMotionAPI ReferenceTrace / TraceIcon / TraceTitle / TraceDescriptionTraceLineTraceCollapsibleTraceCollapsibleTriggerTraceCollapsibleContentAccessibilityBest Practices