Progress

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

Import

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.

<Progress>
  <Progress.Label />
  <Progress.ValueLabel />
  <Progress.Track>
    <Progress.Fill />
  </Progress.Track>
</Progress>

Example

import { Progress } from "@kobalte/core/progress";

export function BasicExample() {
  return (
    <Progress value={80} class={style.progress}>
      <div class={style["progress__label-container"]}>
        <Progress.Label class={style.progress__label}>
          Loading...
        </Progress.Label>
        <Progress.ValueLabel class={style["progress__value-label"]} />
      </div>
      <Progress.Track class={style.progress__track}>
        <Progress.Fill class={style.progress__fill} />
      </Progress.Track>
    </Progress>
  );
}

.progress {
  display: flex;
  flex-direction: column;
  gap: 2px;
  width: 300px;
}

.progress__label-container {
  display: flex;
  justify-content: space-between;
}

.progress__label,
.progress__value-label {
  color: hsl(240 4% 16%);
  font-size: 14px;
}

.progress__track {
  height: 10px;
  background-color: hsl(240 6% 90%);
}

.progress__fill {
  background-color: hsl(200 98% 39%);
  height: 100%;
  width: var(--kb-progress-fill-width);
  transition: width 250ms linear;
}

.progress__fill[data-progress="complete"] {
  background-color: #16a34a;
}

[data-theme*="dark"] .progress__label,
[data-theme*="dark"] .progress__value-label {
  color: hsl(0 100% 100% / 0.9);
}

[data-theme*="dark"] .progress__track {
  background-color: hsl(240 5% 26%);
}

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.

<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.

<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).

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

Rendered elements