Skip to content

shadcn.io is an independent project built on shadcn/ui

Components

Free

Progress for Solid

A progress bar for Solid on Ark UI that fills from the value you pass, for uploads and numbered steps, with an optional label and percent.

On this page9 sections
UI library: Ark UI

A progress bar shows how far a task with a known end has gotten: an upload, an import, the third of five setup steps. It fills from the value you pass and redraws when that number changes. It never watches the request itself.

When there's no number to report, a Spinner is the honest choice. For a ring that fits a tight corner, use Circular Progress, and when people should set the number themselves, a Slider.

Preview width

Installation

Sign in to get your install command
Free with an account. It carries your token, so the CLI installs everything in one go.

Anatomy

Progress anatomy: root, label, value, track, indicator

Usage

import { useEffect, createSignal } from "react";
import { Progress } from "@/components/ui/progress";
const ProgressDemo = () => {
  const [progress, setProgress] = createSignal(13);

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

  return <Progress aria-label="Loading" class="w-[60%]" value={progress} />;
};

The timer stands in for real work: half a second after mount it moves value from 13 to 66, and the fill slides to match. In your app the number comes from the upload or the job that reports it. With no visible label, aria-label gives the bar its name.

Accessibility

The element with the progressbar role is the track that Progress renders inside itself, with aria-valuenow, aria-valuemin and aria-valuemax. A ProgressLabel names it through aria-labelledby, and an aria-label or aria-labelledby passed to Progress goes to the track too. With none of them, Ark UI names the bar by its value text, such as "56%" or, while it's indeterminate, "loading...". ProgressValue is a polite live region, which a screen reader reads again each time the number changes.

Demos

Label

An upload bar at 56%, with ProgressLabel reading "Upload progress" on one side and ProgressValue printing the percent on the other, both inside Progress. Use it when the page runs more than one task, or the bar sits far from the thing it measures. The label also becomes the bar's name for screen readers.

Preview width

Controlled

A bar at 50% with a Slider under it that writes into the same state, so dragging the thumb moves the fill. The slider stands in for the real source. In an app, value comes from an upload's progress events or from the step a setup flow is on. Reach for this pattern whenever the work can report how far it has gotten.

Preview width

RTL

The upload bar with an Arabic label and dir set to rtl on Progress. On Ark UI that attribute reaches only the root, so the label and percent swap sides while the track keeps the locale's left-to-right direction and fills from the left. Wrap the bar in a Direction provider set to right to left, and the fill grows from the right edge.

Preview width

FAQ

How do I update a Progress bar from a file upload in Solid?

Keep the percent in state and pass it as value: the bar redraws on every change and never reads the request itself. For an upload, XMLHttpRequest reports bytes sent through upload.onprogress, and loaded / total * 100 is the number to store. fetch has no upload progress event, so a bar driven by it can only jump from start to finish.

Pass a number from the first render. With no value, Ark UI starts the bar halfway between min and max.

How do I show an indeterminate Progress bar when I don't know how long it will take?

Pass null as value. The bar drops aria-valuenow, its value text becomes "loading..." (the name it falls back on without a label), and the root and indicator get data-state set to indeterminate.

The indicator then fills the whole track and pulses, so the bar reads as busy rather than empty or finished. The pulse is a fade, not movement, so it keeps running under reduced motion. For another look, change the indicator's classes for that state in components/ui/progress, or show a Spinner, which says "working" without a number.

How do I count steps instead of percent with the Ark UI Progress?

Set max on Progress to the number of steps and pass the current step as value: 3 with a max of 5 fills 60% of the track. Add min when the count doesn't start at 0. ProgressValue still prints a percent unless you give it content of its own, such as "3 of 5", which replaces the number.

How do I change what screen readers hear for the Ark UI Progress?

Pass translations with a value function, which receives the value, min, max and percent and returns the value text, "56%" by default. Ark UI sets that text as the bar's aria-label, which screen readers hear only when no ProgressLabel, aria-label or aria-labelledby names the bar, so return the task along with the number, such as "Upload, 56%".

With a ProgressLabel, the bar is read by its label and aria-valuenow. To put the number in words there, pass Progress an aria-label that carries both, such as "Upload, 3 of 5 files", which names the bar in the label's place. The visible ProgressValue ignores both, so change it through its own content.

How do I show a label and the percentage next to the Progress bar?

Put ProgressLabel and ProgressValue inside Progress, ahead of the track it renders for you, as the Label demo does. The root is a flex row that wraps, so the two share the first line with the value pushed to the far end, and the track takes the full width beneath them.

ProgressLabel also becomes the bar's accessible name, so it needs no aria-label.

How do I change the color or height of a Progress bar?

Progress renders its track and indicator for you, so reach them from the classes you pass to Progress, matching their data-slot. *:data-[slot=progress-track]:h-3 makes the track taller, and **:data-[slot=progress-indicator]:bg-emerald-500 recolors the fill. The first selector matches direct children only, and the indicator sits one level deeper, inside the track.

For a look every bar in the app should share, edit ProgressTrack and ProgressIndicator in components/ui/progress, which is your code once installed.

What happens when a Progress value goes past max?

Progress clamps it between min and max before Ark UI sees it, since Ark UI throws an error for a first value outside them and passes a later one through as it is. A value above max fills the whole track and reports max to screen readers, and one below min leaves it empty. Nothing breaks, but a bar sitting at 100% while work goes on points at max and value counting different things, such as kilobytes against bytes.

