Skip to content
BlazorUI

Progress

Progress

Bit.BlazorUIProgressIndicatorProgressBarSpinner

A bar, a ring or a gauge that reports how far along an operation is - or, indeterminate, that it is still running - to the eye and to assistive technology alike.

Notes

The progressbar role requires a name: give every indicator a Label, or an AriaLabel where the text around it already says what is loading.

Prefer a determinate value wherever one exists - it is the difference between "working" and "stuck" - and keep Indeterminate for the moment the total is unknown.

Progress is never operated: nothing in it takes focus, so a cancel button belongs beside it. The sweep, the spinner and the travelling stripes slow down under prefers-reduced-motion.

Usage

Every example is live. Open its code to see exactly what produced the component running underneath.

Basic

Percent is all it needs. Label names the bar for screen readers too, Description adds a line under it, and Circular draws the same progress as a ring. Both texts have a Template twin for markup.

Uploading report.pdf
4.2 MB of 10 MB

Uploading report.pdf
4.2 MB of 10 MB

Indeterminate

For an operation with no known end: the bar sweeps and the ring spins (a spinner). No value reaches assistive technology, which is what marks it indeterminate. Delay hides it for that many milliseconds after it first renders, so a quick operation never flashes one.

Preparing your export




Thickness & diameter

Thickness is the height of the bar and the stroke of the ring, in pixels; Diameter is the exact size of the ring. Unset, both follow the Size and the theme.

10


Percent number

ShowPercentNumber writes the percentage; PercentNumberFormat ("{0:F0} %" by default) or PercentNumberTemplate changes how it reads. PercentNumberPosition puts a bar's readout under it (End, Start, Center), on the label's row (Top) or on the bar (Inside, given a Thickness the text fits in). A ring shows it in its middle, scaled to its diameter.

End
86 %

Format
85.69 %

Template
86% done

Start
42 %

Center
42 %

Top
42 %

Inside
42 %

86 %
85.7 %

Value & range

When the operation is counted in something other than percent, set Value with Min and Max: the bar fills from the same ratio, but assistive technology gets the real numbers. AriaValueText puts them into words.

Uploading files
3 of 10 files

Re-indexing rows
55 %

Steps
58 %

Buffer

Buffer draws a fainter second value behind the bar - 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.

40


Processing
40 %

Rounded & striped

Rounded gives the bar pill ends and the ring a round cap. Striped paints diagonal stripes over a linear bar and StripedAnimation makes them travel - the conventional "still running" on a bar that is not moving much.





Segments

Segments cuts the linear bar into equal steps and SegmentGap spaces them, in pixels. The value still fills continuously, so a step can be part-filled.

45

45 %


Reversed & vertical

Reversed fills from the end, turns the ring counter-clockwise and sweeps an indeterminate bar back; it is logical, so it follows Dir. Vertical stands the bar on its end, filling from the bottom (the top when Reversed), Length tall (10rem by default).

42 %



Gauge

GapDegree cuts a gap (0 to 295 degrees) out of the ring, turning it into a gauge; GapPosition moves the opening from the Bottom to the Top, Start or End.

65

65 %
65 %

Meter

Progress moves forward and ends; a reading within a range - disk usage, a temperature, a score - does neither. Meter exposes such a reading with the meter role instead; nothing else changes.

62

Disk usage
62 %
62 GB of 100 GB used

Temperature
32 °C

Accessibility

A screen reader is not told a bar moved unless something says so. AnnounceProgress adds a polite live region that speaks once per AnnounceStep crossed (25 points by default) and always at completion - the Label followed by AriaValueText or the formatted percentage. The first value and a reset are recorded in silence.

20

Importing rows
20 %

Uploading

Custom colors

BarColor and TrackColor take any CSS color for the one indicator that needs its own. The ring, the buffer and the stripes follow the bar color; the track color also paints the ends of the sweep. Prefer Color where a theme role fits: these do not re-skin with the theme.

Brand
62 %

Buffered

Striped

Sweeping

62 %

Cascading parameters

BitParams hands a BitProgressParams to every progress under it, so a dashboard sets the shared look once. The values are defaults, not overrides: a progress that sets a parameter itself keeps its own. The value, the texts and the templates stay per instance.

