On this page
@addTagHelper *, Webority.Ui.RazorTones
Pick the tone by what the bar means, so a warning bar and a failed upload read differently at a glance.
A visible label
The label is always the accessible name for the bar; show it as text above the bar when readers need the figure.
Any scale
Pass the real total as max, so a bar of 30 of 60 credits needs no conversion to percent.
Striped and animated
Striped shows a task is in progress, and animated says it is still running; use them only while work continues.
Indeterminate
Use an indeterminate bar when the layout needs a bar shape but the amount is unknown; otherwise use a spinner.
Compact size
Use the thin size in a table row or inline, where a full-height bar would crowd the line.
Every option
Every value of every prop, one cell each.
tone: all six
tone="primary"tone="info" (default)tone="success"tone="warning"tone="danger"tone="neutral"size: both
size="md" (default)size="sm"label / show-label
(no label)label (accessible name only)label + show-labelshow-label with a long label (wraps above the bar)striped / animated
(default, flat fill)stripedanimated (implies striped)striped="false" animated (still implies striped)value / max: clamping and non-percent scales
value="0" (default, empty track)value="100" max="100" (full)value="150" max="100" (clamps to 100%)value="-20" max="100" (clamps to 0%)value="30" max="60" (non-100 total)indeterminate
indeterminateindeterminate show-label (label dropped from the bar, kept for a11y)indeterminate size="sm"className: extra classes
class="w-50" (extra classes on the track)Guidance
What to do, and what to avoid.
Use it when
- The task has a known total and a real, changing amount completed: an upload, an import, a quota.
- You can compute a percentage (or a value and max pair) at any moment during the wait.
- Showing how much is left is genuinely useful to the reader, not just decoration.
Reach for something else when
- There is no known amount or duration: it is just "working". → AppSpinner
- Content with a known shape is loading, not a quantified task. → AppSkeleton
- A button is submitting a single request. → AppButton
Real amounts, not fake progress
A real value with a label that states the actual amount, not just a bare percentage.
A progress bar pinned at 100% (or any fixed value) to fake a spinner. That is AppSpinner's job.
Reference
Try every prop, read the full list, and check keyboard and screen reader behaviour.
9 props. The 5 most used come first.
Used on most screens 5 props
| Prop | Type | Default | Description |
|---|---|---|---|
| valuedefault 0 | number | 0 | The current amount from 0 to max, clamped into range. Ignored when indeterminate. |
| maxdefault 100 | number | 100 | The amount that counts as complete. |
| tonedefault info | primary | info | success | warning | danger | neutral | info | The fill colour. |
| sizedefault md | sm | md | md | The bar thickness. sm is a thin 4px bar for inline or table use. |
| labeldefault - | string | - | The accessible name of the bar. It is also shown above the bar when showLabel is set. |
Less common 4 props
| Prop | Type | Default | Description |
|---|---|---|---|
| show-labeldefault false | bool | false | Shows the label text above the bar. Ignored when indeterminate. |
| stripeddefault false | bool | false | A diagonal stripe overlay. |
| animateddefault false | bool | false | Animates the stripes, which implies striped. |
| indeterminatedefault false | bool | false | An unknown-duration sweep that drops the value and the label. |
Screen reader
3 notes- The bar has role progressbar with aria-valuemin 0, aria-valuemax and aria-valuenow, and label is its accessible name.
- An indeterminate bar leaves out aria-valuenow, as ARIA requires when the value is unknown.
- The label text shown above the bar is hidden from assistive technology, because label already names the bar.
Do and avoid
1 pairsReal amounts, not fake progress
A real value with a label that states the actual amount, not just a bare percentage.
A progress bar pinned at 100% (or any fixed value) to fake a spinner. That is AppSpinner's job.