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

Progress Bar

[!WARNING] This component might still be in development. Please use with caution.

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.

Example Progress Bar

Specs

Tokens

Token	Description
displayName	Display name in the structure panel
visibilityPolicySetId	Controls visibility using policy sets
titleTranslations	Title text with localization support
errorMessage	Message shown when progress bar is in error state
paddingClass	Spacing around the progress bar via CSS classes
events	Configures component events
ON_INIT (Events)	Event triggered on initialization
ON_DESTROY (Events)	Event triggered on removal
id	Unique identifier for programmatic access
dataTestId	Identifier for automated testing
enableAsHotspot	Enables the progress bar as a guided tour hotspot
guidedTourHotSpotTitle	Localized title for guided tour hotspot
guidedTourHotSpotDescription	Localized description for guided tour hotspot
updateProgress	Method to update progress value
setInvalid	Method to set error state with message
setValid	Method to reset from error state

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.

Links

Figma: tba
Live style guide: https://e1-dev.k8s.myapp.de/live-style-guide/other-components/progress-bar

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

Do	Don’t	Article setting(s)
update with values strictly within 0–100.	pass values outside the allowed range or non-numbers.	`updateProgress`
show an actionable failure message when progress cannot continue.	indicate failure only by color or by stopping updates with no explanation.	`setInvalid`, `errorMessage`
clear the error state when resolved, then resume updates.	keep the bar in error after the issue is fixed.	`setValid`, `updateProgress`
add outer spacing to suit context.	force spacing with external CSS overrides.	`paddingClass`
localize all user-facing copy (title, error, hotspot text).	ship English-only text.	`titleTranslations`, `errorMessage`, `guidedTourHotSpotTitle`, `guidedTourHotSpotDescription`
hide for ineligible users.	show sensitive progress to users who shouldn’t see it.	`visibilityPolicySetId`
annotate the component for tours when teaching the UI.	rely on ad-hoc callouts elsewhere to explain it.	`enableAsHotspot`, `guidedTourHotSpotTitle`, `guidedTourHotSpotDescription`
clean up listeners/timers on teardown.	leave background work running after navigation.	`events.ON_DESTROY`

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.