> 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/dynamic-components/components/progress-indicator.md).

# Progress Indicator

The Avonni Progress Indicator component displays a multi-step progress indicator that tracks completion through a sequence of steps. Use it to visualize where a record or user stands in a process — such as an Opportunity stage, a Case status, or a custom onboarding workflow.

## Overview

The component ships with two builder presets: **Progress Indicator** (the default horizontal dot-and-line style) and **Path** (Salesforce Sales Path-style chevron steps). Both presets use the same component and properties — the preset just pre-fills the **Type** setting for you.

Beyond those two presets, the component supports four additional types: **Vertical**, **Bar**, **Circle**, and **Vertical Navigation**, giving you six display variants in total.

| Type                    | What it looks like                                                                            | Best for                                                                                                          |
| ----------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Horizontal**          | A row of step indicators connected by a line, labels above or below each dot.                 | Default desktop pattern. Works for 3–6 short-labeled steps.                                                       |
| **Vertical**            | A vertical column of steps with content and optional sub-steps and actions next to each step. | Long step lists, mobile, anywhere with limited horizontal space, processes that need supporting content per step. |
| **Bar**                 | A single horizontal progress bar with a percentage.                                           | Simple completion meters where step names don't matter.                                                           |
| **Circle**              | A circular progress ring with a percentage in the middle.                                     | Compact KPI tiles, "% complete" indicators.                                                                       |
| **Path**                | Salesforce Sales Path style — chevron-shaped steps.                                           | Opportunity stages, Case statuses, anything that mirrors native Salesforce Path.                                  |
| **Vertical Navigation** | A vertical list styled like a navigation menu, each step clickable.                           | Wizard-style left-rail navigation, multi-page forms.                                                              |

You can drive the steps from a Salesforce picklist field (such as Opportunity `StageName` or Case `Status`), a Query, or manually defined steps. Steps can be made clickable and wired to Interactions, allowing users to advance a process directly from the component.

## Configuration

To configure the Progress Indicator, select it on the canvas. The **Edit Progress Indicator** panel opens on the right with three tabs: **Properties**, **Interactions**, and **Style**. The sections below mirror the Properties tab.

### Data Source

The **Data Source** setting determines where the steps come from.

| Source       | Description                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------------------- |
| **Manual**   | Define steps directly in the component configuration — ideal for fixed, known workflows.                |
| **Picklist** | Retrieve step values from a Salesforce picklist field (e.g., Opportunity `StageName` or Case `Status`). |

### Data Mapping

When using Manual or Picklist, configure the **Data Mappings** section to map fields to step properties. Key mappings include:

* **Value** — The step identifier; matched against **Current Step** to determine which step is active.
* **Label** — The display text shown below (or next to) each step indicator.
* **Description** — Optional descriptive text associated with the step.
* **Icon Name** — Icon displayed on the step indicator.
* **Href** — Makes the step label a clickable link.
* **Disabled** — Marks the step as non-interactive.
* **Hidden** — Hides the step from the indicator.

### General

These settings appear for all or most types. Where a setting is only available for certain types, that is noted below.

#### Type

Changes the visual pattern of the indicator. Valid values are **Horizontal**, **Vertical**, **Bar**, **Circle**, **Path**, and **Vertical Navigation**. Defaults to **Horizontal**. This is the first decision — many other settings only appear after you choose a type.

#### Variant

Changes the appearance of the progress indicator. **Base** is the standard look; **Shaded** adds a light gray border around the step indicators. Defaults to **Base**. Requires **Type** = Horizontal, Vertical, or Vertical Navigation.

#### Format

Sets the progression format. **Linear** requires steps to be completed in order; **Non Linear** allows any step to be active regardless of prior completion. Defaults to **Linear**. Requires **Type** = Horizontal, Vertical, or Path.

#### Current Step

Sets which step is currently active. Enter the value that matches the **Value** property of one of the configured steps. Typically bound to a record field — for example, `{!$Record.StageName}`. If not set, the first step is used.

