A component that displays an indicator showing the completion progress of a task, typically displayed as a progress bar.

Progress component

Downloading Ubuntu 24.04 LTS

import * as React from 'react';
import { Progress } from 'gnome-ui/progress';
import { Download } from 'lucide-react';

export function ProgressDefault() {
  const [progress, setProgress] = React.useState(13);

  React.useEffect(() => {
    const timer = setTimeout(() => setProgress(66), 500);
    return () => clearTimeout(timer);
  }, []);

  return (
    <Progress.Root value={progress} className="flex w-full max-w-md flex-col gap-2">
      <div className="flex w-full items-center justify-between">
        <Progress.Label className="flex items-center gap-2 text-sm font-medium text-foreground">
          <Icons.Download className="size-4 text-muted-foreground" />
          Downloading Ubuntu 24.04 LTS
        </Progress.Label>
        <Progress.Value className="text-sm font-medium text-muted-foreground" />
      </div>
      <Progress.Track className="h-1.5 w-full overflow-hidden rounded-full bg-secondary">
        <Progress.Indicator className="h-full bg-primary transition-all duration-500 ease-in-out" />
      </Progress.Track>
    </Progress.Root>
  );
}

Anatomy

import { Progress } from 'gnome-ui/progress';

<Progress.Root>
  <Progress.Label />
  <Progress.Value />
  <Progress.Track>
    <Progress.Indicator />
  </Progress.Track>
</Progress.Root>

Examples

Indeterminate

When the exact progress is unknown, pass value={null} to the root component. This activates the data-[state="indeterminate"] attribute, which you can use to apply custom pulsing or sliding animations.

Progress component

Syncing repositories...

import * as React from 'react';
import { Progress } from 'gnome-ui/progress';
import { RefreshCw } from 'lucide-react';

export function ProgressIndeterminate() {
  return (
    <Progress.Root value={null} className="flex w-full max-w-md flex-col gap-2">
      <div className="flex w-full items-center justify-between">
        <Progress.Label className="flex items-center gap-2 text-sm font-medium text-foreground">
          <Icons.RefreshCw className="size-4 animate-spin text-muted-foreground" />
          Syncing repositories...
        </Progress.Label>
      </div>
      <Progress.Track className="h-1.5 w-full overflow-hidden rounded-full bg-secondary">
        <Progress.Indicator className="h-full bg-primary transition-all duration-500 ease-in-out data-[state=indeterminate]:w-full data-[state=indeterminate]:animate-pulse" />
      </Progress.Track>
    </Progress.Root>
  );
}

Custom Limits and Values

You can change the max value for use cases like step tracking. If you want custom text instead of percentages, you can omit <Progress.Value> and render your own string.

Progress component

Uploading filesStep 3 of 5

import * as React from 'react';
import { Progress } from 'gnome-ui/progress';
import { UploadCloud } from 'lucide-react';

export function ProgressSteps() {
  const step = 3;
  const totalSteps = 5;
  
  return (
    <Progress.Root value={step} max={totalSteps} className="flex w-full max-w-md flex-col gap-2">
      <div className="flex w-full items-center justify-between">
        <Progress.Label className="flex items-center gap-2 text-sm font-medium text-foreground">
          <Icons.UploadCloud className="size-4 text-muted-foreground" />
          Uploading files
        </Progress.Label>
        <span className="text-sm font-medium text-muted-foreground">
          Step {step} of {totalSteps}
        </span>
      </div>
      <Progress.Track className="h-1.5 w-full overflow-hidden rounded-full bg-secondary">
        <Progress.Indicator className="h-full bg-[oklch(0.55_0.12_250)] transition-all duration-500 ease-in-out" />
      </Progress.Track>
    </Progress.Root>
  );
}

ProgressIndicator

Visualizes the completion status of the task. Renders a <div> element.

Documentation: Base UI Progress

API reference

Root

Groups all parts of the progress bar and provides the task completion status to screen readers. Renders a <div> element.

Root Props:

Prop	Type	Default	Description
value	`number \| null`	`null`	The current value. The component is indeterminate when value is `null`.
aria-valuetext	`string`	-	A string value that provides a user-friendly name for `aria-valuenow`, the current value of the meter.
getAriaValueText	`((formattedValue: string \| null, value: number \| null) => string)`	-	Accepts a function which returns a string value that provides a human-readable text alternative for the current value of the progress bar.
locale	`Intl.LocalesArgument`	-	The locale used by `Intl.NumberFormat` when formatting the value. Defaults to the user's runtime locale.
min	`number`	`0`	The minimum value.
max	`number`	`100`	The maximum value.
format	`Intl.NumberFormatOptions`	-	Options to format the value.
className	`string \| ((state: Progress.Root.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component’s state.
style	`CSSProperties \| ((state: Progress.Root.State) => CSSProperties \| undefined)`	-	-
render	`ReactElement \| ((props: HTMLProps, state: Progress.Root.State) => ReactElement)`	-	Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a `ReactElement` or a function that returns the element to render.

Root Data Attributes:

Attribute	Type	Description
data-complete	-	Present when the progress has completed.
data-indeterminate	-	Present when the progress is in interminate state.
data-progressing	-	Present while the progress is progressing.

Track

Contains the progress bar indicator. Renders a <div> element.

Track Props:

Prop	Type	Default	Description
className	`string \| ((state: Progress.Root.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component’s state.
style	`CSSProperties \| ((state: Progress.Root.State) => CSSProperties \| undefined)`	-	-
render	`ReactElement \| ((props: HTMLProps, state: Progress.Root.State) => ReactElement)`	-	Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a `ReactElement` or a function that returns the element to render.

Track Data Attributes:

Attribute	Type	Description
data-complete	-	Present when the progress has completed.
data-indeterminate	-	Present when the progress is in interminate state.
data-progressing	-	Present while the progress is progressing.

Indicator

Visualizes the completion status of the task. Renders a <div> element.

Indicator Props:

Prop	Type	Default	Description
className	`string \| ((state: Progress.Root.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component’s state.
style	`CSSProperties \| ((state: Progress.Root.State) => CSSProperties \| undefined)`	-	-
render	`ReactElement \| ((props: HTMLProps, state: Progress.Root.State) => ReactElement)`	-	Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a `ReactElement` or a function that returns the element to render.

Indicator Data Attributes:

Attribute	Type	Description
data-complete	-	Present when the progress has completed.
data-indeterminate	-	Present when the progress is in interminate state.
data-progressing	-	Present while the progress is progressing.

Value

A text label displaying the current value. Renders a <span> element.

Value Props:

Prop	Type	Default	Description
children	`((formattedValue: string \| null, value: number \| null) => ReactNode) \| null`	-	-
className	`string \| ((state: Progress.Root.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component’s state.
style	`CSSProperties \| ((state: Progress.Root.State) => CSSProperties \| undefined)`	-	*
render	`ReactElement \| ((props: HTMLProps, state: Progress.Root.State) => ReactElement)`	-	Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a `ReactElement` or a function that returns the element to render.

Value Data Attributes:

Attribute	Type	Description
data-complete	-	Present when the progress has completed.
data-indeterminate	-	Present when the progress is in interminate state.
data-progressing	-	Present while the progress is progressing.

Label

An accessible label for the progress bar. Renders a <span> element.

Label Props:

Prop	Type	Default	Description
className	`string \| ((state: Progress.Root.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component’s state.
style	`CSSProperties \| ((state: Progress.Root.State) => CSSProperties \| undefined)`	-	-
render	`ReactElement \| ((props: HTMLProps, state: Progress.Root.State) => ReactElement)`	-	Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a `ReactElement` or a function that returns the element to render.

Label Data Attributes:

Attribute	Type	Description
data-complete	-	Present when the progress has completed.
data-indeterminate	-	Present when the progress is in interminate state.
data-progressing	-	Present while the progress is progressing.

Progress

On this page