CPU
34 %

Memory
71 %

Disk
92 %

Outside the cascade

Color

Color picks the bar's palette from the theme, so it re-skins with the design system. It is the way to show a status - pair it with words and, through PercentNumberTemplate, a glyph, since color alone is never the whole message.



Status:

Uploading report.pdf
Upload complete

Uploading report.pdf
Upload failed - the connection was lost

Size

Size scales the thickness, the ring's diameter and the type from the theme.

Small
69 %

Medium
69 %

Large
69 %

69 %

Style & Class

Style and Class reach the root; Styles and Classes reach each part - Root, Label, BarContainer, Track, Buffer, Bar, PercentNumber and Description - after the computed geometry, so they win over it.

Component's Style & Class:




Styles & Classes:





The public CSS variables inherit, so one set on :root or an ancestor restyles every progress below it, and one on Style restyles a single instance. A parameter that says the same thing still wins.

Softer corners, own palette
58 %

Wide, bright stripes

42 %

Set once on an ancestor, inherited by every progress inside it:

Documents
2.1 GB
Photos
5.4 GB
Videos
8.8 GB

RTL

Dir set to BitDir.Rtl fills the bar from the right and mirrors the label, readout and description, while the number keeps its own direction ("85 %", never "% 85").


در حال بارگذاری
69 %
۴.۲ مگابایت از ۱۰ مگابایت

69 %

CSS variables

The public custom properties this component reads off its root, for what no parameter covers.

Every variable is read with a fallback and never declared by the component, so it inherits like any other custom property: set one on :root (or in a [bit-theme] block) to restyle every instance, on any ancestor to restyle the ones inside it, or on the Style of one instance to restyle that one alone. Leave a variable unset and the component falls back to the theme token beside it.

BitProgress CSS variables

