Kobalte.v0.13.1

Progress

Show either determinate or indeterminate progress of an operation over time.

Import

ts
import { Progress } from "@kobalte/core/progress";
// or
import { Root, Label, ... } from "@kobalte/core/progress";
// or (deprecated)
import { Progress } from "@kobalte/core";
ts
import { Progress } from "@kobalte/core/progress";
// or
import { Root, Label, ... } from "@kobalte/core/progress";
// or (deprecated)
import { Progress } from "@kobalte/core";

Features

  • Exposed to assistive technology as a progress bar via ARIA.
  • Labeling support for accessibility.
  • Internationalized number formatting as a percentage or value.
  • Determinate and indeterminate progress support.

Anatomy

The progress consists of:

  • Progress: The root container for a progress bar.
  • Progress.Label: An accessible label that gives the user information on the progress.
  • Progress.ValueLabel: The accessible label text representing the current value in a human-readable format.
  • Progress.Track: The component that visually represents the progress track.
  • Progress.Fill: The component that visually represents the progress value.
tsx
<Progress>
<Progress.Label />
<Progress.ValueLabel />
<Progress.Track>
<Progress.Fill />
</Progress.Track>
</Progress>
tsx
<Progress>
<Progress.Label />
<Progress.ValueLabel />
<Progress.Track>
<Progress.Fill />
</Progress.Track>
</Progress>

Example

Loading...
80%

Usage

Custom value scale

By default, the value prop represents the current percentage of progress, as the minimum and maximum values default to 0 and 100, respectively. Alternatively, a different scale can be used by setting the minValue and maxValue props.

Loading...
50%
tsx
<Progress value={100} minValue={50} maxValue={150} class="progress">
<div class="progress__label-container">
<Progress.Label class="progress__label">Loading...</Progress.Label>
<Progress.ValueLabel class="progress__value-label" />
</div>
<Progress.Track class="progress__track">
<Progress.Fill class="progress__fill" />
</Progress.Track>
</Progress>
tsx
<Progress value={100} minValue={50} maxValue={150} class="progress">
<div class="progress__label-container">
<Progress.Label class="progress__label">Loading...</Progress.Label>
<Progress.ValueLabel class="progress__value-label" />
</div>
<Progress.Track class="progress__track">
<Progress.Fill class="progress__fill" />
</Progress.Track>
</Progress>

Custom value label

The getValueLabel prop allows the formatted value used in Progress.ValueLabel and ARIA to be replaced with a custom string. It receives the current value, min and max values as parameters.

Processing...
3 of 10 tasks completed
tsx
<Progress
value={3}
minValue={0}
maxValue={10}
getValueLabel={({ value, max }) => `${value} of ${max} tasks completed`}
class="progress"
>
<div class="progress__label-container">
<Progress.Label class="progress__label">Processing...</Progress.Label>
<Progress.ValueLabel class="progress__value-label" />
</div>
<Progress.Track class="progress__track">
<Progress.Fill class="progress__fill" />
</Progress.Track>
</Progress>
tsx
<Progress
value={3}
minValue={0}
maxValue={10}
getValueLabel={({ value, max }) => `${value} of ${max} tasks completed`}
class="progress"
>
<div class="progress__label-container">
<Progress.Label class="progress__label">Processing...</Progress.Label>
<Progress.ValueLabel class="progress__value-label" />
</div>
<Progress.Track class="progress__track">
<Progress.Fill class="progress__fill" />
</Progress.Track>
</Progress>

Progress bar fill width

We expose a CSS custom property --kb-progress-fill-width which corresponds to the percentage of progression (ex: 80%). If you are building a linear progress bar, you can use it to set the width of the Progress.Fill component in CSS.

API Reference

Progress

Progress is equivalent to the Root import from @kobalte/core/progress (and deprecated Progress.Root).

PropDescription
valuenumber
The progress value.
minValuenumber
The minimum progress value.
maxValuenumber
The maximum progress value.
indeterminateboolean
Whether the progress is in an indeterminate state.
getValueLabel(params: { value: number; min: number; max: number }) => string
A function to get the accessible label text representing the current value in a human-readable format. If not provided, the value label will be read as a percentage of the max value.
Data attributeDescription
data-progress='loading'Present when the progress is not complete (value < maxValue).
data-progress='complete'Present when the progress is complete (value === maxValue).
data-indeterminatePresent when the progress is in an indeterminate state.

Progress.Label, Progress.ValueLabel, Progress.Track and Progress.Fill shares the same data-attributes.

Rendered elements

ComponentDefault rendered element
Progressdiv
Progress.Labelspan
Progress.ValueLabeldiv
Progress.Trackdiv
Progress.Filldiv