Displays an indicator showing the completion progress of a task, typically displayed as a progress bar.
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { progressClass } from '#components/ui/progress.ts';
// shadcn's demo starts at 13 and moves to 66 half a second after mount. A
// static demo shows the value the reader sees, 66.
export default function ProgressDemo() {
return html`
<progress data-slot="progress" value="66" max="100" aria-label="Progress" class=${cn(progressClass(), 'w-[60%]')}></progress>
`;
}
View Code
Installation
Copy and paste the following code into your project.
/**
* Progress: progress bar. Tier-1 class helper over the native
* `<progress>` element. The native element supplies the `progressbar`
* role and `aria-valuenow` automatically from its `value` / `max`
* attributes, so no JS, no custom element.
*
* shadcn parity:
* Progress → progressClass() (visual: 2px track + animated fill,
* styled via `::-webkit-progress-bar`,
* `::-webkit-progress-value`, and
* `::-moz-progress-bar`)
*
* A11y (required for accessible output): give the <progress> an accessible
* name with aria-label (or a <label for>), e.g. aria-label="Upload
* progress". The native element supplies the role and value; only the name
* is the author's responsibility.
*
* Design tokens used: --primary.
*
* @example
* ```html
* <progress value="42" max="100" class=${progressClass()}></progress>
*
* <!-- Indeterminate state, with no value attribute. -->
* <progress class=${progressClass()}></progress>
* ```
*/
/**
* Class for the native `<progress>` element. The track + fill colours
* come from Tailwind utilities. The browser handles the actual bar
* rendering through the `::-webkit-progress-value` and
* `::-moz-progress-bar` pseudo-elements. We expose them via the
* `[&::-webkit-progress-value]:bg-primary` and
* `[&::-moz-progress-bar]:bg-primary` Tailwind variants.
*
* Indeterminate state (no `value` attribute on the element) gets a
* pulse animation via `:indeterminate { animate-pulse }`.
*/
export const progressClass = (): string =>
[
// Reset native styling. WebKit / Blink draw a default 3D bar that we
// strip via appearance-none + classic clear of the border. The TRACK
// colour is the style's (`.cn-progress` sets the element's background),
// so the native track pseudo-element is transparent and shows it, and
// overflow-hidden clips the fill to the style's corners. A colour here
// would sit in the utilities layer and beat every style.
'block h-2 overflow-hidden rounded-full bg-primary/20 w-full',
'appearance-none overflow-hidden border-0 [&::-webkit-progress-bar]:bg-transparent',
// Bar fill: blink/webkit + firefox both via Tailwind 4's arbitrary-
// pseudo variant. Smooth animation on width change matches shadcn.
"[&::-webkit-progress-value]:bg-primary [&::-webkit-progress-value]:transition-all",
"[&::-moz-progress-bar]:bg-primary",
// Indeterminate state animates the track itself (no value -> no bar
// to color, so we pulse the bg).
'indeterminate:animate-pulse',
].join(' ');
Update the import paths to match your project setup.
Usage
import { progressClass } from '#components/ui/progress.ts';
<progress value="33" max="100" aria-label="Progress" class=${progressClass()}></progress>
Label
Use a Field to add a label to the progress bar, linked by the for and id pair.
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { fieldClass, fieldLabelClass } from '#components/ui/field.ts';
import { progressClass } from '#components/ui/progress.ts';
export default function ProgressWithLabel() {
return html`
<div role="group" data-slot="field" data-orientation="vertical" class=${cn(fieldClass(), 'w-full max-w-sm')}>
<label data-slot="field-label" for="progress-upload" class=${fieldLabelClass()}>
<span>Upload progress</span>
<span class="ml-auto">66%</span>
</label>
<progress data-slot="progress" id="progress-upload" value="66" max="100" class=${progressClass()}></progress>
</div>
`;
}
View Code
Controlled
A progress bar that can be controlled by a slider.
import { html } from '@webjsdev/core';
import { progressClass } from '#components/ui/progress.ts';
import { sliderClass } from '#components/ui/slider.ts';
// shadcn's demo keeps the bar and the slider in step through React state.
// In an app, set the bar's value from the slider's ui-value-change event
// (see the Controlled section); this preview shows both at the start value.
export default function ProgressControlled() {
return html`
<div class="flex w-full max-w-sm flex-col gap-4">
<progress data-slot="progress" value="50" max="100" aria-label="Progress" class=${progressClass()}></progress>
<ui-slider>
<input type="range" min="0" max="100" step="1" value="50" aria-label="Value" class=${sliderClass()}>
</ui-slider>
</div>
`;
}
View Code
The bar is a native <progress>, so setting its value is the whole update. Listen for the slider's ui-value-change event and write the value across:
const slider = document.querySelector('ui-slider');
const bar = document.querySelector('progress');
slider.addEventListener('ui-value-change', (event) => {
bar.value = event.detail.value[0];
});
RTL
To enable RTL support, see the RTL configuration guide.
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { fieldClass, fieldLabelClass } from '#components/ui/field.ts';
import { progressClass } from '#components/ui/progress.ts';
// shadcn's demo switches language with a selector; the page shows its
// default, Arabic, with Arabic numerals. shadcn rotates its bar under rtl
// because Radix draws it with divs; a native <progress> already fills from
// the right in a right-to-left page.
const translations = {
en: { dir: 'ltr', values: { label: 'Upload progress' } },
ar: { dir: 'rtl', values: { label: 'تقدم الرفع' } },
he: { dir: 'rtl', values: { label: 'התקדמות העלאה' } },
};
const ARABIC_NUMERALS = ['٠', '١', '٢', '٣', '٤', '٥', '٦', '٧', '٨', '٩'];
const toArabicNumerals = (num: number) =>
num.toString().split('').map((digit) => ARABIC_NUMERALS[Number(digit)]).join('');
export default function ProgressRtl() {
const { dir, values: t } = translations.ar;
return html`
<div role="group" data-slot="field" data-orientation="vertical" dir=${dir} class=${cn(fieldClass(), 'w-full max-w-sm')}>
<label data-slot="field-label" for="progress-upload-rtl" class=${fieldLabelClass()}>
<span>${t.label}</span>
<span class="ms-auto">${toArabicNumerals(66)}%</span>
</label>
<progress data-slot="progress" id="progress-upload-rtl" value="66" max="100" class=${progressClass()}></progress>
</div>
`;
}
View Code
API Reference
progressClass
progressClass() returns the classes for a native <progress> element. It takes no options. The element supplies the progressbar role and its value to assistive technology on its own, so the one thing to add is an accessible name, an aria-label or a <label for>.
Leave value off for the indeterminate state, which pulses.