Progress | NDS - Vanilla National Design System

Progress Circle

Circular indicator that scales from compact inline counters to large hero displays

% Active users

Progress Circle — Out of

Displays a value as a fraction (e.g. 3.75/5) instead of a percentage, ideal for GPA, ratings, and score displays

SGPA

Progress Line

Linear indicator with label, fill percentage, and feedback message for file uploads, form completion, and multi-step workflows

Uploading document.pdf

Processing your file...

Built-in Features

Auto-initialization

Reads data-value, data-num, and data-max on page load and sets CSS custom properties automatically.

Data-Driven Values

Set data-value on any circle or bar and the fill, percentage text, and CSS properties update reactively through a shared attribute observer.

Out-of Display

Show values as fractions like 3.75/5 using data-num and data-max. The progress fill auto-calculates from the ratio.

Scalable Sizes

Five circle sizes from compact inline counters to large hero displays, plus three bar heights, with text and icons that scale proportionally.

Status Feedback

Success and error statuses swap the percentage for a feedback icon and apply the matching color automatically.

Inline Bar Percentage

The large progress bar displays the current percentage inside the fill track, keeping the value visible without extra labels.

Smooth Transitions

Both circle and bar fills animate smoothly when the progress value changes, giving users clear visual feedback during updates.

Programmatic Control

Update values at runtime with NDS.Progress.setValue() and NDS.Progress.setOutOf(). Changes propagate through the attribute observer automatically.

Usage Guidelines

Best Practices

Use progress circles for KPI displays, dashboard stats, and completion summaries where the value itself is the focus
Use progress bars for file uploads, form completion, and any operation where the user is waiting for a process to finish
Use the out-of display (data-num + data-max) for GPA, ratings, or scores where showing the fraction is more meaningful than a percentage
Choose the large bar (nds-lg) when you want the percentage visible inside the track without additional labels
Use small or medium bars when the progress indicator sits alongside other content and should not dominate the layout
Prefer data-value over inline style="--progress-value" for setting progress. Data attributes enable reactive updates and work with the JS API
Set data-status="success" only when the operation completes. The value automatically locks to 100% and shows a feedback icon
Add a .nds-progress-label and .nds-feedback-message to the bar so users understand what is progressing and its current state
Do not use progress components for indeterminate loading states. Use the Loading component instead
For multi-step workflows with discrete stages, prefer the Stepper component over a progress bar
Use NDS.Progress.setValue() or update data-value directly to animate the fill at runtime. The CSS transition handles smooth movement automatically

Modifier Classes

Class	Applies to	Description
`nds-xs`	Circle	24px, hides percentage symbol and label text
`nds-sm`	Circle / Bar	Circle: 40px, hides label text. Bar: 4px track height, hides inline percentage
`nds-md`	Circle / Bar	Circle: 64px (default). Bar: 8px track height (default)
`nds-lg`	Circle / Bar	Circle: 120px. Bar: 16px track height with percentage inside the fill
`nds-xl`	Circle	160px large display
`nds-2xl`	Circle	200px hero display
`nds-neutral`	Circle / Bar	Neutral gray color variant

Data Attributes

Attribute	Description
`data-value`	Progress percentage (0–100). Sets `--progress-value` via JS. Has priority over inline style
`data-num`	Numerator for "out of" display (e.g. 3.75). Populates `.nds-progress-number` text and auto-calculates progress value
`data-max`	Denominator for "out of" display (e.g. 5). Populates `.nds-progress-of` text. Used with `data-num`
`data-status="success"`	Locks value to 100%, applies success color, and shows a feedback icon instead of the percentage
`data-status="error"`	Applies error color and shows the feedback icon. Value stays at its current position

CSS Custom Properties

Property	Default	Description
`--progress-value`	0	Current progress (0 to 100). Values above 100 are clamped. Update via JS to animate the fill
`--progress-size`	64px	Circle diameter. Overridden by size classes (nds-xs through nds-xl)
`--progress-color`	var(--background-primary)	Fill and stroke color for both circle and bar
`--progress-track-color`	var(--colors-neutral-100)	Background track color for the circle
`--progress-height`	8px	Bar track height. Overridden by size classes

JavaScript API

The NDS.Progress API reads data-value, data-num, and data-max attributes on initialization and observes changes reactively. For dynamically added elements, call NDS.Progress.init() to pick them up.


// ── Set progress value (circle or bar) ──────────────
const el = document.querySelector('.nds-progress-circle');
NDS.Progress.setValue(el, 80);       // Sets data-value="80", fill animates to 80%

// ── Set out-of display (circle only) ────────────────
NDS.Progress.setOutOf(el, 4.2, 5);  // Sets data-num="4.2" data-max="5"
                                     // Fill auto-calculates to 84%
                                     // Text shows "4.2" and "/5"

// ── Direct attribute updates also work ──────────────
// The shared observer picks up any data-* change
el.dataset.value = 90;              // Fill animates to 90%
el.dataset.num = 3.5;               // Recalculates from num/max

// ── Initialize after dynamic HTML ───────────────────
NDS.Progress.init();                // Scans for new elements

// ── Initialize a single element ─────────────────────
NDS.Progress.initCircle(el);        // Process one element directly