Progress

<esp-progress>

A progress indicator that supports both determinate and indeterminate modes, rendered as a linear bar or a circle.

In determinate mode, set value and optionally max to show a fill bar representing progress toward completion:

In indeterminate mode (the default when no value is set), an animated bar communicates that work is happening without a known endpoint:

The three size presets:

Color variants match the design system:

Click the button to watch the progress bar fill over ten seconds:

Indeterminate mode with different variants:

Circle mode displays a ring that fills clockwise. Set mode="circle" and optionally show-value to display the percentage in the center:

Circle size presets:

Indeterminate circle mode:

Click the button to watch the circle fill over ten seconds:

Attributes

<esp-progress> has the following attributes:

value

value has a default value of null.

The current progress value. Set to null (or omit) for indeterminate mode. Values are clamped to 0..max.

max

max has a default value of 100.

The maximum value. Defaults to 100.

label

label has a default value of "".

An accessible label describing what the progress bar represents. Required for screen readers.

show-value

show-value has a default value of false.

Show the percentage value as text. In bar mode the text appears below the track; in circle mode it appears in the center of the ring.

size

size has a default value of "medium".

Size preset for the progress indicator.

In bar mode:

small — 6px
medium — 12px (default)
large — 20px

In circle mode:

small — 48px diameter
medium — 80px diameter (default)
large — 120px diameter

mode

mode has a default value of "bar".

Display mode for the progress indicator.

bar — linear progress bar (default)
circle — circular SVG ring

Methods

<esp-progress> has the following methods:

traverseToClosest

Traverse up the DOM tree to find the closest element that matches the selector. This method is aware of shadow DOM boundaries and will traverse through them to find the element.

CSS Properties

<esp-progress> has the following CSS properties:

--esp-progress-border-color

Border color of the track outline. Defaults to var(--esp-color-border).

--esp-progress-border-radius

Border radius of the track and fill. Defaults to var(--esp-size-border-radius).

--esp-progress-circle-size

Diameter of the circular progress ring in circle mode. Automatically set by the size attribute.

--esp-progress-fill-color

Color of the progress fill. Defaults to var(--esp-color-action-background).

--esp-progress-font-size

Font size for the value text. Defaults to var(--esp-type-small).

--esp-progress-height

Height of the progress bar track. Automatically set by the size attribute.

--esp-progress-text-color

Color of the percentage text in both bar and circle modes. Defaults to var(--esp-color-text).

--esp-field-background

Background color of the shared field shell. Defaults to var(--esp-color-layer-2).

--esp-field-border-color

Border color of the shared field shell. Defaults to var(--esp-color-border).

--esp-field-border-width

Border width of the shared field shell. Defaults to 1px.

--esp-field-text-color

Text color used inside the shared field shell. Defaults to var(--esp-color-text).

--esp-field-hover-bg

Hover background color of the shared field shell. Derived from --esp-field-background.

--esp-field-focus-bg

Focus background color of the shared field shell. Derived from --esp-field-background.

--esp-field-focus-shadow

Shadow color used for shared field focus treatment. Defaults to var(--esp-color-shadow).