How far a task or a goal has come: a bar or a ring, determinate or indeterminate.

Web + MobileBetaFeedback

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

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@beta @krizaka/tailwind@beta @krizaka/tokens@beta tailwindcss

Styles

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

Import

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

Examples

Bar

A task with a known end.

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

export default function ProgressBar() {
  return <Progress label="Upload" value={64} />;
}

Bar sizes

sm, md, lg.

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

export default function ProgressBarSizes() {
  return (
    <div className="flex flex-col gap-4">
      <Progress label="Small" size="sm" value={30} />
      <Progress label="Medium" size="md" value={55} />
      <Progress label="Large" size="lg" value={80} />
    </div>
  );
}

Indeterminate bar

A wait of unknown length.

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

// No `value`: a wait of unknown length (still under reduced motion).
export default function ProgressBarIndeterminate() {
  return <Progress label="Processing" />;
}

Ring

A goal with its amount in the centre.

42%

$750of $1,000

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

// A ring holds its amount in the centre; `valueText` gives the words a screen reader reads.
export default function ProgressRing() {
  return (
    <div className="flex items-end gap-6">
      <Progress variant="ring" size="sm" label="Profile completed" value={40} />
      <Progress variant="ring" size="md" label="Raised" value={420} max={1000} valueText="$420 of $1,000">
        <span className="text-sm font-bold text-fg">42%</span>
      </Progress>
      <Progress variant="ring" size="lg" label="Raised towards the goal" value={750} max={1000} valueText="$750 of $1,000">
        <span className="font-display text-2xl font-black text-fg">$750</span>
        <span className="text-xs text-fg-secondary">of $1,000</span>
      </Progress>
    </div>
  );
}

Indeterminate ring

A ring without a value.

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

export default function ProgressRingIndeterminate() {
  return <Progress variant="ring" size="md" label="Loading" />;
}

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").
`children`	`ReactNode`	—	A ring's centre: an amount, a percentage, an icon.
`max`	`number`	`100`	The value that means complete.
`size`	`"sm" \| "md" \| "lg"`	`md`	sm · md · lg: the bar's thickness, the ring's diameter.
`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.

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.

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

Progress