Job progress

npx shadcn@latest add "@assistant-ui/elements-job-progress"

npx assistant-ui@latest init

import { AssistantRuntimeProvider } from "@assistant-ui/react";
import { useChatRuntime, AssistantChatTransport } from "@assistant-ui/ai-sdk";

export default function App() {
  const runtime = useChatRuntime({
    transport: new AssistantChatTransport({ api: "/api/chat" }),
  });

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      {/* your components */}
    </AssistantRuntimeProvider>
  );
}

npx shadcn@latest add "@assistant-ui/elements-job-progress"

A single long-running job: a title, a weighted sequence of stages, and one overall bar that fills as the current stage advances toward the end of the list. With a runtime the stage sequence comes from a tool call and its outcome from that call's result; standalone you drive stageIndex and stageProgress yourself, live, for as long as the job runs.

Getting started

"use client";

import { defineToolkit } from "@assistant-ui/react";
import { JobProgress } from "@/components/assistant-ui/elements/job-progress";

export const toolkit = defineToolkit({
  run_ci_job: {
    type: "backend",
    render: ({ args, result, addResult }) => {
      if (!result) {
        return (
          <JobProgress
            title={args.target}
            stages={args.stages ?? []}
            stageIndex={0}
            stageProgress={0}
            eta="starting"
            onCancel={() =>
              addResult({ stageIndex: 0, stageProgress: 0, eta: "cancelled" })
            }
          />
        );
      }
      return (
        <JobProgress
          title={args.target}
          stages={args.stages ?? []}
          stageIndex={result.stageIndex}
          stageProgress={result.stageProgress}
          eta={result.eta}
        />
      );
    },
  },
});

import {
  AssistantRuntimeProvider,
  AuiConfig,
  Tools,
} from "@assistant-ui/react";
import { useChatRuntime } from "@assistant-ui/ai-sdk";
import { toolkit } from "./toolkit";

export function MyRuntimeProvider({
  children,
}: {
  children: React.ReactNode;
}) {
  const runtime = useChatRuntime();
  const config = AuiConfig({ tools: Tools({ toolkit }) });
  return (
    <AssistantRuntimeProvider runtime={runtime} config={config}>
      {children}
    </AssistantRuntimeProvider>
  );
}

"use client";

import {
  JobProgress,
  type JobStage,
} from "@/components/assistant-ui/elements/job-progress";

const stages: readonly JobStage[] = [
  { name: "clone", weight: 1 },
  { name: "install", weight: 4 },
  { name: "build", weight: 3 },
  { name: "test", weight: 2 },
];

export function CiJob() {
  return (
    <JobProgress
      title="Verify the fix on CI"
      stages={stages}
      stageIndex={1}
      stageProgress={0.6}
      eta="about 3 min"
    />
  );
}

"use client";

import { useEffect, useRef, useState } from "react";

export function CiJob({ jobId }: { jobId: string }) {
  const [stageIndex, setStageIndex] = useState(0);
  const [stageProgress, setStageProgress] = useState(0);
  const controller = useRef(new AbortController());

  useEffect(() => {
    const source = subscribeToJob(jobId, controller.current.signal, (update) => {
      setStageIndex(update.stageIndex);
      setStageProgress(update.stageProgress);
    });
    return () => source.close();
  }, [jobId]);

  return (
    <JobProgress
      title="Verify the fix on CI"
      stages={stages}
      stageIndex={stageIndex}
      stageProgress={stageProgress}
      eta="about 3 min"
      onCancel={() => controller.current.abort()}
    />
  );
}

Anatomy

<div data-slot="job-progress">
  <div>
    {/* check icon once finished, else a spinning loader */}
    <span>{/* title */}</span>
    <span>{/* eta, or "done" once finished */}</span>
    {/* cancel button, hidden once finished */}
  </div>

  <span role="progressbar">{/* overall progress bar, named from the title */}</span>

  <div>
    {/* one label per stage, dimmed by position relative to the current stage */}
  </div>
</div>

stageIndex is floored and clamped into 0…stages.length rather than 0…stages.length − 1, so reaching stages.length itself, one past the last stage's own index, is what "finished" means. That is when the checkmark, the "done" label, and the filled green bar appear, and the cancel button disappears. stageProgress clamps into 0…1 and only scales the current stage's own contribution to the overall bar; every stage already passed counts its full weight regardless of stageProgress. The stages' weights are summed once and that total falls back to 1 when it would otherwise be 0, so an all-zero or empty stages array never divides by zero; it just never fills. Stage name labels dim by position: already passed stages read faintly, the current stage reads bright, stages still ahead read faintest of all. The overall bar is a named progressbar with a 0…100 value matching its painted width.

Examples

The finished state

Set stageIndex to stages.length, not to the last stage's own index, to show a job as done. stageProgress stops mattering once you cross that line.

<JobProgress
  title="Verify the fix on CI"
  stages={stages}
  stageIndex={stages.length}
  stageProgress={0}
  eta="seconds"
/>

Where the progress comes from

run_ci_job: tool({
  description: "Kick off CI for the current change and report where it lands.",
  inputSchema: z.object({
    target: z.string(),
    stages: z.array(z.object({ name: z.string(), weight: z.number() })),
  }),
  execute: async ({ target }) => runCiJob(target),
}),

function pollJob(jobId: string, onUpdate: (u: JobUpdate) => void) {
  const id = setInterval(async () => {
    onUpdate(await fetchJobStatus(jobId));
  }, 2000);
  return { close: () => clearInterval(id) };
}

Restyle the bar

Both lanes take className on the root. The ETA text and stage labels use the shared mono surface, and the cancel button uses the shared ghostButton surface, both from surfaces.tsx, so restyling those tokens restyles every element that uses them.

<JobProgress className="max-w-none gap-4" /* ... */ />

API reference