Progress

How far a task or a goal has come: a bar or a ring — with its words and time left, what is buffered ahead, its steps as segments, and a paused or failed state that says where it stopped.

Web + MobileBetaFeedback

Web and mobile — the same component for React and React Native. Beta: its API may still change in a minor version.

Why it is here. Used by Orochia, Orazaka, krizaka.com.

When to use

For a task with a known end: an upload, a processing step, a profile to complete.
A ring with its amount in the centre for a goal: money raised, steps done.
Indeterminate (no value) for a wait of unknown length inside a layout.

When not to use

For a short, unknown wait with nothing to show.Use instead: Spinner
While the content of a page loads.Use instead: Skeleton
For the time left until a moment.Use instead: Countdown

Installation

Install

npm install @krizaka/ui @krizaka/tailwind @krizaka/tokens tailwindcss

Styles

@import "tailwindcss";
@import "@krizaka/tailwind";
@import "@krizaka/ui/tailwind.css";

Import

import { Progress } from "@krizaka/ui/progress";

Examples

An upload with its time left

showLabel and eta: the file, the percentage and the time left above the bar.

Steps

segments: 3 of 5 steps on a bar, 7 of 10 on a ring.

7/10

Buffered ahead

buffer: a player's timeline, what is loaded ahead in a lighter fill.

Paused and failed

status: striped at rest when waiting, the danger colour where it failed.

Bar

A task with a known end.

Bar sizes

sm, md, lg.

Indeterminate bar

A wait of unknown length.

Ring

A goal with its amount in the centre.

42%

$750of $1,000

Indeterminate ring

A ring without a value.

Props

A progress bar or ring: value / max, indeterminate without a value. State: data-state (loading · complete · indeterminate).

Prop	Type	Default	Description
`label`required	`string`	—	The accessible name — passed translated ("Upload", "Raised towards the goal").
`buffer`	`number`	—	How far is already available beyond the value (a video buffered ahead), between 0 and `max` — bar only.
`children`	`ReactNode`	—	A ring's centre: an amount, a percentage, an icon.
`eta`	`string`	—	The time left, in words (“About 2 min left”), shown with `showLabel` and read with the value — passed translated.
`max`	`number`	`100`	The value that means complete.
`segments`	`number`	—	Splits the bar or the ring into this many segments: the steps of a task, the parts of a goal.
`showLabel`	`boolean`	—	Shows the label above the bar, with the percentage (or `valueText`) and `eta` — bar only.
`size`	`"sm" \| "md" \| "lg"`	`md`	sm · md · lg: the bar's thickness, the ring's diameter.
`status`	`"error" \| "paused" \| "active"`	`active`	active · paused (the fill rests, striped: waiting for someone) · error (the fill turns to the danger colour where it stopped).
`value`	`number \| null`	—	How far, between 0 and `max`. `null` or absent: indeterminate (a wait of unknown length).
`valueText`	`string`	—	The value in words for assistive technology ("$420 of $1,000") — default: the percentage.
`variant`	`"bar" \| "ring"`	`bar`	bar · ring (a ring holds its `children` in the centre).

Accessibility

role="progressbar" named by label, with aria-valuenow, aria-valuemax and aria-valuetext.
Indeterminate: no value attributes; the motion stops under prefers-reduced-motion.
eta is appended to aria-valuetext (“64%, About 40 s left”); the visible header is a copy hidden from assistive technology.

Best practices

Always a label (“Upload”), translated: it names the bar.
Give valueText when the percentage is not what matters (“$420 of $1,000”).
Do not move the bar backwards: if a task restarts, say so.
A long task: showLabel and an eta — the name, the percentage and the time left read as one line, and are spoken with the value.
When it stops, say how: status="paused" (it waits for something) is not status="error" (it failed).

Generated from the code of @krizaka/ui 3.8.0: its meta.ts, its examples and its types.Edit this documentation on GitHub