> ## Documentation Index
> Fetch the complete documentation index at: https://anvil.servicetitan.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Progress Bar - Web

> Progress Bars visually represent the completion of a task.

> [!NOTE]
>
> For development, import `ProgressBar` from
> `@servicetitan/anvil2`. For design, find it in the
> [Anvil2 file](https://www.figma.com/design/xaNQsvRKczoxu7pj0M6QT8/Anvil2-v3?node-id=210-4049).

![](https://mintcdn.com/servicetitan/H5FwKyiqhPVZ1UJQ/images/docs/web/components/shared/overview-of-progress-bar.png?fit=max\&auto=format\&n=H5FwKyiqhPVZ1UJQ\&q=85\&s=1c7d57824e28fa4f6064472ff034027d)

## Anatomy

The Progress Bar consists of four primary elements that work together to visually represent the completion of a task.

![Anatomy of a Progress
Bar](https://mintcdn.com/servicetitan/aip5_7K1pHSn1Axn/images/docs/web/components/progress-bar/design/anatomy-of-a-progress-bar.png?fit=max\&auto=format\&n=aip5_7K1pHSn1Axn\&q=85\&s=eb1cbf8e349a2a5985e2f67f90f3e824)

1. Label
2. Fill
3. Track
4. Status Indicator: the shared Status Icon, the same one Alert and Field Message use

## Options

The Progress Bar supports the following configurations to accommodate various progress representation scenarios.

### Status

progressbar-status

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/progressbar-status?file=src/App.tsx)

```tsx lines theme={null}
import { ProgressBar, Flex } from "@servicetitan/anvil2";

function App() {
  return (
    <Flex direction="column" gap="8" grow={1}>
      <ProgressBar label="Default" value="30" />
      <ProgressBar label="Success" max="100" value="100" />
      <ProgressBar error label="Error" value="70" />
    </Flex>
  );
}

export default App;
```

| Status type | Description |
| - | - |
| Info (Default) | Used to convey the general use of the Progress Bar |
| Success | Optionally used to denote the completion of the Progress Bar. |
| Error | Used to convey that something went wrong with the operation. |

### Value

A numeric value visually changes the progression. Use this when the actual percentage of completion can be determined.

progressbar-value

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/progressbar-value?file=src/App.tsx)

```tsx lines theme={null}
import { ProgressBar, Flex } from "@servicetitan/anvil2";

function App() {
  return (
    <Flex direction="column" gap="8" grow={1}>
      <ProgressBar label="Value of 0" value="0" />
      <ProgressBar label="Value of 50" value="50" />
      <ProgressBar label="Value of 100" value="100" />
    </Flex>
  );
}

export default App;
```

### Indeterminate

Set an indeterminate value when it isn't well known how long an operation will take.

progressbar-indeterminate

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/progressbar-indeterminate?file=src/App.tsx)

```tsx lines theme={null}
import { ProgressBar, Flex } from "@servicetitan/anvil2";

function App() {
  return (
    <Flex direction="column" gap="8" grow={1}>
      <ProgressBar label="Indeterminate" indeterminate />
    </Flex>
  );
}

export default App;
```

### Label

#### Label

progressbar-label

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/progressbar-label?file=src/App.tsx)

```tsx lines theme={null}
import { ProgressBar, Flex } from "@servicetitan/anvil2";

function App() {
  return (
    <Flex direction="column" gap="8" grow={1}>
      <ProgressBar label="Label text" value="50" />
    </Flex>
  );
}

export default App;
```

#### More Info

progressbar-moreinfo

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/progressbar-moreinfo?file=src/App.tsx)

```tsx lines theme={null}
import { ProgressBar, Flex } from "@servicetitan/anvil2";

function App() {
  return (
    <Flex direction="column" gap="8" grow={1}>
      <ProgressBar
        label="Label text"
        labelProps={{ moreInfo: "Tooltip explaining the Progress Bar" }}
        value="50"
      />
    </Flex>
  );
}

export default App;
```

#### No Label

progressbar-label-false

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/progressbar-label-false?file=src/App.tsx)

```tsx lines theme={null}
import { ProgressBar, Flex } from "@servicetitan/anvil2";

function App() {
  return (
    <Flex direction="column" gap="8" grow={1}>
      <ProgressBar value="50" aria-label="Progress Bar Label" />
      <ProgressBar error value="50" aria-label="Progress Bar Label" />
      <ProgressBar value="100" aria-label="Progress Bar Label" />
    </Flex>
  );
}

export default App;
```

#### Description And Error Text

progressbar-message

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/progressbar-message?file=src/App.tsx)

```tsx lines theme={null}
import { ProgressBar, Flex } from "@servicetitan/anvil2";

function App() {
  return (
    <Flex direction="column" gap="8" grow={1}>
      <ProgressBar label="Default" value="50" description="Description text" />
      <ProgressBar label="Error" value="50" error="Error Text" />
      <ProgressBar
        label="Success"
        value="100"
        description="Description Text"
        error="Error Text"
      />
    </Flex>
  );
}

export default App;
```

## Behavior

The Progress Bar responds to content overflow by wrapping text labels while maintaining consistent visual representation.

### Overflow

The text label of a Progress Bar will wrap when not enough space is provided.

progressbar-overflow

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/progressbar-overflow?file=src/App.tsx)

