> For the complete documentation index, see [llms.txt](https://docs.avonnicomponents.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avonnicomponents.com/lwc-components/core-components/progress-indicator.md).

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

```html
<!-- 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>
```

```js
// 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.

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

```js
// 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.                        |

### Styling Hooks

| CSS Variable                                                 | Type  | Default   |
| ------------------------------------------------------------ | ----- | --------- |
| `--avonni-progress-indicator-bar-color-background`           | color | `#dddbda` |
| `--avonni-progress-indicator-bar-completed-color-background` | color | `#0176d3` |

## 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 <support@avonni.app> for assistance.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.avonnicomponents.com/lwc-components/core-components/progress-indicator.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.