Progress

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".

Playground

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

Functionality

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

---