#### Completed Steps

An array of step values that are marked as completed (shown in green or with a checkmark). Requires **Type** = Horizontal, Vertical, or Path.

#### Error Steps

An array of step values that are marked as in error. Requires **Type** = Horizontal, Vertical, or Path.

#### Show Step Number

When enabled, the step indicator displays the step's number instead of a dot when no icon is set. Requires **Type** = Horizontal or Vertical.

#### Show Step Label

When enabled, the step label is displayed below the indicator. Requires **Type** = Horizontal or Bar.

#### Step Label Position

Controls where step labels appear relative to the indicator. Options: **Top**, **Bottom** (default). Requires **Type** = Horizontal.

#### Hide Bar Value

When enabled, hides the percentage value displayed inside the progress bar. Requires **Type** = Bar.

#### Mark as Complete

When enabled, all steps are marked as completed. Useful for showing a "process finished" state.

#### Has Error

When enabled, the current step is displayed in an error state and the error icon is shown on the step indicator. Requires **Type** = Horizontal, Vertical, or Path.

#### Enable click for each steps

When enabled, all steps become clickable. Required for the **Step Click** interaction to fire. Requires **Type** = Horizontal, Vertical, Path, or Vertical Navigation.

#### Alternative Text

Accessibility text describing the component for screen readers.

### Step Icon

This panel is available when **Type** = Horizontal or Vertical.

#### Icon Alignment

Aligns the left icon and actions to the top of the step instead of the center. Useful when a step has multiline content. Options: **Center** (default), **Top**. Requires **Type** = Vertical.

#### Icon Size

Sets the size of the step icon bubbles. At **Medium** or **Large**, steps without an icon display their step number instead of a dot. Options: **Small** (default), **Medium**, **Large**. Requires **Type** = Horizontal or Vertical.

#### Error Icon Name

The SLDS icon displayed on steps in an error state. Defaults to `utility:error`. Available when **Hide Error Icon** is off. Requires **Type** = Horizontal, Vertical, or Path.

#### Error Image Source

URL of a custom image to display on error steps instead of an icon.

#### Hide Error Icon

When enabled, hides the error icon entirely. Requires **Type** = Horizontal, Vertical, or Path.

### Current Step Icon

This panel is available when **Type** = Horizontal or Vertical. Use it to replace the active step's dot with a custom icon or image.

#### Icon Name

An SLDS icon name to display on the currently active step (for example, `utility:checkin`).

#### Image Source

URL of an image to display on the active step instead of an icon.

### Steps (Data Source)

Each step represents one stop in the process. You can populate steps three ways:

| Source       | When to use                                                                                               | How to configure                                                                  |
| ------------ | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| **Picklist** | When steps map to a Salesforce picklist field (Opportunity `StageName`, Case `Status`, custom picklists). | Pick the Object and Field API Name. The component reads the picklist values live. |
| **Query**    | When steps are records (for example, Approval Process Steps, custom configuration objects).               | Configure a Query and map record fields to step properties.                       |
| **Manual**   | When the steps are static and never change.                                                               | Add steps one by one in the Steps editor.                                         |

**Step Properties**

Each step supports the following properties regardless of source:

| Property      | Description                                                                                                                                                         |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Label**     | The text displayed for the step (for example, "Qualification").                                                                                                     |
| **Value**     | The internal identifier used in Current Step, Completed Steps, and Error Steps. Must be unique. For picklist sources, this is automatically the picklist API value. |
| **Disabled**  | Greys out the step and prevents clicks.                                                                                                                             |
| **Hidden**    | Removes the step from the indicator.                                                                                                                                |
| **Content**   | Rich text shown next to or below the step (Vertical and Path types).                                                                                                |
| **Icon Name** | SLDS icon to display on this step's indicator.                                                                                                                      |

**Vertical Type — Sub Steps and Actions**

The Vertical type (and Vertical Navigation) adds two more configurable areas per step.

