When an operation takes more than a moment (build, test, deploy) the user deserves to know where things stand. ProgressTracker shows each step of a multi-step workflow with its current status: pending, in-progress, completed, or failed. If something breaks, the error is visible immediately. Once the operation finishes, the tracker collapses into a receipt with the final outcome.

Role: State. Shows internal activity and progress. See Design Guidelines for how component roles work.

Getting Started

import { ProgressTracker } from "@/components/tool-ui/progress-tracker";export function Example() {  return (    <ProgressTracker      id="progress-tracker-example"      steps={[        {          id: "build",          label: "Building",          description: "Compiling TypeScript and bundling assets",          status: "completed",        },        {          id: "test",          label: "Running Tests",          description: "147 tests across 23 suites",          status: "in-progress",        },        {          id: "deploy",          label: "Deploy to Production",          description: "Upload to edge nodes",          status: "pending",        },      ]}      elapsedTime={43200}    />  );}

"use client";import { type Toolkit } from "@assistant-ui/react";import { ProgressTracker } from "@/components/tool-ui/progress-tracker";import { safeParseSerializableProgressTracker } from "@/components/tool-ui/progress-tracker/schema";export const toolkit: Toolkit = {  trackProgress: {    type: "backend",    render: ({ result }) => {      const parsed = safeParseSerializableProgressTracker(result);      if (!parsed) {        return null;      }      return <ProgressTracker {...parsed} />;    },  },};

ProgressTracker is display-only and result-driven: render it from backend tool result updates. For interactive decisions or confirmations, use OptionList or ApprovalCard.

Key Features

Step Statuses

Each step has one of four statuses:

• Pending: not yet started (empty circle)
• In-progress: currently executing (animated spinner)
• Completed: finished successfully (filled checkmark)
• Failed: encountered an error (filled X icon)

The component automatically highlights the current step (first in-progress, otherwise first failed, otherwise first pending) with a subtle background and aria-current="step" for accessibility.

Receipt Pattern

Pass a choice prop to render this component in its receipt state. See Receipts for the pattern.

The receipt shows all steps with their final statuses, an elapsed time badge, and an outcome indicator in the top-right corner. Supports success, partial, failed, and cancelled outcomes. Read-only with no action buttons.

Elapsed Time

Pass elapsedTime in milliseconds to display a timer badge. Automatically formatted as:

• Under 60 seconds: 3.4s
• Over 60 seconds: 2m 15s

Props

ProgressStep Schema

ToolUIReceipt Schema

Accessibility

• Semantic <article> with role="status" and aria-live="polite" for live updates
• aria-busy indicates when an operation is in progress
• aria-current="step" marks the currently active step
• Steps rendered as semantic ordered list (<ol> / <li>)
• Elapsed duration is rendered with semantic <time> and machine-readable dateTime
• All animations respect prefers-reduced-motion
• Text is unselectable to prevent accidental highlighting during status changes

Related

• Plan: task-oriented progress with expandable detail per step