Name Default value Description
--bit-Progress-bar-color The Color role's main color Fill of the bar and stroke of the ring; the buffer and the stripes derive from it. BarColor wins over it.
--bit-Progress-bar-text-color The Color role's text color Color of a readout placed Inside the bar.
--bit-Progress-track-color --bit-clr-bg-sec The unfilled part: the track, the ring behind the stroke and the ends of the sweep. TrackColor wins over it.
--bit-Progress-buffer-color The bar color at 38% The buffered second value, on the bar and on the ring.
--bit-Progress-stripe-color --bit-clr-bg-pri at 25% The stripes of a Striped bar.
--bit-Progress-stripe-size spacing(2) Pitch of the stripes, which is also how far they travel in one cycle.
--bit-Progress-thickness Per Size: --bit-siz-track-sm / -md / -lg (bar), 1x / 2x / 4x --bit-siz-spinner-stroke (ring) Height of the bar, width of a vertical one and stroke of the ring. Thickness wins over it.
--bit-Progress-radius --bit-shp-radius-none Corner radius of the track and the bar. Rounded wins over it with a full radius.
--bit-Progress-diameter Per Size: spacing(4) / spacing(6.25) / spacing(9) Smallest diameter of the ring. Diameter wins over it.
--bit-Progress-length spacing(20) Height of a Vertical bar. Length wins over it.
--bit-Progress-transition-duration --bit-mot-duration How long the fill takes to follow a new value. Set it to 0s for a bar fed many times a second.
--bit-Progress-font-size Per Size: --bit-tpg-fs-xs / -sm / -md Text size of the label and of the readout beside the bar.
--bit-Progress-label-color --bit-clr-fg-pri Color of the label.
--bit-Progress-label-font-weight --bit-tpg-fw-regular Weight of the label.
--bit-Progress-percent-color --bit-clr-fg-pri (bar), --bit-clr-fg-sec (ring) Color of the readout beside the bar or in the middle of the ring.
--bit-Progress-percent-font-size A step of the type ramp per the size the ring is drawn at, --bit-tpg-fs-xs to --bit-tpg-fs-4xl Text size of the readout in the middle of the ring.
--bit-Progress-description-color --bit-clr-fg-sec Color of the description.
--bit-Progress-description-font-size Per Size: --bit-tpg-fs-2xs (small, medium), --bit-tpg-fs-xs (large) Text size of the description.

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 through a polite live region, once per AnnounceStep crossed and always at completion.
AnnounceStep double 25 How far the progress has to advance, in percentage points, before it is announced again. The first value is recorded without announcement; zero or negative is treated as 25.
AriaValueText string? null The value in words for screen readers ("3 of 10 files"), also what AnnounceProgress speaks.
BarColor string? null The color of the bar as any CSS color, replacing the Color role. The ring, the buffer and the stripes follow it.
Buffer double? null A fainter second value behind the bar, read on the same scale as Value (or as a percentage without one). Ignored while Indeterminate.
Circular bool false Draws the progress as a ring instead of a bar. An indeterminate ring is a spinner.
Classes BitProgressClassStyles? null Custom CSS classes for different parts of the BitProgress.
Color BitColor? null The general color of the BitProgress.
Delay int 0 Milliseconds the progress stays hidden after it first renders, so a quick operation never flashes one. Its space is kept and it is hidden from assistive technology too. The window opens once, with the first render: giving a Delay to a progress already on screen does not hide it.
Description string? null Text describing or supplementing the operation.
DescriptionTemplate RenderFragment? null Custom template for describing or supplementing the operation.
Diameter int? null The exact diameter of the ring in pixels. Unset, it follows the Size, growing only when Thickness times Radius asks for more.
GapDegree double 0 Cuts a gap of this many degrees (0 to 295) out of the ring, turning it into a gauge. No effect on a bar.
GapPosition BitProgressGapPosition BitProgressGapPosition.Bottom Where the gauge gap sits. Reversed swaps Start and End.
Indeterminate bool false Reports that something is running without saying how far: the bar sweeps and the ring spins. No value is published to assistive technology and the readout is hidden.
Label string? null Label to display above the BitProgress.
LabelTemplate RenderFragment? null Custom label template to display above the BitProgress.
Length string? null The height of a Vertical bar, as a CSS length (10rem by default).
Max double 100 The top of the range Value is read against. Ignored without a Value.
Meter bool false Exposes the indicator with the meter role - a reading within a range, such as disk usage - instead of progressbar. An Indeterminate one stays a progressbar.
Min double 0 The bottom of the range Value is read against. Ignored without a Value.
Percent double 0 The completeness as a percentage between 0 and 100. Ignored when Value is set.
PercentNumberFormat string {0:F0} % The composite format string of the readout, applied to the percentage on the current culture.
PercentNumberPosition BitProgressPercentPosition BitProgressPercentPosition.End Where the readout of a bar sits: under it (End, Start, Center), on the label's row (Top) or on the bar (Inside). A ring always shows it in its middle.
PercentNumberTemplate RenderFragment<double>? null Custom markup for the readout, receiving the percentage as its context. Shows the readout even without ShowPercentNumber.
Radius int 6 The multiplier applied to Thickness to size the ring when no Diameter is set.
Reversed bool false Fills from the end towards the start and turns the ring counter-clockwise.
Rounded bool false Pill-shaped ends on the bar and round caps on the ring.
SegmentGap int 4 The gap between two Segments, in pixels.
Segments int? null Cuts the bar into this many equal segments. The value still fills continuously. No effect on a ring.
ShowPercentNumber bool false Writes the percentage beside the bar or in the middle of the ring. Hidden while Indeterminate.
Size BitSize? null The size of the BitProgress.
Striped bool false Paints diagonal stripes over a determinate bar.
StripedAnimation bool false Makes the stripes of a Striped bar travel.
Styles BitProgressClassStyles? null Custom CSS Styles for different parts of the BitProgress.
Thickness int? null The height of the bar, the width of a Vertical one and the stroke of the ring, in pixels. Unset, it follows the Size.
TrackColor string? null The color of the unfilled part as any CSS color: the track, the ring behind the stroke and the ends of the sweep.
Value double? null The completeness in the operation's own unit, read against Min and Max. Takes the place of Percent and is what assistive technology is given.
Vertical bool false Stands the bar on its end, filling from the bottom up (top down when Reversed). Its height comes from Length.

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.