Progress Indicator

avonni-progress-indicator

The Avonni Progress Indicator displays a user's progress through a sequence of steps in a process.

Overview

Progress Indicator is a Lightning Web Component that displays a user's progress through a sequence of steps in a process.

Use it in your own Lightning Web Components to guide multi-step flows such as wizards, checkouts, or onboarding. You define the steps as data and control which are completed, current, disabled, in error, or in warning—plus optional per-step buttons and popovers—all through the component's attributes.

Use Cases

• Wizards: Walk users through a guided, multi-step task.
• Checkout flows: Show progress from cart through confirmation.
• Onboarding: Track setup steps and highlight what's next.
• Approval pipelines: Mark stages as complete, in error, or pending.
• Record lifecycles: Visualize where a record sits in a defined process.

---

Variant Guidelines

Variant	Use Case
base	Default flat step indicators.
shaded	Adds a light gray border for extra contrast.

---

Use Case Examples

Example 1: Checkout flow

Scenario: Track a customer through a five-step checkout, marking earlier steps complete and flagging one that needs attention.

<!-- checkoutProgress.html -->
<template>
    <avonni-progress-indicator
        steps={steps}
        current-step="review"
        completed-steps={completedSteps}
        error-steps={errorSteps}
        disabled-steps={disabledSteps}
        variant="shaded"
    ></avonni-progress-indicator>
</template>

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

export default class CheckoutProgress extends LightningElement {
    steps = [
        { value: 'account', label: 'Account details' },
        { value: 'shipping', label: 'Shipping address' },
        { value: 'payment', label: 'Payment method' },
        { value: 'review', label: 'Review order' },
        { value: 'confirm', label: 'Confirmation' }
    ];
    completedSteps = ['account', 'shipping'];
    errorSteps = ['payment'];
    disabledSteps = ['confirm'];
}

Result: A shaded indicator with the first two steps complete, "Payment method" flagged in error, "Review order" as the current step, and "Confirmation" disabled.

Example 2: Handling step interaction

Scenario: Respond when a user clicks a step to navigate the flow.

<!-- guidedFlow.html -->
<template>
    <avonni-progress-indicator
        steps={steps}
        current-step={currentStep}
        onstepclick={handleStepClick}
    ></avonni-progress-indicator>
</template>

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

export default class GuidedFlow extends LightningElement {
    currentStep = 'account';
    steps = [
        { value: 'account', label: 'Account details' },
        { value: 'shipping', label: 'Shipping address' }
    ];

    handleStepClick(event) {
        this.currentStep = event.detail.value; // navigate to clicked step
    }
}

Result: Clicking a step fires stepclick with that step's value, letting you advance the flow.

---

Specifications

Attributes

Name	Description	Type	Default	Required
completed-steps	Array of completed steps values.	string[]	—
current-step	Set current-step to match the value attribute of one of progress-step components.	String	—
disabled-steps	Array of disabled steps values.	string[]	—
error-steps	Array of error steps values.	string[]	—
steps	Array of steps objects.	AvonniProgressIndicatorStep[]	—
variant	Changes the appearance of the progress indicator for the base type only. Valid values are base or shaded. The shaded variant adds a light gray border to the step indicators.	String	"base"
warning-steps	Array of warning steps values.	string[]	—

Custom Events

stepblur

The event fired when a step looses focus.

The stepblur event returns the following parameters.

Parameter	Type	Description
value	string	Unique value of the blurred step.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

stepbuttonclick

The event fired when a step button is clicked.

The stepbuttonclick event returns the following parameters.

Parameter	Type	Description
value	string	Unique value of the step the clicked button belongs to.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

stepclick

The event fired when a step is clicked.

The stepclick event returns the following parameters.

Parameter	Type	Description
value	string	Unique value of the clicked step.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

stepfocus

The event fired when a step receives focus.

The stepfocus event returns the following parameters.

Parameter	Type	Description
value	string	Unique value of the focused step.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

stepmouseenter

The event fired when the mouse enters a step.

The stepmouseenter event returns the following parameters.

