Task progress

Tracks long-running work with phases, honest progress, cancellation, and retry.

Preview

Export preview

In progress

In action

Exporting study

In progress

12s elapsed

Prepare · complete
Render · active

When to use

Use it for

Exports, uploads, background processing, and recoverable operations.

Not for

A brief loading indicator; use Spinner.

Install

Three ways in. They share one source, so the pixels match whichever you pick.

1. Import the package

npm install @noorddev/vlak-react

// once, next to your app's root
import "@noorddev/vlak-react/css";

import { TaskProgress } from "@noorddev/vlak-react";

Precompiled React and one stylesheet. No compiler to configure. Per-component imports work too: @noorddev/vlak-react/components/task-progress.

2. Vendor the source

npx @noorddev/vlak-cli add task-progress

The StyleX leaf lands in components/vlak/ with its dependencies, for your own compiler to own. See StyleX.

3. Through shadcn

npx shadcn add https://vlak.dev/r/task-progress.json

The same registry item, installed by shadcn's CLI.

CSS only

<link rel="stylesheet" href="node_modules/@noorddev/vlak/css/vlak.css" />

No React. Link vlak.css and use the markup and classes below.

React

import { TaskProgress } from "@noorddev/vlak-react";

<TaskProgress label="Exporting study" state="running" value={42} elapsedSeconds={12} phases={[{ id: "prepare", label: "Prepare", state: "complete" }, { id: "render", label: "Render", state: "active" }, { id: "package", label: "Package", state: "pending" }]} />

Props

TaskProgress

Honest long-running task state, including unknown progress and action failures.

Prop	Type	Default	Description
`label`required	`string`
`state`required	`TaskState`
`value`	`number`		Percentage, omit while the amount of work is unknown.
`phases`	`TaskPhase[]`	`[]`
`description`	`ReactNode`
`elapsedSeconds`	`number`
`remainingSeconds`	`number`
`onCancel`	`() => void \| Promise<void>`
`onRetry`	`() => void \| Promise<void>`

Also accepts HTMLAttributes<HTMLElement>.

Keyboard

Keys	Does
`Tab, Enter, Space`	Tab reaches cancel or retry when supplied; Enter or Space invokes the callback.

Accessibility

Native progress supports unknown completion when value is omitted. State changes are announced, elapsed seconds are not repeatedly announced.

Markup

<section class="rs-task-progress" aria-label="Exporting study"><h2 class="rs-task-progress-title">Exporting study</h2><p role="status">In progress</p><progress class="rs-task-progress-bar" aria-label="Export progress" max="100" value="42"></progress></section>

Classes

.rs-task-progress.rs-task-progress-title.rs-task-progress-bar.rs-task-progress-detail.rs-task-progress-phases.rs-task-progress-phase.rs-task-progress-actions

Depends on

/button