Skip to content
lab components / Data Visualization

Progess Bar

Visually communicate the progress of a specific process to keep users informed and manage expectations.

ExamplesPropertiesGuidelines

This is a Lab component!

That means it doesn't satisfy our definition of done and may be changed or even deleted. For an exact status, please reach out to the Fancy team through the dev_fancy or ux_fancy channels.

import { ProgressBar } from "@siteimprove/fancylab";

#Spinner vs. Progress Bar

To clarify the differences between Spinner and ProgressBar, a short description is provided.

Component namePurposeUser interactionUsage
SpinnerIndicates an ongoing process with an unknown or indefinite duration.Typically, no user interaction is possible during the process.Loading content, refreshing data, background tasks.
Progress BarShows the progress of a process with a known or estimated duration.User interaction may be possible during the process (e.g., cancellation).Uploading/downloading files, multi-step forms, progress towards goals.

#Warm color v.s Cool color

To clarify the colorRange differences between Cool and Warm, a short description is provided.

ColorPsychological associationsUse CasesConsiderations
Cool Colors (Blues)Trust, calmness, professionalism, stabilityStandard progress, data uploads, background tasks, tasks with longer durations.None.
Warm Colors (Reds, Oranges, Yellows)Energy, urgency, excitement, warning.Quick actions, time-sensitive tasks, alerts, reaching milestones, potential errors.Use cautiously and sparingly. Reds can be associated with errors, so use lighter oranges or yellows to indicate progress towards a positive goal.

#Examples

#Basic Usage - 0%

Illustrates the progress bar's initial or empty state before any progress has been made.

<ProgressBar value={0} total={100} />

#Basic Usage - 25%

Demonstrates the bar at a quarter of completion, showing a small amount of progress.

<ProgressBar value={25} total={100} />

#Basic Usage - 50%

Showcases the halfway point, representing significant progress.

<ProgressBar value={50} total={100} />

#Basic Usage - 75%

Indicates that the process is nearing completion, with only a small amount remaining.

<ProgressBar value={75} total={100} />

#Basic Usage - 100%

Signifies full completion of the process, often accompanied by a visual change or message.

<ProgressBar value={100} total={100} />

#Color Range "Cool" - 0%

Illustrates the progress bar's initial or empty state before any progress has been made.

<ProgressBar value={0} total={100} colorRange="cool" />

#Color Range "Cool" - 25%

Shows a gradual shift towards darker hues as the bar progresses within the Heatrange: cool colour platte.

<ProgressBar value={25} total={100} colorRange="cool" />

#Color Range "Cool" - 50%

Highlights the midpoint with a balanced, neutral color within the Heatrange: cool colour platte.

<ProgressBar value={50} total={100} colorRange="cool" />

#Color Range "Cool" - 75%

Continues the transition to darker colors, nearing completion within the Heatrange: cool colour platte.

<ProgressBar value={75} total={100} colorRange="cool" />

#Color Range "Cool" - 100%

Indicates completion with the darkest color in the Heatrange: cool colour platte.

<ProgressBar value={100} total={100} colorRange="cool" />

#Specific color - 69%

Showcases a progress bar at 69% completion using a distinct color that may be chosen to highlight a specific milestone, convey a particular meaning, or simply provide visual contrast.

<ProgressBar value={69} total={100} color={ColorPinkDarker} />

#Reverse Animation - 75%

Demonstrates a progress bar decreasing from right to left, commonly used for countdowns or when a value is depleting.

Use Cases:

  • Decreasing Values: Visualize countdowns, depletion of resources, etc.
  • Critical Alerts: Emphasize urgent situations or time-sensitive tasks.

Best Practices:

  • Use sparingly to avoid confusion.
  • Clearly label the bar to indicate its reverse direction.
<ProgressBar value={75} total={100} reverseColorRange />

#Hidden for screen readers

Demonstrates how a progress bar can be programmatically hidden from screen reader users while still conveying the progress information visually.

<ProgressBar value={50} total={100} aria-hidden={true} />

#Properties

PropertyDescriptionDefinedValue
valueRequired
number
totalRequired
number
tooltipContentOptional
string
colorOptional
stringIf color is specified, it will take precedence over the colorRange property
colorRangeOptional
"cool" | "warm"
reverseColorRangeOptional
boolean
aria-hiddenOptional
boolean
data-observe-keyOptional
stringUnique string, used by external script e.g. for event tracking
classNameOptional
stringCustom className that's applied to the outermost element (only intended for special cases)
styleOptional
objectStyle object to apply custom inline styles (only intended for special cases)

#Guidelines

#Best practices

#General

Use ProgressBar when:

  • Measurable Progress: The task's progress can be quantifiably tracked towards a goal (e.g.: file download). The bar fills linearly from 0% to 100%.
  • Compact Display: You need to show progress clearly in limited space (e.g.: CMS, or browser extension).
  • Data Operations: You want to indicate the status of data-related activities (loading, transfer, processing).
#Flat Gauge Variation (for Data Visualization)
  • Purpose: Quickly visualize progress towards a metric or goal within a small area (e.g.: in dashboards, Card, HighlightList table, Table).
  • Clear Label: Ensure the metric being tracked is instantly recognizable (e.g.: "DCI Score").
  • Numerical Precision: Include a percentage or numerical value alongside the visual bar for accuracy.

#Placement

ProgressBar is typically used in the following places:

  • Above Content: For overall page or section loading.
  • Within Task Flows: Guide users through multi-step forms or processes.
  • Flat Gauge: In dashboards, Card, Highlight, Table, or List for quick progress checks towards goals.

#Style

  • Siteimprove Design System: Adhere to Siteimprove's guidelines for color, typography, and spacing. If you are not using a component from Fancy, match the styling of your ProgressBar to existing components for visual consistency.
  • Label Wrapping: Allow labels to wrap if space is limited, but ensure numerical values are always fully visible.

#Do not use when

  • Short Tasks (<5 seconds): Use a Spinner instead for very brief loading times.
  • User-Driven Progress: When progress depends on user actions (e.g.: tutorials completed) rather than automatic processes.

#Accessibility

#For designers

  • Ensure sufficient color contrast between the bar and its background.

#For developers

This component comes with built-in accessibility, no extra work required.

Explore detailed guidelines for this component: Accessibility Specifications

#Writing

  • Labels: Inform users about the specific data or process the progress bar represents (e.g.: "Downloading file..."). Keep labels concise and consistent.
  • Estimated Time(Optional): For longer tasks, consider displaying an estimated time remaining alongside the progress bar.