> 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-bar.md).

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

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

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

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

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