PettyUI/.firecrawl/kobalte.dev-docs-core-components-progress.md

Progress

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

Import

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

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

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

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

Example

Loading...

80%

index.tsxstyle.css

Copytsx
import { Progress } from "@kobalte/core/progress";
import "./style.css";

function App() {
  return (
    <Progress value={80} 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>
  );
}

Copytsx
import { Progress } from "@kobalte/core/progress";
import "./style.css";

function App() {
  return (
    <Progress value={80} 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>
  );
}

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%

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

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

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

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

Prop	Description
value	number The progress value.
minValue	number The minimum progress value.
maxValue	number The maximum progress value.
indeterminate	boolean 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 attribute	Description
data-progress='loading'	Present when the progress is not complete (value < maxValue).
data-progress='complete'	Present when the progress is complete (value === maxValue).
data-indeterminate	Present when the progress is in an indeterminate state.

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

Rendered elements

Component	Default rendered element
Progress	div
Progress.Label	span
Progress.ValueLabel	div
Progress.Track	div
Progress.Fill	div

Previous←PopoverNextRadio Group→