Parameter	Type	Description
value	string	Unique value of the step entered by the mouse.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

stepmouseleave

Event that fires when mouse leaves step.

The stepmouseleave event returns the following parameters.

Parameter	Type	Description
value	string	Unique value of the step left by the mouse.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

steppopoverclick

The event fired when a step popover is clicked.

The steppopoverclick event returns the following parameters.

Parameter	Type	Description
value	string	Unique value of the step the clicked popover belongs to.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

stepblur

The event fired when a step looses focus.

The stepblur event returns the following parameters.

Parameter	Type	Description
value	string	Unique value of the blurred step.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

stepbuttonclick

The event fired when a step button is clicked.

The stepbuttonclick event returns the following parameters.

Parameter	Type	Description
value	string	Unique value of the step the clicked button belongs to.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

stepclick

The event fired when a step is clicked.

The stepclick event returns the following parameters.

Parameter	Type	Description
value	string	Unique value of the clicked step.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

stepfocus

The event fired when a step receives focus.

The stepfocus event returns the following parameters.

Parameter	Type	Description
value	string	Unique value of the focused step.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

stepmouseenter

The event fired when the mouse enters a step.

The stepmouseenter event returns the following parameters.

Parameter	Type	Description
value	string	Unique value of the step entered by the mouse.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

stepmouseleave

Event that fires when mouse leaves step.

The stepmouseleave event returns the following parameters.

Parameter	Type	Description
value	string	Unique value of the step left by the mouse.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

steppopoverclick

The event fired when a step popover is clicked.

The steppopoverclick event returns the following parameters.

Parameter	Type	Description
value	string	Unique value of the step the clicked popover belongs to.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

Styling Hooks

CSS Variable	Type	Default
--avonni-progress-indicator-bar-color-background	color	#dddbda
--avonni-progress-indicator-bar-completed-color-background	color	#0176d3
--avonni-progress-indicator-step-popover-color-background	color	#e8e8e8
--avonni-progress-indicator-step-popover-text-color	color	#080707
--avonni-progress-indicator-step-popover-completed-color-background	color	#0176d3
--avonni-progress-indicator-step-popover-completed-text-color	color	#ffffff
--avonni-progress-indicator-step-popover-button-color-background	color	#e8e8e8
--avonni-progress-indicator-step-popover-button-icon-color-background	color	#706e6b
--avonni-progress-indicator-step-popover-button-color-background-hover	color	#f4f6fe
--avonni-progress-indicator-step-popover-button-completed-color-background	color	#0176d3
--avonni-progress-indicator-step-popover-button-icon-completed-color-background	color	#ffffff
--avonni-progress-indicator-step-label-text-color	color	#080707
--avonni-progress-indicator-step-label-font-size	font	0.875rem
--avonni-progress-indicator-step-label-font-style	font	normal
--avonni-progress-indicator-step-label-font-weight	font	700
--avonni-progress-indicator-step-description-text-color	color	#080707
--avonni-progress-indicator-step-description-font-size	font	0.815rem
--avonni-progress-indicator-step-description-font-style	font	normal
--avonni-progress-indicator-step-description-font-weight	font	400

Key Considerations

• Unique values: Each step's value must be unique—the state arrays match steps by value.
• State precedence: A step can be completed, current, disabled, in error, or in warning; set these via the corresponding arrays.
• Steps as data: Provide steps as an array; mutate the bound property to re-render rather than editing the DOM.
• Buttons and popovers: Steps can include button and popover fields that emit their own events when clicked.
• Best Practice: Give every step a unique value and reference those same values in the completed-steps, current-step, and other state arrays so the indicator stays in sync.

---

Troubleshooting Common Issues

• Steps not updating: Reassign the steps, completed-steps, or current-step properties with new arrays/values so LWC detects the change.
• Wrong step highlighted: Confirm the values in the state arrays exactly match the value of each step object.
• Events not firing: Verify the on... handlers are wired in the template and the step exposes a button or popover where applicable.
• If issues persist: Contact our support team at [email protected] for assistance.