**Sub Steps** — nested steps shown beneath a parent step. Each sub-step has its own **Label**, **Value**, **Disable Step**, **Hide Step**, **Actions**, **Visible Action Buttons**, **Hide Actions**, and **Disable Actions** settings.

**Actions** — buttons displayed on the right side of a step. Used for things like "Edit", "View Details", or "Send Notification". Each action has:

| Action Property           | Description                                                        |
| ------------------------- | ------------------------------------------------------------------ |
| **Label**                 | Text shown on the action button.                                   |
| **Name**                  | Unique identifier passed to the **Step Action Click** interaction. |
| **Icon Name**             | SLDS icon for the button.                                          |
| **Disabled** / **Hidden** | Standard visibility controls.                                      |

Per-step settings on the Vertical type also include **Visible Action Buttons** (how many to show before collapsing to a menu), **Hide Actions**, and **Disable Actions**.

### Set Component Visibility

All components support conditional visibility — see [Component Visibility](/dynamic-components/core-concepts/component-visibility.md).

## Use Cases

### Visualize Opportunity Stages on a Record Page

Build a Path-style progress indicator that shows the current Opportunity stage, marks completed stages as green, and lets users advance the stage with a click.

{% stepper %}
{% step %}

#### Add the Progress Indicator to the Canvas

* From the **Component Library** (left sidebar), drag the **Progress Indicator** component onto the Canvas.
* In the Properties Panel (right), set **Type** to `Path`.

*Why: The Path type is the closest visual match to Salesforce's native Sales Path and the one users are most familiar with on Opportunities.*
{% endstep %}

{% step %}

#### Connect the steps to the Opportunity Stage picklist

* In the **Steps** section of the Properties Panel, set the data source to **Picklist**.
* **Object:** `Opportunity`
* **Field API Name:** `StageName`
* **Record Type:** Select the appropriate record type if your org uses them.

*Why: This pulls the live picklist values directly from Salesforce — when admins change the stages in Setup, the component updates automatically.*
{% endstep %}

{% step %}

#### Set the current step to the record's stage

* In the **Current Step** field, enter `{!$Record.StageName}`.

*Why: This binds the indicator's active step to the record being viewed, so it shows the right stage on every Opportunity.*
{% endstep %}

{% step %}

#### Make the steps clickable

* Enable **Enable click for each steps**.
* Open the **Interactions** tab.
* On the **Step Click** trigger, add an action: **Update Record**.
  * **Object:** `Opportunity`
  * **Record ID:** `{!$Record.Id}`
  * **Field:** `StageName` = `{!Last Clicked Step Value}`

*Why: Clicking a stage updates the Opportunity record to that stage. Last Clicked Step Value contains the picklist value of the step the user clicked.*
{% endstep %}

{% step %}

#### Save and Activate

* Click **Save** in the top right.
* Click **Activate** and add the component to the Opportunity Lightning Record Page [using the Lightning App Builder](/dynamic-components/core-concepts/publishing-your-dynamic-components.md).
  {% endstep %}
  {% endstepper %}

### Case Lifecycle on a Service Console

A Vertical indicator showing Case Status with sub-steps for the support process.

{% stepper %}
{% step %}

#### Configure the indicator

* **Type:** `Vertical`
* **Format:** `Non Linear` (support cases sometimes go backwards)
* Set **Steps** source to **Picklist**: Object = `Case`, Field = `Status`.
* **Current Step:** `{!$Record.Status}`
  {% endstep %}

{% step %}

#### Add per-step actions

* On the "Working" step, add an action with **Label** = `Escalate`, **Name** = `escalate`, **Icon Name** = `utility:warning`.
* On the "Escalated" step, add an action with **Label** = `De-escalate`, **Name** = `deescalate`, **Icon Name** = `utility:undo`.
  {% endstep %}

{% step %}

#### Wire actions to a Flow