```tsx lines theme={null}
import { ProgressBar } from "@servicetitan/anvil2";

function App() {
  return (
    <div style={{ maxWidth: "250px" }}>
      <ProgressBar
        label="Text overflow of the label that will wrap when not enough space is present"
        value="50"
      />
    </div>
  );
}

export default App;
```

## Usage Guidelines

| Standard | Requirement |
| - | - |
| DoShow system operation progress | Progress Bars are best used to show the progression of a system operation. This can include things such as downloading, uploading, and progress on a submission. |
| DoSet a value when accuracy allows | If progression can be roughly estimated and still be accurate, set a value. |
| DoPrefer indeterminate over guesses | If accuracy is not realistic, the indeterminate state is preferable over an inaccurate value. |
| DoTransition from indeterminate to a value | If it's not possible to know at the start, but during processing an estimate can be made, the progress bar can start as indeterminate but become a set value. |
| Don'tUse for data visualizations | Progress Bar's scope is limited to system operations. It should not be extended to contexts such as dashboard analytics and flow progression. |
| Don'tUse to denote steps in a flow | Progress Bar should not be used to convey steps in a flow. Use the Stepper instead. |
| Don'tRestyle Progress Bar colors | Progress Bars only support visual states for info, success, and error. Don't restyle the Progress Bar individually unless part of a wider theming. |

## Content

Content within the Progress Bar should clearly communicate the task being completed and its current status.

## Keyboard Interaction

Users can navigate the Progress Bar using standard keyboard controls.

### Accessibility

#### Provide ARIA labels when a visual label is not used

When using a Progress Bar without a label, provide one through the usage of an `aria-label`.

For more guidance on progress indicators and status updates, see [changing content best practices](https://anvil.servicetitan.com/docs/accessibility/changing-content.md).

## Code

**Implementation**

progressbar-playground

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/progressbar-playground?file=src/App.tsx)

```tsx lines expandable theme={null}
import { ProgressBar } from "@servicetitan/anvil2";

function App() {
  return (
    <ProgressBar
      label="Value 50"
      value="50"
      description="Description for Progress Bar"
    />
  );
}

export default App;
```

## Common Examples

```tsx theme={null}
import { ProgressBar } from "@servicetitan/anvil2";

function ExampleComponent() {
  return (
    <ProgressBar
      label="50% Completed"
      value={50}
      description="Description for Progress Bar"
    />
  );
}
```

### Progress bar fill percentage

Progress bars show a completed state when the `value` is equal to the `max` value, which is `100` by default. Otherwise, the `value` is divided by the `max` to determine what percentage the bar should be visually filled to.

progressbar-value

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/progressbar-value?file=src/App.tsx)

```tsx lines expandable theme={null}
import { ProgressBar, Flex } from "@servicetitan/anvil2";

function App() {
  return (
    <Flex direction="column" gap="8" grow={1}>
      <ProgressBar label="Value of 0" value="0" />
      <ProgressBar label="Value of 50" value="50" />
      <ProgressBar label="Value of 100" value="100" />
    </Flex>
  );
}

export default App;
```

### Showing indeterminate progress bars

If the `indeterminate` prop is set to `true`, the progress bar will show an animation to signal to the user that the progress has not been determined.

progressbar-indeterminate

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/progressbar-indeterminate?file=src/App.tsx)

```tsx lines expandable theme={null}
import { ProgressBar, Flex } from "@servicetitan/anvil2";

function App() {
  return (
    <Flex direction="column" gap="8" grow={1}>
      <ProgressBar label="Indeterminate" indeterminate />
    </Flex>
  );
}

export default App;
```

### Progress bar error state

Use the `error` prop to show an error state. If a `string` is provided to the `error` prop, a message will also be displayed.

progressbar-error

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/progressbar-error?file=src/App.tsx)

```tsx lines expandable theme={null}
import { ProgressBar, Flex } from "@servicetitan/anvil2";

function App() {
  return (
    <Flex direction="column" gap="8" style={{ minWidth: "20.5rem" }}>
      <ProgressBar value="25" label="Value 25/100" error />
      <ProgressBar
        value="99"
        label="Value 99/100"
        error="Something went wrong"
      />
    </Flex>
  );
}

export default App;
```

**ProgressBar Props**

```tsx theme={null}
<ProgressBar
  label="50% Completed"
  value={50}
  max={100}
  indeterminate={false}
  error={false}
  errorAriaLive="assertive"
  description="Description text"
  labelProps={{ moreInfo: "Additional label text", moreInfoOpen: true }}
/>
```

## `ProgressBar` Props

**label** `ReactNode`

One of `label`, `aria-label`, or `aria-labelledby` is required. If
`undefined`, `labelProps` cannot be used.

**description** `ReactElement | string`

**error** `ReactElement | string | boolean` (default: false)

**errorAriaLive** `"off" | "assertive" | "polite"` (default: assertive)

Overrides how assistive technologies will announce an error message.

**indeterminate** `boolean`

Displays indeterminate animation when `true`. Cannot be used with `value`.

**labelProps** `\{ moreInfo?: ReactNode; moreInfoOpen?: boolean \}`

Properties passed to the `Label` component. Can only be used with `label`.

**max** `number | string` (default: 100)

The maximum value, used to determine bar fill percentage.

**value** `number | string`

The current value, used to determine bar fill percentage. Cannot be used with
`indeterminate`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.