Task progress
A task list that shows what is done, running or next, and strikes tasks through as they finish. Use it on AI agent or setup screens with 5 to 9 steps.
- In progress: Read the project rules and notes
- Not started: Sketch the three task states
- Not started: Draw the strike as each task finishes
- Not started: Keep five tasks, fold the rest away
- Not started: Check light and dark on a phone
- Not started: Run the production build
- Not started: Hand it over for review
npx shadcn@latest add https://impeccableui.vercel.app/r/task-progress.jsonRun it in a project set up with shadcn. No other packages needed. Or open and copy the file into components/ui/task-progress.tsx.
Prompts
Paste one into Claude Code, Cursor or any AI coding tool. Install adds this exact list and asks only where it goes and which steps it shows. Blend asks four short questions (where and which steps, how many show, the words, and the spinner's color), then fits it to your product without changing how it moves.
# Task progress
A 1-file React component from Impeccable. Add it to this project so it works and looks exactly like the source below, in the one place I choose, and change nothing else.
A task list where each task is not started (a dotted circle), in progress (an arc spinning over the dots) or done (a filled circle with a check). When a task finishes, its check draws in, its text fades and a strike line draws across it. Hovering a done task (tapping it on a phone) pulls the strike back and darkens the text so it can be read. Only the first 5 tasks show; the rest open under "Show N more" and close with "Show less".
## Before you build: one question
Look through this project first: any screen that runs several steps in a row (an AI agent or assistant run, onboarding or setup, an import, build or deploy), any checklist or stepper it already has, and where those steps' states live in the code. Then ask me this in one message and wait for my answer:
- **Where should it go, and which steps does it show?** Suggest the 1–3 spots it fits best from my code. For each one, name the steps you would list and the existing state you would read to mark each one not started, in progress or done. I can pick one or name another.
*Why: the list is only honest when its states come from real work, so it belongs where my product already knows which step it is on.*
Ask nothing else. If I say *skip*, use the best suggestion.
## Keep it as it is
The three icons (dotted circle, spinning arc, filled circle with a check), the strike that draws across a finished task, the peek on hover or tap, and the fold after 5 tasks with "Show N more" and "Show less", with their timing, are the design. Keep them exactly as in the source. If something doesn't fit my project, tell me instead of changing it.
- Add only the component file and the one place I picked. If it replaces an existing checklist or stepper there, keep that spot's logic and remove only the old list. Don't add packages, change other files, or restyle anything.
- Don't add the demo parts from the Impeccable website: the list that plays on its own and starts over (`useTaskRun`), its example task names, pausing while the pointer is on it, the dotted card behind it, and the home page's TV.
## Fastest path
If this project has a `components.json` (shadcn), run `npx shadcn@latest add https://impeccableui.vercel.app/r/task-progress.json`.
If the command succeeds, only fix import paths to match this project and skip ahead. If it fails or there is no `components.json`, build it by hand as below.
## Build it
- Stack: React 18 or 19 with TypeScript. No other packages: the icons are inline SVG and every animation is CSS.
- JavaScript project? Name the file `task-progress.jsx` and remove the type annotations; nothing else changes.
- Create this file, in this project's usual place for components:
- `components/ui/task-progress.tsx`
- Keep these exports and their names: `TaskProgress`, `TaskProgressProps`, `Task`, `TaskStatus`.
- Keep `"use client"` at the top in Next.js App Router projects. In other setups it is harmless.
- Keep the tuning values at the top exactly as written: `EASE`, `POP`, `SPIN_MS`, `ARC`, `STRIKE_MS`, `STRIKE_DELAY`, `PEEK_MS`, `OPEN_MS`, `STAGGER`, `R` and the `CSS` block. They are the design and its timing.
- Keep the fallbacks: with `prefers-reduced-motion: reduce` the arc stops spinning and every change is a short fade (the strike appears without drawing). The rows under "Show more" are `inert` while folded, so keyboards and screen readers skip them. Screen readers hear "Done", "In progress" or "Not started" before each task, and the task in progress has `aria-current="step"`.
## Use it
```tsx
"use client";
import { TaskProgress, type Task } from "@/components/ui/task-progress";
export function SetupSteps({ step }: { step: number }) {
const names = ["Connect your store", "Import products", "Pick a theme", "Add a payment method", "Invite your team", "Go live"];
const tasks: Task[] = names.map((label, i) => ({
id: label,
label,
status: i < step ? "done" : i === step ? "active" : "pending",
}));
return <TaskProgress tasks={tasks} aria-label="Setup steps" className="max-w-md" />;
}
```
- Give each task a stable `id` (its name or the step's id), so a task keeps its own animation when the list changes.
- Change a task's `status` to animate it. Don't remount the list to update it, or nothing animates.
- It takes its text color from its parent, so place it where my normal text color applies. It fills the width it is given, so set a max width with `className` or `style`.
## How the list works
Read this before you touch anything, so you know what the code does and why it must stay as it is.
1. **The card.** A box with a 1px border at 13% of the text color and 16px corners, 15px text on 22px lines. Each task is one row: an 18px icon, a 12px gap, then the text, which wraps under itself (never under the icon). There is no background, so the page shows through unless `style` or `className` sets one.
2. **Not started.** A circle of 8 round dots at 52% of the text color. The text is the normal text color.
3. **In progress.** An arc covering 62% of the circle draws in over the dots and spins once every 0.9 seconds. It is the text color unless `activeColor` is set.
4. **Done.** The arc closes into a full ring, then a filled circle (46% of the text color) pops in with a tiny overshoot, and a check draws inside it. 0.3 seconds later the text fades to 46% and a 1.25px line draws across it from left to right in 0.52 seconds. On wrapped text the line runs across the first line, then the next. Tasks that are already done when the list first shows are struck at once, with no animation.
5. **Peek.** Hovering a done task pulls the line back to the left in 0.26 seconds and darkens the text to 88%; leaving draws it back. Phones have no hover, so a tap does the same and a second tap undoes it.
6. **Show more.** Only the first `limit` tasks (5) show. Under them, "Show N more" (the number of hidden tasks) opens the rest: the space grows in 0.42 seconds with a soft landing and the rows fade and slide down into place 45ms apart. The button then reads "Show less" and folds them away again. The list keeps its order; tasks are never moved.
7. **Colors.** Everything is mixed from the text color around the list, so it follows light and dark mode. The check is white on light pages and near-black on dark pages; it is re-read when the theme changes.
## Check
- It type-checks and the page renders with no console errors.
- The task in progress spins. When it finishes, its check draws in and, about 0.3 seconds later, a line draws across its text from left to right while the text fades. Hovering a done task pulls the line back and darkens the text. With more than 5 tasks, "Show N more" opens the rest and "Show less" folds them away.
- It looks right in light and dark mode (check both): the check is readable inside the filled circle in each.
- It works with a finger on a phone: tapping a done task shows it clearly, tapping again strikes it, and nothing scrolls sideways.
- With `prefers-reduced-motion: reduce`, the arc stands still and every change is a short fade.
- Nothing else on the site looks or behaves differently.
- Finish with a short report: the files you added or changed, where it's placed, and every place where you had to do something differently from the source, and why.
## Source
The reference implementation. Copy it as-is, then apply only the changes listed above.
### `components/ui/task-progress.tsx`
```tsx
"use client";
/**
* Task progress, from Impeccable.
*
* A list of tasks, each one of three states:
* - "pending": not started yet, a dotted circle.
* - "active": in progress, a spinning arc over the dotted circle.
* - "done": a filled circle with a check, the text faded and struck through.
* Hover a done task (tap it on a phone) and the strike pulls back and the text
* darkens, so it can be read. Only the first 5 tasks show; the rest open
* under "Show N more" and close again with "Show less".
*
* No packages. Colors come from the text color around the list, so it follows
* light and dark mode on its own.
*/
import { useEffect, useId, useRef, useState, type CSSProperties, type ReactNode } from "react";
export type TaskStatus = "pending" | "active" | "done";
export type Task = {
/** A stable id, so a task keeps its animation when the list changes. Falls back to its position. */
id?: string | number;
label: ReactNode;
status: TaskStatus;
};
export type TaskProgressProps = {
tasks: Task[];
/** How many tasks show before "Show N more". */
limit?: number;
/** Text of the button that opens the rest. Gets the number of hidden tasks. */
moreLabel?: (hidden: number) => ReactNode;
/** Text of the button that closes them again. */
lessLabel?: ReactNode;
/** Start with every task showing. */
defaultExpanded?: boolean;
/** Color of the spinning arc on the task in progress. Any CSS color, including var(--…). */
activeColor?: string;
/** Shown when there are no tasks. */
emptyLabel?: ReactNode;
/** Name of the list for screen readers. */
"aria-label"?: string;
className?: string;
style?: CSSProperties;
};
/* ---------- the design: keep as written ---------- */
const EASE = "cubic-bezier(.23,1,.32,1)"; // fast start, soft landing
const POP = "cubic-bezier(.34,1.56,.64,1)"; // a tiny overshoot
const SPIN_MS = 900; // one turn of the arc
const ARC = 0.62; // how much of the circle the arc covers while in progress
const STRIKE_MS = 520; // the strike drawing across a finished task
const STRIKE_DELAY = 300; // waits for the check before it strikes
const PEEK_MS = 260; // the strike pulling back on hover
const OPEN_MS = 420; // "Show more" opening or closing
const STAGGER = 45; // between rows as they open
const R = 7; // circle radius in the 18px icon
const C = 2 * Math.PI * R; // its length
const CSS = `
.itp { --itp-soft: color-mix(in oklab, currentColor 46%, transparent); --itp-line: color-mix(in oklab, currentColor 13%, transparent); --itp-dot: color-mix(in oklab, currentColor 52%, transparent); --itp-disc: color-mix(in oklab, currentColor 46%, transparent); box-sizing: border-box; border: 1px solid var(--itp-line); border-radius: 16px; padding: 10px 14px; font-size: 15px; line-height: 22px; }
.itp ul { list-style: none; margin: 0; padding: 0; }
.itp-row { display: flex; align-items: flex-start; gap: 12px; padding: 3px 0; -webkit-tap-highlight-color: transparent; }
.itp-icon { position: relative; flex: none; width: 18px; height: 22px; display: grid; place-items: center; }
.itp-icon > * { grid-area: 1 / 1; }
.itp-spin { width: 18px; height: 18px; animation: itp-spin ${SPIN_MS}ms linear infinite; animation-play-state: paused; }
.itp-row[data-status="active"] .itp-spin { animation-play-state: running; }
@keyframes itp-spin { to { transform: rotate(360deg); } }
.itp-dots { stroke: var(--itp-dot); transition: opacity .3s ${EASE}; }
.itp-arc { stroke: var(--itp-arc, currentColor); stroke-dasharray: ${C.toFixed(3)} ${C.toFixed(3)}; stroke-dashoffset: ${C.toFixed(3)}; transition: stroke-dashoffset .5s ${EASE}, opacity .2s; }
.itp-row[data-status="active"] .itp-arc { stroke-dashoffset: ${(C * (1 - ARC)).toFixed(3)}; }
.itp-row[data-status="done"] .itp-arc { stroke-dashoffset: 0; opacity: 0; transition: stroke-dashoffset .22s ${EASE}, opacity .2s .26s; }
.itp-row[data-status="done"] .itp-dots { opacity: 0; transition-delay: .2s; }
.itp-done { width: 18px; height: 18px; overflow: visible; }
.itp-disc { fill: var(--itp-disc); transform-origin: 9px 9px; transform: scale(.4); opacity: 0; transition: transform .2s ${EASE}, opacity .15s; }
.itp-row[data-status="done"] .itp-disc { transform: scale(1); opacity: 1; transition: transform .38s ${POP} .16s, opacity .16s .16s; }
.itp-check { stroke-dasharray: 10; stroke-dashoffset: 10; transition: stroke-dashoffset .12s; }
.itp-row[data-status="done"] .itp-check { stroke-dashoffset: 0; transition: stroke-dashoffset .28s ${EASE} .3s; }
.itp-text { min-width: 0; flex: 1; overflow-wrap: anywhere; }
.itp-label { color: currentColor; background: linear-gradient(currentColor, currentColor) 0 58% / 0% 1.25px no-repeat; transition: color .3s ${EASE}, background-size ${PEEK_MS}ms ${EASE}; }
.itp-row[data-status="done"] .itp-label { color: var(--itp-soft); background-size: 100% 1.25px; }
.itp-row[data-status="done"][data-fresh] .itp-label { transition: color .4s ${EASE} ${STRIKE_DELAY}ms, background-size ${STRIKE_MS}ms cubic-bezier(.65,0,.35,1) ${STRIKE_DELAY}ms; }
@media (hover: hover) {
.itp-row[data-status="done"]:hover .itp-label { color: color-mix(in oklab, currentColor 88%, transparent); background-size: 0% 1.25px; transition: color .2s ${EASE}, background-size ${PEEK_MS}ms ${EASE}; }
}
.itp-row[data-status="done"][data-peek] .itp-label { color: color-mix(in oklab, currentColor 88%, transparent); background-size: 0% 1.25px; transition: color .2s ${EASE}, background-size ${PEEK_MS}ms ${EASE}; }
.itp-more { display: grid; grid-template-rows: 0fr; transition: grid-template-rows ${OPEN_MS}ms ${EASE}; }
.itp-more[data-open="true"] { grid-template-rows: 1fr; }
.itp-more > ul { min-height: 0; overflow: hidden; }
.itp-more .itp-row { opacity: 0; transform: translateY(-6px); filter: blur(2px); transition: opacity .2s, transform .25s ${EASE}, filter .2s; }
.itp-more[data-open="true"] .itp-row { opacity: 1; transform: none; filter: none; transition: opacity .3s ${EASE}, transform .4s ${EASE}, filter .3s; }
.itp-toggle { all: unset; box-sizing: border-box; display: inline-flex; margin: 4px 0 2px 24px; padding: 3px 6px; border-radius: 8px; cursor: pointer; color: var(--itp-soft); transition: color .15s, background-color .15s; -webkit-tap-highlight-color: transparent; }
.itp-toggle:focus-visible { box-shadow: 0 0 0 2px var(--itp-soft); }
@media (hover: hover) { .itp-toggle:hover { color: color-mix(in oklab, currentColor 88%, transparent); } }
.itp-toggle span { display: inline-block; animation: itp-swap .26s ${EASE} both; }
@keyframes itp-swap { from { opacity: 0; transform: translateY(3px); filter: blur(2px); } }
.itp-empty { color: var(--itp-soft); padding: 3px 0; }
.itp-sr { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; }
@media (prefers-reduced-motion: reduce) {
.itp-spin { animation: none; }
.itp-arc, .itp-dots, .itp-disc, .itp-check, .itp-row .itp-label, .itp-more, .itp-more .itp-row { transition-duration: .15s !important; transition-delay: 0s !important; }
.itp-disc, .itp-more .itp-row { transform: none !important; filter: none !important; }
.itp-label { transition-property: color, opacity !important; }
.itp-toggle span { animation: none; }
}`;
const STATUS_TEXT: Record<TaskStatus, string> = { pending: "Not started: ", active: "In progress: ", done: "Done: " };
/** True when the text around the list is light (dark mode), so the check mark can be dark. */
function useLightText(ref: React.RefObject<HTMLElement | null>) {
const [light, setLight] = useState(false);
useEffect(() => {
const read = () => {
const c = ref.current && getComputedStyle(ref.current).color.match(/[\d.]+/g);
if (!c) return;
const [r, g, b] = c.map(Number);
setLight(0.299 * r + 0.587 * g + 0.114 * b > 140);
};
read();
const mo = new MutationObserver(read);
mo.observe(document.documentElement, { attributes: true, attributeFilter: ["class", "data-theme", "style"] });
const mq = window.matchMedia("(prefers-color-scheme: dark)");
mq.addEventListener("change", read);
return () => {
mo.disconnect();
mq.removeEventListener("change", read);
};
}, [ref]);
return light;
}
/** One task. Remembers when it has just finished, so only that strike waits for the check. */
function Row({ task, lightText, style }: { task: Task; lightText: boolean; style?: CSSProperties }) {
const { status, label } = task;
// Set during render (not in an effect), so the strike's delay is in place on the very frame the task turns done.
const [seen, setSeen] = useState(status);
const [fresh, setFresh] = useState(false);
const [peek, setPeek] = useState(false);
const touch = useRef(false);
if (seen !== status) {
setSeen(status);
setFresh(status === "done");
setPeek(false);
}
useEffect(() => {
if (!fresh) return;
const t = window.setTimeout(() => setFresh(false), STRIKE_DELAY + STRIKE_MS + 60);
return () => clearTimeout(t);
}, [fresh]);
return (
<li
className="itp-row"
data-status={status}
data-fresh={fresh ? "" : undefined}
data-peek={peek && status === "done" ? "" : undefined}
aria-current={status === "active" ? "step" : undefined}
style={style}
onPointerDown={(e) => (touch.current = e.pointerType !== "mouse")}
onClick={() => {
// Phones have no hover: a tap on a done task shows it clearly, another tap strikes it again.
if (touch.current && status === "done") setPeek((p) => !p);
}}
>
<span className="itp-icon" aria-hidden="true">
<svg className="itp-spin" viewBox="0 0 18 18" fill="none">
<circle className="itp-dots" cx="9" cy="9" r={R} strokeWidth="1.7" strokeLinecap="round" strokeDasharray={`0 ${(C / 8).toFixed(4)}`} />
<circle className="itp-arc" cx="9" cy="9" r={R} strokeWidth="1.7" strokeLinecap="round" transform="rotate(-90 9 9)" />
</svg>
<svg className="itp-done" viewBox="0 0 18 18" fill="none">
<circle className="itp-disc" cx="9" cy="9" r="8" />
<path className="itp-check" d="M5.6 9.3L7.9 11.5L12.4 6.7" stroke={lightText ? "#0a0a0a" : "#ffffff"} strokeWidth="1.7" strokeLinecap="round" strokeLinejoin="round" />
</svg>
</span>
<span className="itp-text">
<span className="itp-sr">{STATUS_TEXT[status]}</span>
<span className="itp-label">{label}</span>
</span>
</li>
);
}
export function TaskProgress({
tasks,
limit = 5,
moreLabel = (n) => `Show ${n} more`,
lessLabel = "Show less",
defaultExpanded = false,
activeColor,
emptyLabel = "No tasks yet.",
"aria-label": ariaLabel = "Tasks",
className,
style,
}: TaskProgressProps) {
const rootRef = useRef<HTMLDivElement>(null);
const lightText = useLightText(rootRef);
const [open, setOpen] = useState(defaultExpanded);
const moreId = useId();
const list = Array.isArray(tasks) ? tasks : [];
const shown = Number.isFinite(limit) && limit >= 1 ? Math.floor(limit) : 5;
const first = list.slice(0, shown);
const rest = list.slice(shown);
const key = (t: Task, i: number) => t.id ?? i;
return (
<div
ref={rootRef}
className={`itp${className ? ` ${className}` : ""}`}
style={{ ...(activeColor ? ({ "--itp-arc": activeColor } as CSSProperties) : null), ...style }}
>
<style>{CSS}</style>
{list.length === 0 ? (
<p className="itp-empty" style={{ margin: 0 }}>{emptyLabel}</p>
) : (
<ul aria-label={ariaLabel}>
{first.map((t, i) => (
<Row key={key(t, i)} task={t} lightText={lightText} />
))}
</ul>
)}
{rest.length > 0 && (
<>
<div className="itp-more" data-open={open} id={moreId} inert={!open}>
<ul aria-label={ariaLabel}>
{rest.map((t, i) => (
<Row
key={key(t, i + shown)}
task={t}
lightText={lightText}
style={{ transitionDelay: open ? `${60 + i * STAGGER}ms` : "0ms" }}
/>
))}
</ul>
</div>
<button type="button" className="itp-toggle" aria-expanded={open} aria-controls={moreId} onClick={() => setOpen((o) => !o)}>
<span key={open ? "less" : "more"}>{open ? lessLabel : moreLabel(rest.length)}</span>
</button>
</>
)}
</div>
);
}
```
Usage
Build tasks from the state your product already has, and change a task's status to move it along.
"use client";
import { TaskProgress, type Task } from "@/components/ui/task-progress";
export function SetupSteps({ step }: { step: number }) {
const names = ["Connect your store", "Import products", "Pick a theme", "Add a payment method", "Invite your team", "Go live"];
const tasks: Task[] = names.map((label, i) => ({
id: label, // stable, so each task keeps its animation
label,
status: i < step ? "done" : i === step ? "active" : "pending", // change it and the row animates
}));
return <TaskProgress tasks={tasks} aria-label="Setup steps" className="max-w-md" />;
}For a wait with no steps, a single progress bar like Tug of Work loader fits better.
How it moves
Three icons, one strike and a fold. Everything takes its color from the text around it.
A task that has not started shows a ring of eight soft dots. When it starts, a dark arc draws in over the dots and spins, once every 0.9 seconds. When it finishes, the arc closes into a full ring, a filled circle pops in with a tiny overshoot and a check draws inside it. A moment later the text fades and a thin line draws across it from left to right, line by line on wrapped text. Hover a finished task and the line pulls back while the text darkens, so you can read it; move away and it strikes again. On a phone, tap it instead. Only the first five tasks show. Show more opens the rest: the space grows with a soft landing and the rows fade in one after another. Show less folds them away. With reduced motion the arc stands still and every change is a short fade.
Props
| Prop | Default | What it does |
|---|---|---|
tasks | — | The list, in order. Each task is { id, label, status }, where status is "pending" (not started), "active" (in progress) or "done". Change a status and that row animates. |
limit | 5 | How many tasks show before the rest fold under Show more. |
moreLabel | (n) => `Show ${n} more` | Text of the button that opens the rest. It gets the number of hidden tasks. |
lessLabel | "Show less" | Text of the button that folds them away. |
defaultExpanded | false | Start with every task showing. |
activeColor | the text color | Color of the spinning arc on the task in progress. Any CSS color, including var(--…). |
emptyLabel | "No tasks yet." | Shown when the list is empty. |
aria-label | "Tasks" | Name of the list for screen readers. |
className / style | — | On the outer box. It fills the width it is given and has no background, so set a max width or a background here. |