* In **Interactions**, on the **Step Action Click** trigger, add **Execute Flow** = `Case_Escalation_Flow`.
* Pass `{!Last Clicked Step Action — Action Name}` and `{!$Record.Id}` to the Flow.
  {% endstep %}
  {% endstepper %}

### Onboarding Wizard with Vertical Navigation

A multi-step user onboarding flow using Vertical Navigation as a left-rail menu.

{% stepper %}
{% step %}

#### Build the steps

* **Type:** `Vertical Navigation`
* Steps (Manual): `welcome`, `profile`, `team`, `preferences`, `done`.
* **Current Step:** `{!OnboardingStage}` (a variable on the record or component).
* Enable **Enable click for each steps**.
  {% endstep %}

{% step %}

#### Show the right content for each step

* Place a **Container** next to the navigation indicator.
* Use Conditional Visibility on the Container's children — each one visible only when `OnboardingStage` matches its step value.
  {% endstep %}

{% step %}

#### Update the variable on click

On the **Step Click** trigger, add **Update Variable**: `OnboardingStage` = `{!Last Clicked Step Value}`.
{% endstep %}
{% endstepper %}

## Interactions

[Interactions](/dynamic-components/component-builder/interactions.md) define what happens when users interact with the Progress Indicator. Configure them from the **Interactions** tab of the Edit Progress Indicator panel.

### Step Click

Fires when a user clicks a step. Requires **Enable click for each steps** to be enabled (or at least one interaction configured on this trigger). Use the **clickedStep** output to read the full step object, or use **currentStep** to get the value of the clicked step and branch your flow logic or update a record field accordingly.

### Step Action Click

Fires when a user clicks an action button on a step. Use the **clickedStepActionName** output to identify which action was clicked, and **clickedStepActionStep** to get the step the action belongs to — useful for dispatching different flow logic per action.

## Mobile Configuration

The six types behave very differently on small screens. Picking the right type for mobile is the most important decision.

| Type                    | Mobile behavior                                                                                                           | Recommended?                                                   |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| **Vertical**            | Renders as a vertical list — perfect fit for narrow screens.                                                              | Best choice for any process with more than 3–4 steps.          |
| **Vertical Navigation** | Renders as a vertical menu list.                                                                                          | Best for wizard-style mobile flows.                            |
| **Bar**                 | Scales to container width, stays compact.                                                                                 | Always fine on mobile.                                         |
| **Circle**              | Stays compact, scales nothing.                                                                                            | Always fine on mobile.                                         |
| **Horizontal**          | Steps stay on one line. The component scrolls horizontally if steps don't fit, but step labels become cramped or get cut. | Only acceptable with 3 or fewer steps and short labels.        |
| **Path**                | Same as Horizontal — chevrons stay on one line and overflow with horizontal scroll.                                       | Acceptable for 3–4 short stages, otherwise switch to Vertical. |

**Required settings for a mobile-friendly indicator**

| Setting                              | Value                                         | Why                                                              |
| ------------------------------------ | --------------------------------------------- | ---------------------------------------------------------------- |
| **Type**                             | Vertical, Vertical Navigation, Bar, or Circle | Horizontal and Path overflow on phones.                          |
| **Show Step Label** (Horizontal/Bar) | Off, or use very short labels                 | Labels under each step squish together below 480px.              |
| **Icon Size** (Horizontal/Vertical)  | Small                                         | Medium and Large icons take up disproportionate space on phones. |
| **Step labels**                      | Keep under 12 characters                      | Long labels wrap awkwardly or get truncated on narrow viewports. |

**Responsive pattern: different type per device**

To use the Path type on desktop and switch to Vertical on mobile, place two Progress Indicator components inside a Columns layout and toggle their visibility per device:

1. Add a **Columns** component with two columns, each set to **Size = 12** for All devices.
2. Drop the Path indicator in column 1 and the Vertical indicator in column 2.
3. Use a **Conditional Visibility** rule on each:
   * Path indicator: show when device width ≥ 768px.
   * Vertical indicator: show when device width < 768px.

Both indicators read from the same data source, so the user sees the right one on each device.

