(this page was created automatically. In case of formatting issues, please visit the official Wiki Page)

Progress Bar

(in development)

Link to Figma: tba

Overview

• The Dynamic Progress Bar component shows progress toward completing a task or process.
• It displays a horizontal bar that fills from left to right as progress increases.
• It supports customizable colors, thresholds, and state indicators.
• This component is useful for showing task completion, loading states, or any measurable percentage.

Specs

Tokens

Structure

• The Dynamic Progress Bar represents task completion as a horizontal bar that fills according to a numeric progress value.

(Configured in Component Actions)

• progress – A number between 0 and 100 representing the completion percentage. For example, calling updateProgress(75) would set the progress bar to 75% filled.

(Configured in Visual Properties)

• errorMessage – Specifies the message to display when the progress bar enters an error state. For example, "Upload failed due to network error" provides users with clear information about what went wrong.

(Configured in General Properties)

• visibilityPolicySetId – Determines the visibility of the component based on specified policy sets. For example, setting to "userOnlyPolicy" restricts the progress bar to authenticated users.

(Configured in Technical Documentation for Backend Developers)

• Progress Updates Example – The progress bar can be updated using server-sent events or polling API endpoints:

  {
    "progress": 65,
    "status": "processing",
    "remainingTime": "2 minutes"
  }

Styling

(Configured in General Properties)

• displayName – Sets the display name of the component shown in the structure panel. For example, "Upload Progress" allows for easy identification of this progress bar's purpose in the component structure.

(Configured in Visual Properties)

• paddingClass – Configures spacing around the progress bar using CSS classes. For example, "p-3" adds medium padding around the progress bar for better visual spacing within its container.
• titleTranslations – Sets the title text displayed above the progress bar with support for multiple languages. For example, {"en-US": "File Upload Progress", "de-DE": "Datei-Upload-Fortschritt"} ensures proper localization of the header text.

Actions & Variants

(Configured in Events)

• events – Configures the events that the component can trigger and respond to.
• ON_INIT (Events) – Triggered when the component is initialized. Can be used to perform setup operations like loading initial progress value.
• ON_DESTROY (Events) – Triggered when the component is removed from the DOM. Useful for cleanup operations.

(Configured in Component Actions)

• updateProgress(progress: number) – Updates the current progress value displayed by the bar. For example, calling updateProgress(75) sets the progress bar to 75% filled.
• setInvalid(errorMessage: string) – Sets the progress bar to an invalid/error state with a custom message. For example, calling setInvalid("Connection timeout") shows the error message.
• setValid() – Resets the progress bar from an error state back to a normal state.

Tests

(Configured in Testing Hooks)

• id – Specifies a unique identifier for the component used for programmatic access. For example, "fileUploadProgressBar" enables targeted manipulation of this specific progress bar.
• dataTestId – Sets the testing hook ID for automated testing. For example, setting it to "file-upload-progress" allows test scripts to reliably locate this component.
• enableAsHotspot – Enables the component as a guided tour hotspot. When enabled, this progress bar can be highlighted during guided tours of the application.
• guidedTourHotSpotTitle – Sets the title for the guided tour hotspot, supporting translations. For example, {"en-US": "Progress Indicator", "de-DE": "Fortschrittsanzeige"} provides localized titles for the hotspot.
• guidedTourHotSpotDescription – Sets the description for the guided tour hotspot, supporting translations. For example, {"en-US": "This bar shows your current progress", "de-DE": "Dieser Balken zeigt Ihren aktuellen Fortschritt"} provides localized descriptions.

Guidelines

Technical Documentation for Backend Developers

Progress Updates
The progress bar typically receives updates from frontend processes, but it can also be updated based on server-sent events or polling API endpoints that return progress information.

Example progress update format from an API:

{
  "progress": 65,
  "status": "processing",
  "remainingTime": "2 minutes"
}

The actual progress value (0-100) would be extracted from this response and used to update the progress bar.

Usage

• use when you need to represent determinate progress from 0–100 that updates over time via updateProgress(n).
• avoid for indeterminate or non-percentage tasks (no indeterminate state is exposed in the article).

Sizing & Layout

• adjust only the outer spacing with paddingClass; no component height/width tokens are exposed.
• set displayName to help authors identify the instance in the structure panel.

States & Feedback

• normal: set the current percentage with updateProgress(n).
• error: call setInvalid(errorMessage) to show a failure message; recover with setValid() and then resume updateProgress(...).

Data-Driven / Conditional Behavior

• clamp values so updateProgress(n) only receives numbers between 0 and 100.
• when upstream logic signals a failure, trigger setInvalid(errorMessage); on recovery, call setValid() and continue with updateProgress.

Visibility & Authorization

• hide the component for ineligible users with visibilityPolicySetId.

Content & Localization

• localize user-facing copy with titleTranslations for the header and errorMessage for failures.
• if used in guided tours, localize guidedTourHotSpotTitle and guidedTourHotSpotDescription; enable with enableAsHotspot.

Dos & Don’ts

Accessibility

• provide localized context for what the bar represents using titleTranslations. Keep it concise and specific so announcements are understandable.
• convey failures with text via setInvalid(errorMessage); clear with setValid().
  • write errorMessage text that states the issue and, if relevant, the next action.
• expose stable hooks for testing and audits using dataTestId and id.
• prevent disclosure of restricted information by gating visibility with visibilityPolicySetId.
• localize guided-tour copy when hotspots are enabled using guidedTourHotSpotTitle and guidedTourHotSpotDescription.
• moderate announcement frequency by batching calls to updateProgress to avoid rapid changes that can overwhelm users and assistive tech.