Circular Progress

Circular progress indicators display progress along a circular track, for both determinate and indeterminate waits.

Usage

forge-circular-progress communicates that a single component or a small area of the page is loading or changing, through determinate, progress, theme, and track. Place it close to the content it describes, such as inside a button, a list item, or a card, rather than for the whole page. For a page-level or full-region block, use a busy indicator instead, and for a horizontal, linear alternative, use a linear progress indicator instead.

Rules

Only show a progress indicator when the expected wait is more than a second.

Place the indicator inside or directly beside the specific content that's loading or changing.

Pick one indicator style — linear or circular — for a given action, and use it consistently everywhere that action appears.

Don't

Don't show more than one spinner on a single page at once — use a busy indicator or a parent-level indicator instead.

Don't mix linear and circular indicators for the same kind of activity in different parts of the app.

Don't use a circular progress indicator for a full-page load — use a busy indicator instead.

Basic usage

An indeterminate spinner is the default — it animates continuously with no specific progress value.

An indeterminate circular progress indicator.

<forge-circular-progress aria-label="Circular Progress">
</forge-circular-progress>

Determinate

Set determinate and progress (a value from 0 to 1) when the actual completion percentage is known.

A determinate indicator showing a specific completion percentage.

<forge-circular-progress determinate progress="0.6" aria-label="60% complete">
</forge-circular-progress>

Theme and track

Set theme to match the indicator’s surrounding context, and track to keep its background ring visible.

A themed indicator with its track visible.

<forge-circular-progress theme="success" track aria-label="Loading">
</forge-circular-progress>

Circular progress indicators display progress by animating along a circular track in a clockwise direction. They can be used to represent both determinate and indeterminate progress.

import "@tylertech/forge/circular-progress";

Properties

Property	Attribute	Type	Default	Description
`determinate`	`determinate`	`boolean`	`false`	Controls the determinate state.
`progress`	`progress`	`number`	`0`	Controls the progress while in a determinate state. Accepts values from `0` to `1`.
`theme`	`theme`	`CircularProgressTheme`	`"primary"`	Controls the theme of the progress indicator.
`track`	`track`	`boolean`	`false`	Controls the visibility of the track background.

Slots

Name	Description
`(default)`	The is the default/unnamed slot. Renders content at the center of the progress indicator.

CSS Parts

Name	Description
`::part(progressbar)`	Styles the progress bar container element

CSS Custom Properties

Name	Description
`--forge-circular-progress-size`	The height and width of the indicator container.
`--forge-circular-progress-padding`	The padding inside the bounding box of the container.
`--forge-circular-progress-track-width`	The track indicator width.
`--forge-circular-progress-track-color`	The track background color.
`--forge-circular-progress-indicator-color`	The track indicator color.
`--forge-circular-progress-arc-duration`	The duration of the arc animation.
`--forge-circular-progress-theme-transition-duration`	The duration of the theme transition.
`--forge-circular-progress-theme-transition-timing`	The easing function to use for the theme transition.

Always set a meaningful aria-label on the progress indicator — without one, a screen reader has no way to tell the user what’s loading.

Usage

Rules

Basic usage

Determinate

Theme and track

Screen reader behavior