{% hint style="info" %}
Breakpoints in Avonni are based on **container width**, not screen width. A Progress Indicator inside a narrow Lightning Page region hits the mobile breakpoint earlier than one in a full-width region.
{% endhint %}

## Output Variables

The Progress Indicator exposes these output variables you can reference elsewhere on the page after the user interacts with it.

### Step Click

When a user clicks a step, this variable updates with the clicked step's data.

| Output variable  | Type   | What it returns                                                                           |
| ---------------- | ------ | ----------------------------------------------------------------------------------------- |
| **Clicked Step** | Object | The full step object that was last clicked — its value, label, and other step properties. |

> **Example:** When a user clicks a stage in a Path indicator, use **Clicked Step** to read the step's value and pass it to an Update Record action that advances the Opportunity stage.

### Step Action Click

When a user clicks an action button on a step (Vertical type), these variables identify which action was clicked and on which step.

| Output variable                       | Type          | What it returns                                                                                              |
| ------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------ |
| **Clicked Step Action - Action Name** | Text (String) | The `name` of the action button that was clicked. Use it to branch flow logic per action.                    |
| **Clicked Step Action - Step**        | Object        | The full step object that contained the clicked action button — its value, label, and other step properties. |

> **Example:** When a user clicks "Escalate" on the "Working" step, use **Clicked Step Action - Action Name** to confirm the action name and **Clicked Step Action - Step** to confirm which step it came from before triggering a Case Escalation Flow.

## Troubleshooting Common Issues

* **No steps appear** — The Steps data source isn't configured, or the Picklist field returns no values for the user's record type. Open the Steps section and verify the source; for Picklist sources, confirm the user has a matching Record Type and that the picklist has values.
* **Current Step doesn't highlight any step** — The Current Step value doesn't match any step's value; picklist API names are case-sensitive. In Debug, log `{!$Record.StageName}` and compare it character-for-character with the step values — use the API name (e.g. `Closed Won`), not the label.
* **Clicking a step does nothing** — Enable click for each steps is off, or no Interaction is configured on the Step Click trigger. Enable **Enable click for each steps** and add at least one action on the Step Click trigger.
* **Step Click fires but the record doesn't update** — The Update Record action is missing the Record ID, or the field mapping uses Last Clicked Step Label instead of Last Clicked Step Value. Confirm `{!$Record.Id}` is set as the Record ID and use **Last Clicked Step Value** for picklist field updates.
* **Step Action Click trigger doesn't fire** — The component Type is not Vertical (actions only exist on Vertical), or the action's Name is empty. Switch Type to Vertical and make sure each action has a unique Name.
* **Variant or Format settings are missing from the panel** — These settings are Type-dependent: Variant only shows for Horizontal, Vertical, and Vertical Navigation; Format only shows for Horizontal, Vertical, and Path. Change Type if you need a setting that's hidden, or rely on the defaults for the current Type.
* **Steps appear in the wrong order** — For Picklist sources, the picklist sort order isn't set or doesn't match the desired display order; for Manual sources, steps were dragged out of order. Set the Picklist Sort Order in the Properties Panel, or reorder steps manually in the Steps editor.
* **Error icon doesn't appear on a step in the Error Steps array** — Either Hide Error Icon is on, or the step's value in the array doesn't match. Turn off **Hide Error Icon** and verify the value matches the step's API value exactly.
* **Horizontal indicator overflows or scrolls horizontally on mobile** — The Horizontal type stays on one line and scrolls when steps don't fit. Switch the Type to Vertical for mobile, or reduce step labels and keep the count under 4.
* **Mark as Complete is on but steps don't show as completed** — Mark as Complete is overridden by an explicit Current Step that points to an earlier step. Either remove the Current Step value or set it to the last step's value.
* **Sub Steps configured but don't appear** — Sub Steps are only supported on the Vertical type. Switch Type to Vertical, or move the sub-step content into the step's Content field.


---

# 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/dynamic-components/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.