For the complete documentation index, see llms.txt. Markdown variants are available by appending .md to any URL or sending an Accept: text/markdown header. An agent skill is available at /.well-known/agent-skills/site-skill.md.
FrakmentFrakment

Trace

The primitive for rendering collapsible agent trace lines with icons, titles, and status.

Why does pnpm install fail in CI?
CI installs with a frozen lockfile, so the install stops when package.json and pnpm-lock.yaml disagree. I should check what the last commit changed, then reproduce the install.
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.json

The 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.

trace.tsx
"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

Usage

trace.tsx
import { Trace, TraceLine, TraceIcon, TraceTitle } from "@/components/ui/trace";
<DocsBaseSwitcher base="web" component="trace" className="mb-6" />
trace.tsx
<Trace>
  <TraceLine>
    <TraceIcon>
      <SearchIcon />
    </TraceIcon>
    <TraceTitle>Searched for 3 sources</TraceTitle>
  </TraceLine>
</Trace>

Composition

Trace
├── TraceLine
│   ├── TraceIcon
│   ├── TraceTitle
│   └── TraceDescription
└── TraceCollapsible
    ├── TraceCollapsibleTrigger
    └── TraceCollapsibleContent

Static line

The smallest trace: an icon and a sentence.

Created branch fix/frozen-lockfile
trace-static.tsx
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.

StatusEffect
runningForeground color, shimmer on title
errorDestructive color
pending60% opacity
Ran pnpm installFailed to run pnpm lintRunning pnpm buildRun pnpm test
trace-status.tsx
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.

Edited components/settings/notification-form.tsx+48 -12Ran pnpm test14sSearched for useChat8 results
trace-description.tsx
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.0
trace-collapsible.tsx
import { 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
trace-open.tsx
"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>
  );
}

Wrap a TraceLine in an anchor to make it navigable.

trace-link.tsx
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.

Searched for minimumReleaseAgeRead pnpm-workspace.yamlRan pnpm install
trace-group.tsx
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.

trace-sources.tsx
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.

vercel.comgithub.com
Read the last twelve deploys
cache key image optimization
trace-steps.tsx
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.

trace-commit.tsx
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.

trace-dialog.tsx
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.

trace-sheet.tsx
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.

Check which package managers are installed before scaffolding.
Ran node --version
command not found: pnpm

Node is installed and pnpm is not. Reading the docs config.

trace-turn.tsx
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.

trace-thinking.tsx
"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.

trace-tool-calls.tsx
"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

Read 4 filesRan pnpm testWriting patch
trace-agent-step.tsx
"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

PropTypeDefaultDescription
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

  • TraceIcon is aria-hidden. Use TraceTitle as the accessible name — write it as a sentence.
  • Status is conveyed by icon shape and color, not color alone.
  • prefers-reduced-motion disables 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".