Progress
Progress
Bit.BlazorUIProgressIndicatorProgressBarSpinner
A bar or a ring that reports how far along an operation is - an upload, an import, a page of results being fetched - or, in its indeterminate form, that something is still running when nobody can say how far. It draws that as a horizontal or vertical bar, a closed ring or a gauge with a gap cut out of it, with a label and a description, a percentage readout that can sit beside the bar, above it or on it, a buffered second value behind the main one, optional segments, and the usual look-and-feel set of color, size, thickness, rounded ends and stripes. It tells assistive technology what it is worth - as a percentage, or in the unit the operation is actually counted in - reports itself as a meter where the number is a measurement rather than progress, and can announce its own advance as it happens.
Notes
A progress indicator is announced as a progressbar,
and that role requires a name. Give it a Label where one belongs on the page - the label is
referenced by the bar rather than repeated into it - or an AriaLabel where the surrounding text
already says what is loading and a visible label would only duplicate it.
Prefer a determinate bar wherever a number is available: it is the difference between "this is working"
and "this is stuck". Reach for Indeterminate only while the total is genuinely unknown, and keep
it short - a sweep that never ends reads as a hang.
Percent is a percentage, which is the right unit when that is what the reader sees. When the
operation is counted in something else - files, rows, megabytes - use Value with Min and
Max instead: the bar is drawn the same way, but the screen reader is handed the real numbers, and
AriaValueText can spell them out ("3 of 10 files").
Progress only moves forward and it ends. A number that can go either way and is never finished - a disk
that is 60 % full, a temperature, a score - is a measurement, not progress: set Meter and it is
reported as a meter, which is what the ARIA
practices ask for.
A screen reader is not told that a bar moved unless something says so. AnnounceProgress adds a
polite live region that reports it, once per AnnounceStep crossed rather than on every change -
a bar that speaks on every percent is a bar nobody can listen to.
Progress is not a control: it reports, it is never operated. Nothing here takes focus or handles a key,
so a cancel button - if the operation has one - belongs beside the bar, not in it. And a readout placed
Inside the bar is decoration on top of the value, not the value itself: the children of a
progressbar are presentational, so what is announced is still what AriaValueText and the value
say.
The indeterminate sweep and the travelling stripes are decoration, and both collapse under
prefers-reduced-motion. Turn them back on with
ForceAnimation only where the movement is the message.
Usage
Every example is live. Open its code to see exactly what produced the component running underneath.
Basic
A Progress needs nothing but a Percent. Label names what is running and is what the
screen reader reads as the name of the bar; Description adds the supporting line underneath -
the file name, the step, the count - and is referenced as the bar's description. Both have a
Template twin (LabelTemplate, DescriptionTemplate) for markup instead of text.
Basic Progress
Example description
Circular
Circular draws the same progress as a ring instead of a bar. It is the shape for a compact
spot - inside a button, in a card corner, beside a row - where a full-width bar has nowhere to go.
Everything else works the same way: label, description, percentage and color are unchanged.
Basic Circular Progress
Example description
Value & Max
Percent is a percentage, which is right when a percentage is what the operation produces.
When it is counted in something else, set Value with Min and Max: the bar is
filled from the same ratio, but the assistive technology is handed the real range and the real
number rather than a percentage derived from it. AriaValueText spells that out in words where
the bare numbers would not be understood on their own.
Uploading files
3 of 10 files
Re-indexing rows
55 %
Row 3,200 of the 1,000 to 5,000 range
Steps
58 %
Percent number
ShowPercentNumber writes the percentage beside the bar, or in the middle of the ring.
PercentNumberFormat is a standard composite format string ("{0:F0} %" by default) applied to
the percentage, and PercentNumberTemplate replaces the text altogether with markup, receiving
the same percentage as its context. PercentNumberPosition moves it under the bar to the
Start, the Center or the End (the default), up onto the label's row with
Top - the "Uploading ... 42 %" layout, which costs no extra line - or onto the bar itself
with Inside, which keeps the whole indicator to one line but needs a Thickness the
text fits in and shows nothing until the bar is wide enough to hold it. The readout is hidden while
the progress is indeterminate, since there is no number to show.
Show Percent Number
86 %
Percent Number Format
85.69 %
Percent Number Template
86% done
Start
42 %
Center
42 %
Top
42 %
42 %
Inside
Show Percent Number
86 %
Percent Number Format
85.69 %
Thickness
Thickness overrides the height of the bar - the stroke width of the ring - in pixels. Leave it
unset and the thickness follows the Size, which is what keeps a page of progress bars in step
with each other and with the theme.
69 %
69 %
Diameter
Diameter sets the exact width and height of the ring in pixels, which is the direct way to
size a circular progress. Left unset, the ring takes the diameter of its Size and grows past
it only when Thickness multiplied by Radius asks for more room.
69 %
Indeterminate
Indeterminate is for an operation whose end is not known yet: the bar sweeps and the ring
spins instead of filling. No value is reported to assistive technology in this mode - which is what
tells a screen reader the progress is indeterminate - and the percentage readout is hidden.
Switch to a determinate value as soon as one exists.
Preparing your export
Spinner
A circular indeterminate progress is what most libraries call a spinner - the plain "working on it"
indicator. It takes the same Size and Color as everything else, and an
AriaLabel is worth adding where no visible text says what is being waited for.
Buffer
Buffer draws a second, fainter bar behind the first one: how far the operation has loaded
ahead of what it has actually finished - the buffered part of a video, the downloaded part of a file
still being processed. It is read on the same scale as the progress itself, so it is a percentage
beside Percent and a value between Min and Max beside Value, and it is
ignored while the progress is indeterminate.
Playing
35 %
Processing
35 %
Rounded
Rounded gives the bar pill-shaped ends and the ring a round stroke cap. The track is rounded
with the bar, so an empty bar does not sit square inside a round one. It is a purely visual choice -
nothing about the value or the announcement changes.
Striped
Striped paints diagonal stripes over a determinate bar, and StripedAnimation makes them
travel: the conventional way of saying that the operation behind a bar that is not moving much is
still running. Stripes apply to the linear bar only, and not while it is indeterminate - the sweep
already carries that meaning. The travelling stripes stop under reduced motion.
Reversed
Reversed fills the bar from the end of its container towards the start, and turns the ring
counter-clockwise. An indeterminate bar sweeps the other way instead - the shape other libraries call
a query indicator, for the moment before a request has anything to report. The direction is logical,
so it follows Dir: reversed in an RTL context runs left to right.
42 %
Gauge
GapDegree cuts a gap out of the bottom of the ring, which turns it from a loop into a gauge -
the shape for a reading taken against a scale rather than an operation running to an end. It is a
number of degrees between 0 (a closed ring, the default) and 295, so 180 leaves a half circle and 90
leaves the three-quarter dial. GapPosition moves the opening to the Top, the
Start or the End instead. It pairs naturally with Value, Min and
Max, which is what lets the ring read a real quantity, and with Rounded for a softer
arc. A gauge that reads a measurement rather than progress - the third one here - should also be a
Meter, which is the next section.
65 %
65 %
Meter
A progress bar says how far along a task is: it only moves forward, and it ends. A Meter is a
reading taken inside a known range - a disk that is 60 % full, a temperature, a score - which can move
either way and is never "finished". They look identical, but they are announced differently, and the
ARIA practices are explicit that a measurement should not be reported as progress. Set Meter
and the indicator is exposed as a meter instead;
everything else - the shape, the Value range, AriaValueText, the gauge - is unchanged.
An indeterminate indicator stays a progress bar, since a meter always has a value.
Disk usage
62 %
62 GB of 100 GB used
Signal
62 %
Vertical
Vertical stands the linear bar on its end, filling it from the bottom up - or from the top
down when it is also Reversed. A vertical bar has no width to take from its container, so
Length is what says how long it is (any CSS length; it defaults to 10rem). Everything else
carries over: thickness, color, buffer, stripes, rounded ends and segments all work along the other
axis. The circular progress ignores it.
Segments
Segments cuts the linear bar into that many equal pieces, for an operation made of a known
number of discrete steps - a wizard, a batch of jobs, an import in phases. SegmentGap is how
far apart they are drawn, in pixels. The value still fills the bar continuously and is still reported
as it is, so a bar caught between two segments shows a part-filled piece rather than rounding.
Segments apply to the linear bar only.
45 %
Announcements
A screen reader is not told that a progress bar moved unless something says so.
AnnounceProgress adds a polite live region that reports the progress as it advances, and
AnnounceStep is how far it has to move first - 25 percentage points by default, so a long
operation speaks four times instead of a hundred. A zero or negative step is treated as 25.
Completion is always announced. What is said is
AriaValueText when it is set, otherwise the percentage in the PercentNumberFormat,
prefixed by the Label. Nothing is announced while the progress is indeterminate, and the very
first value - including 100% - is recorded without announcement, as the starting point rather than
as an advance.
Importing rows
0 %
Uploading
Status
An operation that finished, or failed, is still a progress indicator - what changes is what it says.
There is no Status parameter here on purpose: a status is a Color, a word and a glyph,
and each of those is already a parameter of its own. Pick the Color for the state, put the
state in words in the Description, and put the glyph in the
PercentNumberTemplate, which replaces the readout with whatever markup you give it. Colour is
never the whole message - the words are what a screen reader reads, and what anyone who cannot tell
the two hues apart is left with.
Uploading report.pdf
70 %
Uploading - 4.2 MB of 6.0 MB
Uploading report.pdf
Upload complete
Uploading report.pdf
Upload failed - the connection was lost
Custom colors
BarColor and TrackColor take any CSS color and step outside the theme palette, for the
one indicator that has to carry a color of its own - a brand shade, a per-category legend, a value
that changes color as it climbs. BarColor replaces what the Color role would have given
and everything derived from it follows: the stroke of the ring, the faint tint of the Buffer,
the fill under the stripes. TrackColor paints the unfilled part - the track, the ring behind
the stroke, and the two ends the indeterminate sweep fades into. Prefer Color wherever the
theme has a role that fits: what is written here does not re-skin with the design system, and it is
on you to keep it readable in both schemes.
Brand
62 %
Buffered
Striped
Sweeping
62 %
Color
Color picks the palette of the bar from the theme's general colors, so the whole set re-skins
with the design system rather than being hard-coded. The track and the buffer follow it. Color alone
never carries the meaning - a failed operation still needs the words for it in the label or the
description.
Size
Size scales the whole indicator from the theme: the thickness of the bar, the diameter of the
ring and the type size of the label and the readout. Set Thickness or Diameter only
where a specific measurement is needed - the sizes are what keep a page consistent.
Small
69 %
Medium
69 %
Large
69 %
69 %
69 %
69 %
Style & Class
Style and Class reach the root element, while Styles and Classes reach
the parts by name - Root, Label, BarContainer, Track, Buffer,
Bar, PercentNumber and Description. What is written there comes after the
geometry the component computes, so a custom background, gradient or stroke wins over the default.
Component's Style & Class:
Styles & Classes:
RTL
Set Dir to BitDir.Rtl to lay the indicator out right to left: the bar fills from the
right, the label and the description align to it, and the percentage readout moves to the other end -
while the number inside it stays in its own direction, so "85 %" never turns into "% 85".
لیبل تست
69 %
توضیحات تست
لیبل تست
69 %
توضیحات تست
API
Every parameter, public member, sub-class and enum this component exposes.
BitProgress parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| AnnounceProgress | bool | false | Announces the progress to screen readers as it advances, through a live region of its own. The announcement is made once per AnnounceStep crossed rather than on every change, since a bar that speaks on every percent is a bar nobody can listen to. |
| AnnounceStep | double | 25 | How far the progress has to advance, in percentage points, before it is announced again. Completion is always announced, whatever the step divides into. The first observed value, including 100%, is recorded without announcement. A zero or negative value is treated as 25. |
| AriaValueText | string? | null | Text alternative of the progress status, used by screen readers for reading the value of the progress. |
| BarColor | string? | null | The color of the bar itself, as any CSS color. It replaces the palette the Color role would have given, and everything derived from it follows: the stroke of the ring, the faint tint of the Buffer and the fill of a Striped bar. |
| Buffer | double? | null | The secondary, buffered progress rendered behind the main bar, for an operation that loads ahead of what it has already played or processed. It is read on the same scale as Value (between Min and Max) when a Value is set, and as a percentage between 0 and 100 otherwise. Ignored while Indeterminate is true. |
| Circular | bool | false | Draws the progress as a ring instead of as a bar, which is the shape for a compact spot - inside a button, in a card corner, beside a row - where a full-width bar has nowhere to go. A circular indeterminate progress is what is usually called a spinner. |
| Classes | BitProgressClassStyles? | null | Custom CSS classes for different parts of the BitProgress. |
| Color | BitColor? | null | The general color of the BitProgress. |
| Description | string? | null | Text describing or supplementing the operation. |
| DescriptionTemplate | RenderFragment? | null | Custom template for describing or supplementing the operation. |
| Diameter | int? | null | The diameter of the circular progress in pixels. When not set, the diameter falls back to the theme value of the current Size, growing beyond it only when Thickness multiplied by Radius asks for more room. |
| GapDegree | double | 0 | Cuts a gap of this many degrees out of the bottom of the circular progress, which turns the ring into a gauge. Between 0 (a closed ring, the default) and 295; a value of 180 leaves a half circle. Has no effect on the linear progress. |
| GapPosition | BitProgressGapPosition | BitProgressGapPosition.Bottom | Where the GapDegree gap sits, which is also where the stroke of the gauge begins and ends. Reversed mirrors the gauge, so it swaps a Start gap with an End one and leaves a Top or a Bottom one where it is. |
| Indeterminate | bool | false | Reports that something is running without saying how far along it is: the bar sweeps and the ring spins instead of filling. No value is published to assistive technology in this mode - which is what tells a screen reader the progress is indeterminate - and the percentage readout is hidden. Switch to a determinate value as soon as one exists. |
| Label | string? | null | Label to display above the BitProgress. |
| LabelTemplate | RenderFragment? | null | Custom label template to display above the BitProgress. |
| Length | string? | null | How long a Vertical bar is, as a CSS length. A horizontal bar takes the width of whatever it is put in, so this has no effect there. |
| Max | double | 100 | The highest value of the range the Value is read against. It has no effect while Value is null, in which case Percent is already a percentage. |
| Meter | bool | false | Reports the indicator as a meter rather than as a progress bar. A progress bar says how far along a task is and only ever moves forward; a meter is a reading taken within a known range - a disk that is 60% full, a temperature, a score - which can move either way and is never "finished". This is what the ARIA practices ask for when the number is a measurement rather than progress. An Indeterminate indicator stays a progress bar, since a meter always has a value. |
| Min | double | 0 | The lowest value of the range the Value is read against. It has no effect while Value is null, in which case Percent is already a percentage. |
| Percent | double | 0 | Percentage of the operation's completeness, numerically between 0 and 100. Ignored when Value is set. |
| PercentNumberFormat | string | {0:F0} % | The composite format string the percentage readout is written with, applied to the percentage itself - "{0:F0} %" by default. It is formatted on the current culture, since it is text the reader sees. |
| PercentNumberPosition | BitProgressPercentPosition | BitProgressPercentPosition.End | Where the percentage readout of a linear progress is placed: under the bar aligned to its end (the default), to its start, in the middle, or on the bar itself. The readout of a circular progress is always in the middle of the ring, so this has no effect there. |
| PercentNumberTemplate | RenderFragment<double>? | null | Custom template for the percentage display, receiving the current percentage as its context. It replaces the text that PercentNumberFormat would have produced. |
| Radius | int | 6 | The multiplier applied to the Thickness to size the circular progress. The resulting diameter never falls below the theme value of the current Size, and setting Diameter replaces this calculation altogether. |
| Reversed | bool | false | Fills the progress from the end of the container towards its start, mirroring the direction of the linear bar and turning the circular one counter-clockwise. |
| Rounded | bool | false | Rounds the ends of the bar: a pill-shaped track and bar in linear mode, and a round stroke cap in circular mode. |
| SegmentGap | int | 4 | The gap between two Segments, in pixels. |
| Segments | int? | null | Cuts the linear bar into this many equal segments, for an operation made of a known number of discrete steps. The bar still fills continuously - the segments are how far apart the steps are drawn, not how the value is rounded. Has no effect on the circular progress. |
| ShowPercentNumber | bool | false | Writes the percentage beside the bar, or in the middle of the ring. PercentNumberPosition says where it goes and PercentNumberFormat how it reads. It is hidden while Indeterminate is true, since there is no number to show. |
| Size | BitSize? | null | The size of the BitProgress. |
| Striped | bool | false | Paints diagonal stripes over the linear bar, which is the conventional way of saying that the operation behind a determinate bar is still running. Has no effect on the circular or the indeterminate progress. |
| StripedAnimation | bool | false | Animates the stripes of a Striped bar so they travel along it. |
| Styles | BitProgressClassStyles? | null | Custom CSS Styles for different parts of the BitProgress. |
| Thickness | int? | null | How thick the indicator is drawn, in pixels: the height of a horizontal bar, the width of a Vertical one and the stroke of the ring. When not set it follows the Size, which is what keeps a page of indicators in step with each other and with the theme. |
| TrackColor | string? | null | The color of the unfilled part of the indicator, as any CSS color: the track behind the bar, the ring behind the stroke, and the two ends the indeterminate sweep fades into. |
| Value | double? | null | The completeness of the operation expressed in its own unit, read against Min and Max. When set, it takes the place of Percent and is what the screen reader is given, so an operation counted in files or in bytes is announced in files or in bytes. |
| Vertical | bool | false | Stands the linear bar on its end, filling it from the bottom up - or from the top down when it is also Reversed. A vertical bar has no width to take from its container, so its height comes from Length. Has no effect on the circular progress. |
BitComponentBase parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| AriaLabel | string? | null | Gets or sets the accessible label for the component, used by assistive technologies. |
| Class | string? | null | Gets or sets the CSS class name(s) to apply to the rendered element. |
| Dir | BitDir? | null | Gets or sets the text directionality for the component's content. |
| ForceAnimation | bool | false | Gets or sets a value indicating whether the component's animations play at their full duration even when reduced motion is requested. |
| HtmlAttributes | Dictionary<string, object> | new Dictionary<string, object>() | Captures additional HTML attributes to be applied to the rendered element, in addition to the component's parameters. |
| Id | string? | null | Gets or sets the unique identifier for the component's root element. |
| IsEnabled | bool | true | Gets or sets a value indicating whether the component is enabled and can respond to user interaction. |
| Style | string? | null | Gets or sets the CSS style string to apply to the rendered element. |
| TabIndex | string? | null | Gets or sets the tab order index for the component when navigating with the keyboard. |
| Visibility | BitVisibility | BitVisibility.Visible | Gets or sets the visibility state (visible, hidden, or collapsed) of the component. |
BitComponentBase public members
| Name | Type | Default value | Description |
|---|---|---|---|
| UniqueId | Guid | Guid.NewGuid() | Gets the readonly unique identifier for the component's root element, assigned when the component instance is constructed. |
| RootElement | ElementReference | Gets the reference to the root HTML element associated with this component. |
BitProgressClassStyles properties
| Name | Type | Default value | Description |
|---|---|---|---|
| Root | string? | null | Custom CSS classes/styles for the root element of the BitProgress. |
| Label | string? | null | Custom CSS classes/styles for the label of the BitProgress. |
| PercentNumber | string? | null | Custom CSS classes/styles for the percent number of the BitProgress. |
| BarContainer | string? | null | Custom CSS classes/styles for the bar container of the BitProgress. |
| Track | string? | null | Custom CSS classes/styles for the track of the BitProgress. |
| Buffer | string? | null | Custom CSS classes/styles for the buffer bar of the BitProgress. |
| Bar | string? | null | Custom CSS classes/styles for the bar of the BitProgress. |
| Description | string? | null | Custom CSS classes/styles for the description of the BitProgress. |
BitColor enum
| Name | Value | Description |
|---|---|---|
| Primary | 0 | Primary general color. |
| Secondary | 1 | Secondary general color. |
| Tertiary | 2 | Tertiary general color. |
| Info | 3 | Info general color. |
| Success | 4 | Success general color. |
| Warning | 5 | Warning general color. |
| SevereWarning | 6 | SevereWarning general color. |
| Error | 7 | Error general color. |
| PrimaryBackground | 8 | Primary background color. |
| SecondaryBackground | 9 | Secondary background color. |
| TertiaryBackground | 10 | Tertiary background color. |
| PrimaryForeground | 11 | Primary foreground color. |
| SecondaryForeground | 12 | Secondary foreground color. |
| TertiaryForeground | 13 | Tertiary foreground color. |
| PrimaryBorder | 14 | Primary border color. |
| SecondaryBorder | 15 | Secondary border color. |
| TertiaryBorder | 16 | Tertiary border color. |
BitProgressGapPosition enum
| Name | Value | Description |
|---|---|---|
| Bottom | 0 | At the bottom of the ring, which is where a gauge is normally opened. This is the default. |
| Top | 1 | At the top of the ring. |
| Start | 2 | At the starting side of the ring - the left in a left-to-right context, the right in a right-to-left one. |
| End | 3 | At the ending side of the ring - the right in a left-to-right context, the left in a right-to-left one. |
BitProgressPercentPosition enum
| Name | Value | Description |
|---|---|---|
| End | 0 | Under the bar, aligned to the end of it. This is the default. |
| Start | 1 | Under the bar, aligned to the start of it. |
| Center | 2 | Under the bar, in the middle of it. |
| Inside | 3 | On the bar itself rather than under it, which keeps the whole indicator to one line. |
| Top | 4 | Above the bar, on the same row as the label and aligned to the end of it. Without a label it is a line of its own above the bar. |
BitSize enum
| Name | Value | Description |
|---|---|---|
| Small | 0 | The small size. |
| Medium | 1 | The medium size. |
| Large | 2 | The large size. |
BitVisibility enum
| Name | Value | Description |
|---|---|---|
| Visible | 0 | The content of the component is visible. |
| Hidden | 1 | The content of the component is hidden, but the space it takes on the page remains (visibility:hidden). |
| Collapsed | 2 | The component is hidden (display:none). |
BitDir enum
| Name | Value | Description |
|---|---|---|
| Ltr | 0 | Ltr (left to right) is to be used for languages that are written from the left to the right (like English). |
| Rtl | 1 | Rtl (right to left) is to be used for languages that are written from the right to the left (like Arabic). |
| Auto | 2 | Auto lets the user agent decide. It uses a basic algorithm as it parses the characters inside the element until it finds a character with a strong directionality, then applies that directionality to the whole element. |
Feedback
Found a mistake, a gap, or something that could be clearer? Every page and every component is one click from its source.