Step List
SaveA compact checklist of an agent's plan on a hairline rail: open dots for queued steps, an animated dot mark while running, and checks, x marks, or dashes once settled.
- Category
- Agent
- Version
- 0.3.0
- Frameworks
- Next.js, Vite + React
- Styling
- Tailwind CSS v4
Preview
Step List preview
Search the docs, Done
Found 3 pages
Edit the limits table, Running
Check links, Failed
2 links returned 404
Notify the team, Skipped
Open a pull request, Queued
Installation
npx @shakenui/cli add step-listReview the plan first. A dry run lists every file and package without changing anything:
npx @shakenui/cli add step-list --dry-runUsage
step-list-example.tsx
import { StepList } from "@/components/shaken/agent/step-list";
export default function StepListExample() {
return (
<StepList
className="w-full max-w-sm"
steps={[
{ id: "1", label: "Search the docs", status: "succeeded", detail: "Found 3 pages" },
{ id: "2", label: "Edit the limits table", status: "running" },
{ id: "3", label: "Check links", status: "failed", detail: "2 links returned 404" },
{ id: "4", label: "Notify the team", status: "skipped" },
{ id: "5", label: "Open a pull request", status: "queued" },
]}
/>
);
}API
| Prop | Type | Default | Description |
|---|---|---|---|
| steps | { id, label, status, detail?, meta?, activity? }[] | — | Steps in order. detail shows a result or the error; meta is right-aligned metadata such as a time and duration; activity picks the Agent State mark for a running step. |
| StepStatusIcon | ({ status }) => JSX | — | The shared circle glyph for a step status on its own, used by the graph components. |
| StatusGlyph | ({ kind, size? }) => JSX | — | The shared stroke glyphs: queued, running, success, failed, waiting, skipped. size is 16 or 20. |
Accessibility
- Each step has a visible text status and a screen-reader status after its label; glyphs and the mark are decorative.
- Skipped steps are struck through and labeled, not only dimmed.
- With reduced motion the running mark holds a still frame and new steps, glyph swaps, and the check draw appear instantly.
Files
Installed into src/components/shaken, or components/shaken when the project has no src directory.
src/components/shaken/agent/step-list.tsxstep-list- Also installs agent-run@0.1.2registry dependency
- Also installs agent-state@0.1.0registry dependency
- npm packages: noneReact and Tailwind CSS v4 required
Source
The exact source the CLI installs, from /r/items/react/step-list/0.3.0.json.
agent/step-list.tsxShowHide
agent/step-list.tsx
import type { ComponentProps, ReactNode } from "react";
import type { StepStatus } from "./agent-run";
import { type AgentActivity, AgentMark } from "./agent-state";
const labels: Record<StepStatus, string> = {
queued: "Queued",
running: "Running",
succeeded: "Done",
failed: "Failed",
skipped: "Skipped",
};
// Status text stays quiet; only a failure takes color. The glyph carries the rest.
const labelTone: Record<StepStatus, string> = {
queued: "text-zinc-500",
running: "text-zinc-600 dark:text-zinc-400",
succeeded: "text-zinc-500",
failed: "text-red-600 dark:text-red-400",
skipped: "text-zinc-500",
};
const ease = "ease-[cubic-bezier(0.23,1,0.32,1)]";
export interface StepListItem {
id: string;
label: ReactNode;
status: StepStatus;
/** Secondary line, e.g. a result summary or the error. */
detail?: ReactNode;
/** Optional right-aligned metadata on the second line, e.g. a start time and duration. */
meta?: ReactNode;
/** Which Agent State mark animates while the step runs. Defaults to thinking. */
activity?: AgentActivity;
}
export interface StepListProps extends Omit<ComponentProps<"ol">, "children"> {
steps: StepListItem[];
}
/**
* A compact checklist of an agent's plan. Steps sit on a hairline rail; a running step
* shows an animated dot mark, finished steps a check, and every row says its status in text.
*/
export function StepList({ steps, className, ...props }: StepListProps) {
return (
<ol className={["grid", className].filter(Boolean).join(" ")} {...props}>
{steps.map((step, index) => (
<li
key={step.id}
data-status={step.status}
className={`relative grid grid-cols-[1rem_minmax(0,1fr)] gap-x-3 pb-4 transition-[opacity,translate] duration-200 ${ease} last:pb-0 starting:translate-y-1 starting:opacity-0 motion-reduce:transition-none`}
>
{index < steps.length - 1 ? (
<span
aria-hidden="true"
className={[
"absolute top-6 bottom-1 left-[7.5px] w-px transition-colors duration-300 motion-reduce:transition-none",
step.status === "succeeded" ? "bg-zinc-950/25 dark:bg-white/25" : "bg-zinc-950/[0.08] dark:bg-white/10",
].join(" ")}
/>
) : null}
<StepGlyph key={step.status} status={step.status} activity={step.activity} />
<div className="min-w-0">
<div className="flex items-baseline justify-between gap-3">
<p
className={[
"min-w-0 text-sm leading-5 break-words transition-colors duration-200 motion-reduce:transition-none",
step.status === "skipped"
? "text-zinc-500 line-through decoration-zinc-500/60"
: step.status === "queued"
? "text-zinc-500"
: "text-zinc-950 dark:text-white",
].join(" ")}
>
{step.label}
<span className="sr-only">, {labels[step.status]}</span>
</p>
<span
aria-hidden="true"
className={`shrink-0 text-xs transition-colors duration-200 motion-reduce:transition-none ${labelTone[step.status]}`}
>
{labels[step.status]}
</span>
</div>
{step.detail != null || step.meta != null ? (
<div className="mt-0.5 flex items-baseline justify-between gap-3">
{step.detail != null ? (
<p className={step.status === "failed" ? "min-w-0 text-xs text-red-600 dark:text-red-400" : "min-w-0 text-xs text-zinc-500"}>
{step.detail}
</p>
) : (
<span />
)}
{step.meta != null ? <span className="shrink-0 font-mono text-[11px] text-zinc-500 tabular-nums">{step.meta}</span> : null}
</div>
) : null}
</div>
</li>
))}
</ol>
);
}
/**
* The step rail's glyphs: a small open dot for queued, the animated mark while running, a
* bare check, an x, or a dash. Remounted per status so the new shape eases in.
*/
function StepGlyph({ status, activity = "thinking" }: { status: StepStatus; activity?: AgentActivity }) {
const enter = `flex h-5 w-4 items-center justify-center transition-[opacity,scale,filter] duration-300 ${ease} starting:scale-75 starting:opacity-0 starting:blur-[2px] motion-reduce:transition-none`;
if (status === "running") {
return (
<span aria-hidden="true" className={enter}>
<AgentMark activity={activity} size={16} className="text-zinc-950 dark:text-white" />
</span>
);
}
const tone =
status === "succeeded"
? "text-emerald-600 dark:text-emerald-400"
: status === "failed"
? "text-red-600 dark:text-red-400"
: "text-zinc-400 dark:text-zinc-600";
return (
<span aria-hidden="true" className={enter}>
<svg viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth={1.5} strokeLinecap="round" strokeLinejoin="round" className={`size-4 ${tone}`}>
{status === "succeeded" ? (
<path
d="m4.25 8.4 2.5 2.45 5-5.6"
pathLength={1}
strokeDasharray="1"
className={`[stroke-dashoffset:0] transition-[stroke-dashoffset] delay-75 duration-300 ${ease} starting:[stroke-dashoffset:1] motion-reduce:transition-none`}
/>
) : status === "failed" ? (
<path d="m5.25 5.25 5.5 5.5m0-5.5-5.5 5.5" />
) : status === "skipped" ? (
<path d="M5.5 8h5" />
) : (
<circle cx="8" cy="8" r="3" />
)}
</svg>
</span>
);
}
/** The shared status shapes. Each one is paired with a text label wherever it is used. */
export type StatusGlyphKind = "queued" | "running" | "success" | "failed" | "waiting" | "skipped";
const glyphTone: Record<StatusGlyphKind, string> = {
queued: "text-zinc-500",
running: "text-sky-600 dark:text-sky-400",
success: "text-emerald-600 dark:text-emerald-400",
failed: "text-red-600 dark:text-red-400",
waiting: "text-amber-600 dark:text-amber-400",
skipped: "text-zinc-500",
};
const stepGlyph: Record<StepStatus, StatusGlyphKind> = {
queued: "queued",
running: "running",
succeeded: "success",
failed: "failed",
skipped: "skipped",
};
/**
* A 16px or 20px stroke glyph for an agent state. Remount it with `key={kind}` so the new
* shape scales in (and the success check draws); both are instant with reduced motion.
* The running arc is the only loop, and it holds still with reduced motion.
*/
export function StatusGlyph({ kind, size = 16, className = "" }: { kind: StatusGlyphKind; size?: 16 | 20; className?: string }) {
return (
<svg
aria-hidden="true"
viewBox="0 0 16 16"
fill="none"
stroke="currentColor"
// 1.2 in a 16 unit box drawn at 20px is a 1.5px stroke, matching the 16px glyph.
strokeWidth={size === 20 ? 1.2 : 1.5}
strokeLinecap="round"
strokeLinejoin="round"
data-glyph={kind}
className={[
size === 20 ? "size-5" : "size-4",
"shrink-0 transition-[opacity,scale] duration-200 ease-[cubic-bezier(0.23,1,0.32,1)] starting:scale-90 starting:opacity-0 motion-reduce:transition-none",
glyphTone[kind],
className,
].join(" ")}
>
{kind === "queued" ? (
<circle cx="8" cy="8" r="6.25" strokeDasharray="2.15 2.75" />
) : kind === "running" ? (
<>
<circle cx="8" cy="8" r="6.25" strokeOpacity="0.2" />
<path d="M8 1.75A6.25 6.25 0 1 1 1.75 8" className="origin-center motion-safe:animate-spin" />
</>
) : (
<>
<circle cx="8" cy="8" r="6.25" />
{kind === "success" ? (
<path
d="m5.35 8.25 1.75 1.75 3.55-3.75"
pathLength={1}
strokeDasharray="1"
className="[stroke-dashoffset:0] transition-[stroke-dashoffset] delay-75 duration-300 ease-[cubic-bezier(0.23,1,0.32,1)] starting:[stroke-dashoffset:1] motion-reduce:transition-none"
/>
) : kind === "failed" ? (
<path d="m6.1 6.1 3.8 3.8m0-3.8-3.8 3.8" />
) : kind === "waiting" ? (
<path d="M6.6 5.9v4.2M9.4 5.9v4.2" />
) : (
<path d="m5.6 10.4 4.8-4.8" />
)}
</>
)}
</svg>
);
}
/** Status glyph for steps; remount with `key={status}` to play its entry transition. */
export function StepStatusIcon({ status, className = "" }: { status: StepStatus; className?: string }) {
return <StatusGlyph kind={stepGlyph[status]} className={className} />;
}