Progress Bar

avonni-progress-bar

Displays the progress of an operation as a horizontal or vertical bar.

Overview

Progress Bar is a Lightning Web Component that displays progress toward a goal as a horizontal or vertical bar, with an optional value label, pin, reference lines, and themed styling.

Use it in your own Lightning Web Components to visualize completion, capacity, or loading progress. You control the value, orientation, theme, thickness, value display, and reference markers—all through the component's attributes.

Use Cases

• Task completion: Show how far a process or checklist has progressed.
• Capacity usage: Visualize storage, quota, or budget consumption.
• Upload progress: Pair is-loading with a value for in-flight transfers.
• Targets and thresholds: Mark goals or minimums with reference lines.
• Status emphasis: Use themes (success, warning, error) to convey state.

---

Theme Guidelines

Theme	Use Case
base	Neutral progress (default).
success	Healthy or on-track progress.
warning	Approaching a limit or threshold.
error	Critical or over-capacity states.
info	Informational progress.
offline	Sync or connectivity progress.

---

Use Case Examples

Example 1: Task completion with reference lines

Scenario: Show project completion with the value displayed and target and minimum thresholds marked.

<!-- projectProgress.html -->
<template>
    <avonni-progress-bar
        label="Project completion"
        value={completionValue}
        theme="base"
        thickness="large"
        show-value
        value-position="top-right"
        value-prefix="Progress:"
        value-suffix="done"
        reference-lines={referenceLines}
    ></avonni-progress-bar>
</template>

// projectProgress.js
import { LightningElement } from 'lwc';

export default class ProjectProgress extends LightningElement {
    completionValue = 72;

    referenceLines = [
        { label: 'Target', value: 80, variant: 'success', borderStyle: 'dashed' },
        { label: 'Minimum', value: 25, variant: 'warning', borderStyle: 'dotted' }
    ];
}

Result: A thick base-themed bar at 72% reading "Progress: 72% done", with dashed target and dotted minimum markers.

Example 2: Circular success bar with a pin

Scenario: Show storage usage as a circular bar with the value displayed in a pin.

<!-- storageProgress.html -->
<template>
    <avonni-progress-bar
        label="Storage used"
        value={storageValue}
        theme="success"
        thickness="medium"
        variant="circular"
        show-pin
        show-value
        pin-attributes={pinAttributes}
        value-suffix="GB sync"
    ></avonni-progress-bar>
</template>

// storageProgress.js
import { LightningElement } from 'lwc';

export default class StorageProgress extends LightningElement {
    storageValue = 45;
    pinAttributes = { type: 'circle', position: 'right' };
}

Result: A circular success-themed progress bar with the value shown in a pin labeled "45 GB sync".

---

Specifications

Attributes

Name	Description	Type	Default	Required
alternative-text	The assistive text for the progress bar.	String	—
is-loading	If present, the progress bar is in a loading state and shows a spinner.	Boolean	false
label	Label for the progress bar.	String	—
loading-state-alternative-text	Message displayed while the progress bar is in the loading state.	String	"Loading..."
orientation	Orientation of the progress bar to be used. Valid values include horizontal and vertical.	String	"horizontal"
pin-attributes	Object of attributes for the pin.	AvonniProgressBarPinAttributes	—
reference-lines	Array of reference lines objects.	AvonniProgressBarReferenceLine[]	—
show-pin	If present, display the value in pin. Show value must be set to true.	Boolean	false
show-value	If present, display the value.	Boolean	false
size	The size of the progress bar. Valid values are x-small, small, medium, large and full.	String	"full"
textured	If present, display a texture background.	Boolean	false
theme	Defines the theme of the progress bar. Valid values includes base, success, inverse, alt-inverse, warning, info, error and offline.	String	"base"
thickness	Set progress bar thickness. Valid values include x-small, small, medium and large.	String	"medium"
value	The percentage value of the progress bar.	Number	0
value-position	Position of the value if present. Valid values include left, right, top-right, top-left, bottom-right and bottom-left.	String	"top-right"
value-prefix	Text displayed before the value.	String	—
value-suffix	Text displayed next to the value.	String	—
variant	The variant changes the appearance of the progress bar. Accepted variants include base or circular.	String	"base"

Styling Hooks

CSS Variable	Type	Default
--avonni-progress-bar-alt-inverse-color-background	color	#dddbda
--avonni-progress-bar-bar-value-alt-inverse-color-background	color	#032d60
--avonni-progress-bar-base-color-background	color	#dddbda
--avonni-progress-bar-bar-value-base-color-background	color	#0176d3
--avonni-progress-bar-error-color-background	color	#dddbda
--avonni-progress-bar-bar-value-error-color-background	color	#ba0517
--avonni-progress-bar-info-color-background	color	#dddbda
--avonni-progress-bar-bar-value-info-color-background	color	#706e6b
--avonni-progress-bar-inverse-color-background	color	#dddbda
--avonni-progress-bar-bar-value-inverse-color-background	color	#001639
--avonni-progress-bar-offline-color-background	color	#dddbda
--avonni-progress-bar-bar-value-offline-color-background	color	#444
--avonni-progress-bar-success-color-background	color	#dddbda
--avonni-progress-bar-bar-value-success-color-background	color	#2e844a
--avonni-progress-bar-warning-color-background	color	#dddbda
--avonni-progress-bar-bar-value-warning-color-background	color	#dd7a01
--avonni-progress-bar-label-text-color	color	#080707
--avonni-progress-bar-label-font-size	font	0.8125rem
--avonni-progress-bar-label-font-style	font	normal
--avonni-progress-bar-label-font-weight	font	400
--avonni-progress-bar-label-line-clamp	number	2
--avonni-progress-bar-value-text-color	color	#080707
--avonni-progress-bar-value-font-size	font	0.8125rem
--avonni-progress-bar-value-font-style	font	normal
--avonni-progress-bar-value-font-weight	font	700
--avonni-progress-bar-pin-text-color	color	#ffff
--avonni-progress-bar-pin-font-style	font	normal
--avonni-progress-bar-pin-font-weight	font	700
--avonni-progress-bar-pin-color-background	color	—

Key Considerations

• Value range: value is a percentage; supply a number between 0 and 100.
• Pin requires value: show-pin only renders when show-value is also set.
• Reference lines: Each entry supports label, value, variant, and borderStyle (e.g. dashed, dotted).
• Loading state: is-loading replaces the bar with a spinner; pair with loading-state-alternative-text for accessibility.
• Best Practice: Pair show-value with a value-prefix/value-suffix for context, and choose a theme that matches the meaning (e.g. success for healthy, error for critical).

---

Troubleshooting Common Issues

• Bar not filling: Confirm value is a number between 0 and 100, not a string with units.
• Value not visible: Set show-value; the pin additionally requires show-pin.
• Reference lines missing: Provide a reference-lines array where each entry has a numeric value.
• If issues persist: Contact our support team at [email protected] for assistance.