Progress Bar - API Reference

Quick Start

Add a progress bar to your page in seconds using data attributes:

Key Features

Multiple Shapes

Horizontal, vertical, circular, gauge

Rich Colors

8 variants + gradients

Animations

Stripes, pulse, glow, shimmer

Milestones

Visual markers at key points

Thresholds

Auto color change at levels

Segments

Stacked multi-value bars

Animate on View

Count-up when scrolled into view

Accessible

Full ARIA support

Data Attributes API

Configure progress bars entirely through HTML data attributes:

Core Attributes

Attribute	Type	Default	Description
`data-rsl-progress`	flag	-	Required. Marks element as a progress bar.
`data-value`	number	0	Current progress value.
`data-min`	number	0	Minimum value.
`data-max`	number	100	Maximum value.
`data-buffer`	number	-	Buffer value (for streaming/video style).

Appearance Attributes

Attribute	Values	Description
`data-variant`	primary, secondary, success, warning, danger, info, dark, light	Color variant.
`data-size`	xs, sm, md, lg, xl	Size variant.
`data-shape`	horizontal, vertical, circular, gauge, steps	Shape type.
`data-label`	inside, outside, floating, hidden	Label position.
`data-label-format`	string	Format string: `{value}`, `{percent}`, `{max}`, `{min}`

Animation Attributes

Attribute	Type	Description
`data-striped`	flag	Add diagonal stripe pattern.
`data-animated`	flag	Animate the stripes.
`data-indeterminate`	flag	Show indeterminate/loading state.
`data-glow`	flag	Add glow effect.
`data-pulse`	flag	Add pulse animation.
`data-animate-on-view`	flag	Animate from 0 when scrolled into view.
`data-duration`	number	Animation duration in ms (default: 1000).

Advanced Attributes

Attribute	Type	Description
`data-thresholds`	JSON	Auto color change: `{"warning": 50, "danger": 80}`
`data-milestones`	JSON	Milestone markers: `[{"value": 25, "label": "Q1"}]`
`data-segments`	JSON	Stacked segments: `[{"value": 30, "color": "success"}]`
`data-steps`	number	Number of discrete steps (for step shape).
`data-show-value`	flag	Show step numbers (for step shape).

CSS Classes

Classes are auto-applied based on data attributes, but can also be used directly:

Class	Description
`.rsl-progress`	Base progress bar class.
`.rsl-progress-{variant}`	Color variant (primary, success, etc.).
`.rsl-progress-{size}`	Size variant (xs, sm, md, lg, xl).
`.rsl-progress-striped`	Diagonal stripe pattern.
`.rsl-progress-animated`	Animate stripes.
`.rsl-progress-indeterminate`	Indeterminate loading state.
`.rsl-progress-circular`	Circular/radial shape.
`.rsl-progress-gauge`	Semi-circular gauge shape.
`.rsl-progress-vertical`	Vertical orientation.
`.rsl-progress-steps`	Discrete step progress.
`.rsl-progress-stacked`	Stacked segments.
`.rsl-progress-glow`	Glow effect.
`.rsl-progress-pulse`	Pulse animation.
`.rsl-progress-gradient-{name}`	Gradient backgrounds (primary, success, fire, ocean, rainbow).

JavaScript API

Full programmatic control via RSL.Progress:

Method	Parameters	Description
`RSL.Progress.init()`	-	Initialize all progress bars on page.
`RSL.Progress.create(element, options)`	element, options?	Create/initialize a single progress bar.
`RSL.Progress.setValue(el, value, animate)`	element, number, boolean?	Set progress value. Animate defaults to true.
`RSL.Progress.getValue(el)`	element	Get current value.
`RSL.Progress.animate(el, to, duration, cb)`	element, number, ms?, callback?	Animate value from current to target.
`RSL.Progress.increment(el, amount)`	element, number?	Increment value (default: 1).
`RSL.Progress.decrement(el, amount)`	element, number?	Decrement value (default: 1).
`RSL.Progress.setBuffer(el, value)`	element, number	Set buffer value.
`RSL.Progress.setIndeterminate(el, bool)`	element, boolean	Toggle indeterminate state.
`RSL.Progress.setSegments(el, segments)`	element, array	Set stacked segments.
`RSL.Progress.setThresholds(el, thresholds)`	element, object	Set threshold configuration.
`RSL.Progress.reset(el)`	element	Reset to minimum value.
`RSL.Progress.complete(el)`	element	Set to maximum value.

Events

Event	Detail	Description
`rsl-progress-change`	{ value, percent, max, min }	Fired when value changes.

// Get progress bar element
const progress = document.querySelector('[data-rsl-progress]');

// Set value with animation
RSL.Progress.setValue(progress, 75);

// Animate from current to target over 2 seconds
RSL.Progress.animate(progress, 100, 2000, () => {
    console.log('Complete!');
});

// Listen for changes
progress.addEventListener('rsl-progress-change', (e) => {
    console.log('Value:', e.detail.value, 'Percent:', e.detail.percent);
});

Accessibility

ARIA Support: Progress bars automatically include role="progressbar", aria-valuenow, aria-valuemin, and aria-valuemax attributes.

Screen Readers: Progress values are announced when they change.
Reduced Motion: Animations are disabled when prefers-reduced-motion: reduce is set.
High Contrast: Adapts to high contrast mode preferences.
Labels: Use aria-label or aria-labelledby for context.


File Upload Progress

Next Steps

See Examples

View examples.html for comprehensive demos

Try the Playground

Test features in playground.html

Explore Components

Browse all RSL components