When should I use a Slider or a Circular Progress instead of a Progress bar?

Progress reports a number your code sets, and nobody can move it. When people should choose the value, such as a volume or a price ceiling, use a Slider, which takes focus and answers to the arrow keys.

Circular Progress shows the same kind of value as a ring, for a card corner or a button where a full-width bar won't fit. A Spinner covers work with no amount to measure, like waiting on a server response.

API Reference

Progress

<div> data-slot="progress"

PropType
value?number | null

The controlled value of the progress bar.

Type
number | null
defaultValue?number | null

The initial value of the progress bar when rendered. Use when you don't need to control the value of the progress bar.

Type
number | null
Default
50
onValueChange?(details: ValueChangeDetails) → void

Callback fired when the value changes.

Type
(details: ValueChangeDetails) → void
Parameters

details – { value: number | null }

Returns
void
dir?"ltr" | "rtl"

The document's text/writing direction.

Type
"ltr" | "rtl"
Default
"ltr"
formatOptions?Intl.NumberFormatOptions

The options to use for formatting the value.

Default
{ style: "percent" }
id?string

The unique identifier of the machine.

ids?object

The ids of the elements in the progress bar. Useful for composition.

Type
{ root?: string; track?: string; label?: string; circle?: string }
locale?string

The locale to use for formatting the value.

Default
"en-US"
max?number

The maximum allowed value of the progress bar.

Default
100
min?number

The minimum allowed value of the progress bar.

Default
0
orientation?"horizontal" | "vertical"

The orientation of the element.

Type
"horizontal" | "vertical"
Default
"horizontal"
translations?object

The localized messages to use.

Type
{ value?: (details: ValueTranslationDetails) → string }
asChild?(props: ParentProps) => JSX.Element

Render your own element: a function that gets the part's props to spread on it.

Type
(props: ParentProps) => JSX.Element
class?string

Merged with the part's classes.

AttributeType
data-max?string
data-orientation?string

The orientation of the progress.

data-state"indeterminate" | "loading" | "complete"

"indeterminate", "loading" or "complete".

Type
"indeterminate" | "loading" | "complete"
data-value?string

The value of the item.

CSS variableType
--circumferencestring

The circumference value for the root.

--offsetstring

The offset position of the element.

--percentstring

The percent value for the root.

--radiusstring

The border radius value.

ProgressLabel

<span> data-slot="progress-label"

PropType
asChild?(props: ParentProps) => JSX.Element

Render your own element: a function that gets the part's props to spread on it.

Type
(props: ParentProps) => JSX.Element
class?string

Merged with the part's classes.

AttributeType
data-orientation?string

The orientation of the label.

ProgressTrack

<div> data-slot="progress-track"

PropType
asChild?(props: ParentProps) => JSX.Element

Render your own element: a function that gets the part's props to spread on it.

Type
(props: ParentProps) => JSX.Element
class?string

Merged with the part's classes.

AttributeType
data-max?string
data-orientation?string

The orientation of the track.

data-state"indeterminate" | "loading" | "complete"

"indeterminate", "loading" or "complete".

Type
"indeterminate" | "loading" | "complete"

ProgressIndicator

<div> data-slot="progress-indicator"

PropType
asChild?(props: ParentProps) => JSX.Element

Render your own element: a function that gets the part's props to spread on it.

Type
(props: ParentProps) => JSX.Element
class?string

Merged with the part's classes.

AttributeType
data-orientation?string

The orientation of the range.

data-state"indeterminate" | "loading" | "complete"

"indeterminate", "loading" or "complete".

Type
"indeterminate" | "loading" | "complete"

ProgressValue

<span> data-slot="progress-value"

PropType
asChild?(props: ParentProps) => JSX.Element

Render your own element: a function that gets the part's props to spread on it.

Type
(props: ParentProps) => JSX.Element
class?string

Merged with the part's classes.

ProgressRange

PropType
asChild?(props: ParentProps) => JSX.Element

Render your own element: a function that gets the part's props to spread on it.

Type
(props: ParentProps) => JSX.Element

useProgress

PropType
value?number | null

The controlled value of the progress bar.

Type
number | null
defaultValue?number | null

The initial value of the progress bar when rendered. Use when you don't need to control the value of the progress bar.

Type
number | null
Default
50
onValueChange?(details: ValueChangeDetails) → void

Callback fired when the value changes.

Type
(details: ValueChangeDetails) → void
Parameters

details – { value: number | null }

Returns
void
formatOptions?Intl.NumberFormatOptions

The options to use for formatting the value.

Default
{ style: "percent" }
id?string

The unique identifier of the machine.

ids?object

The ids of the elements in the progress bar. Useful for composition.

Type
{ root?: string; track?: string; label?: string; circle?: string }
locale?string

The locale to use for formatting the value.

Default
"en-US"
max?number

The maximum allowed value of the progress bar.

Default
100
min?number

The minimum allowed value of the progress bar.

Default
0
orientation?"horizontal" | "vertical"

The orientation of the element.

Type
"horizontal" | "vertical"
Default
"horizontal"
translations?object

The localized messages to use.

Type
{ value?: (details: ValueTranslationDetails) → string }