Skip to content
WebJs
Menu

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

pnpm dlx @webjsdev/ui add progress

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

AttributeTypeDefault
valuenumber
maxnumber1

Leave value off for the indeterminate state, which pulses.