Progress Bar

For development, import ProgressBar from @servicetitan/anvil2. For design, find it in the Anvil2 file.

Anatomy

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

Label
Fill
Track
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

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.

Indeterminate

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

Label

More Info

No Label

Description And Error Text

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.

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.

Code

Implementation
ProgressBar Props

Common Examples

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.

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.

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

ReactNode

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

ReactElement | string

ReactElement | string | boolean

default:"false"

"off" | "assertive" | "polite"

default:"assertive"

Overrides how assistive technologies will announce an error message.

boolean

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

{ moreInfo?: ReactNode; moreInfoOpen?: boolean }

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

number | string

default:"100"

The maximum value, used to determine bar fill percentage.

number | string

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

Concepts & Guidelines

Anvil2

Resources

Progress Bar - Web

Anatomy

Options

Status

Value

Indeterminate

Label

Label

More Info

No Label

Description And Error Text

Behavior

Overflow

Usage Guidelines

Content

Keyboard Interaction

Accessibility

Provide ARIA labels when a visual label is not used

Code

Common Examples

Progress bar fill percentage

Showing indeterminate progress bars

Progress bar error state

`ProgressBar` Props

​Anatomy

​Options

​Status

​Value

​Indeterminate

​Label

​Label

​More Info

​No Label

​Description And Error Text

​Behavior

​Overflow

​Usage Guidelines

​Content

​Keyboard Interaction

​Accessibility

​Provide ARIA labels when a visual label is not used

​Code

​Common Examples

​Progress bar fill percentage

​Showing indeterminate progress bars

​Progress bar error state

​ProgressBar Props

Anatomy

Options

Status

Value

Indeterminate

Label

Label

More Info

No Label

Description And Error Text

Behavior

Overflow

Usage Guidelines

Content

Keyboard Interaction

Accessibility

Provide ARIA labels when a visual label is not used

Code

Common Examples

Progress bar fill percentage

Showing indeterminate progress bars

Progress bar error state

`ProgressBar` Props