Progress

This documentation is currently being revised and is in beta status. Content may still change.

This component is being retested for accessibility. The full test is still pending and can only be completed after a release.

Synonyms: Progress indicator, progress bar

Description: The Progress component visualizes the progress or completion of a process or task. It allows users to understand the current status in relation to a defined goal.

Example

Display of the component with a horizontal progress bar and label.

<KolProgress _label="Progress" _max={100} _value={65} _variant="bar" />

Accessibility

The Progress component was developed with a focus on accessibility:

• Semantic structure: The component uses the ARIA attribute role="progressbar" to correctly identify it to assistive technologies.
• Label: The _label attribute is rendered as an aria-label or similar label and informs users of assistive technologies about the purpose of the progress bar.
• Values: The current and maximum values are communicated via aria-valuenow and aria-valuemax.
• Transparency: Progress is always calculated and displayed as a percentage to ensure transparency.

Links and References

Usage

Best Practices / Recommendations

• Meaningful labels: Use clear descriptions for _label that convey which task or process is loading (e.g. "File is being uploaded" rather than just "Upload").
• Realistic value ranges: Choose _max based on the actual task. For example, for a task with 12 steps you can use _max="12" instead of normalizing to 100.
• Visual clarity: Use _variant="bar" for horizontal contexts and _variant="cycle" for compact displays.
• Communicate unit information clearly: When _unit is set, it is processed internally, but communicate clearly what the unit means (e.g. via _label).
• Limit values: Values outside the range [0, max] are automatically clamped. Validate input values before passing them to the component.
• Variant selection: Use _variant="bar" for longer processes and _variant="cycle" for fast or space-constrained operations.

Use Cases

• File uploads/downloads: Displaying the progress of uploading or downloading files.
• Form completion: Visualization of steps in multi-step forms or checklists.
• Process progress: Displaying progress bars for longer-running background processes.
• Resource usage: Showing utilization (e.g. battery charge, storage space, CPU).
• Task completion: Tracking completed tasks in a list or towards an overall goal.

FAQ

Can I display intermediate values that exceed _max?
Yes, the value is automatically clamped to _max in the display. This is intentional to preserve the integrity of the visualization.

Is _unit displayed anywhere?
No, _unit is not displayed visually, but can be communicated via _label.

Can I use decimal numbers for _value or _max?
Yes, the Progress component also processes decimal numbers, for example _value="5.5" with _max="10".

Construction / Technical Details

Playground

<KolProgress _label="Progress" _max={100} _value={20} />

Functionality (with Code)

Horizontal Progress Bar

The horizontal bar is the default variant and is suitable for display in larger contexts.

<KolProgress _label="Progress" _max={100} _value={45} _variant="bar" />

Circular Progress Bar

The circular variant is compact and suitable for small areas or as an indicator for fast processes.

<KolProgress _label="Cycle" _max={100} _value={65} _variant="cycle" />

Label and Unit

Use _label to describe the progress; _unit can be used internally for calculations.

<KolProgress _label="Download speed" _max={500} _unit="MB" _value={250} />

Task Tracking

Example use case: tracking completed tasks from a list.

<KolProgress _label="Tasks completed" _max={12} _value={8} />

API

Overview

The Progress component visualizes the completion status of a task or process. It supports both determinate (percentage-based) and indeterminate variants.

Properties

Property	Attribute	Description	Type	Default
_label	_label	Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.).	string | undefined	undefined
_max (required)	_max	Defines the maximum value of the element.	number	undefined
_unit	_unit	Defines the unit of the step values (not shown).	string | undefined	undefined
_value (required)	_value	Defines the value of the element.	number	undefined
_variant	_variant	Defines which variant should be used for presentation.	"bar" | "cycle" | undefined	undefined

---