CircularProgressBar

Components/Feedback

Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/circularprogressbar

Overview

Copy

A circular progress bar indicates the percentage of completion for a task or process with a visual indication that fills a circular track.

Do

  • Use to indicate progress of a task that require a long time to complete (10 seconds and more).
  • Use to show users that their action is being processed.

Don't

  • Don't use circular progress bar if processing user action takes less than 10 seconds. Use <Loader/> instead.

Feature examples

Size

Control progress bar size with size prop:

  • large is best for places where progress bar is the only element present.
  • medium is for common use cases.
  • small fits into smaller UI elements like cards and widgets.
  • tiny is used for dense layouts.
Copy

Skin

Control the appearance with skin prop. It supports 3 styles:

  • standard is for common cases.
  • success is best for highligthing the positive effect of the process.
  • premium is to prompt users to upgrade their plans to premium subscription.
Copy

Light

Invert the skin of a progress bar with the light prop. Use this skin on backgrounds with colors or images.

Copy

Progress indication

Add a label that indicates current progress in percentage with showProgressIndication prop.

Copy

Error status

Let users now if process failed using error property.

Add text that explains what went wrong or what action the user should take with the errorMessage prop. Message will be revealed on hover over.

Copy

Label

Add custom label for the progress bar using label prop.

Copy

Label placement

Control custom label position using labelPlacement prop:

  • bottom (default)
  • center
Copy

Common use case examples

Setup progress

Use circular progress bar to indicate users where they are in the feature or tool setup process.

Copy

Code

Copy

Props

NameTypeDefaultDescription
classNamestring—Specifies a CSS class name to be appended to the component's root element.
dataHookstring—Applies a data-hook HTML attribute that can be used in the tests.
errorboolean—Should be true if had failure during the progress.
errorLabelstring—Label to display when an error happens.
errorMessagestring—Message to display when an error happens.
labelstring—Use to display custom text in the progress bar.
labelPlacement"center" | "bottom"—Placement of the label in the progress bar.
lightboolean—Use light theme instead of dark theme.
showProgressIndicationboolean—Use to display a percentage progress.
size"small" | "tiny" | "medium" | "large"—Size of the bar.
skin"standard" | "premium" | "success"—Skin of the bar.
valuestring | number—The number of the percentage progress.

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
isSuccessIconDisplayedChecks whether the success icon is displayed
isErrorIconDisplayedChecks whether the error icon is displayed
isLabelDisplayedChecks whether the label text is displayed
getLabelTextContentGets the text content displayed
isPercentagesProgressDisplayedChecks whether the progress percentages are displayed
getValueGets the progress percentages value
isCompletedChecks whether the progress completed (value is 100)
hasErrorChecks whether an error occurred
getAttribute—
isSingleElementRendered—
isErrorIconShownChecks whether error icon is shown
isSuccessIconShownChecks whether success icon is shown
getSizeGets size.
getTooltipErrorMessageGets the tooltip error message
hasSkinChecks whether progress bar has a given skin
existsChecks whether the component found with the given data hook.
elementGets the component root element.
clickClicks on the component root element.
baseReturns UniDriver for the base element.

Changelog

  • 1.340.0 (2026-10-21) — maintenance release, no component-specific changes
  • 1.339.0 (2026-10-19) — maintenance release, no component-specific changes
  • 1.338.0 (2026-10-15) — maintenance release, no component-specific changes
  • 1.331.0 (2026-10-01) — maintenance release, no component-specific changes
  • 1.330.3 (2026-09-29) — maintenance release, no component-specific changes
  • 1.329.0 (2026-09-24) — maintenance release, no component-specific changes
  • 1.328.0 (2026-09-22) — maintenance release, no component-specific changes
  • 1.325.0 (2026-09-17) — fix: fix light-mode background arcs across themes and CSS minification failures in consuming applications. (#17082) — has visual changes
  • 1.324.0 (2026-09-14) — maintenance release, no component-specific changes
  • 1.323.0 (2026-09-10) — maintenance release, no component-specific changes
  • 1.320.1 (2026-09-04) — maintenance release, no component-specific changes
  • 1.318.0 (2026-08-28) — fix: styles migrated from Stylable to semantic classnames — rendering is unchanged, but the component's internal Stylable-generated classnames are replaced by wds-circular-progress-bar* ones. (#16910)
  • 1.317.0 (2026-08-26) — maintenance release, no component-specific changes
  • 1.310.0 (2026-08-10) — maintenance release, no component-specific changes
  • 1.292.0 (2026-06-22) — maintenance release, no component-specific changes
  • 1.291.0 (2026-06-19) — maintenance release, no component-specific changes
  • 1.278.0 (2026-05-08) — maintenance release, no component-specific changes
  • 1.271.0 (2026-04-22) — maintenance release, no component-specific changes
  • 1.266.0 (2026-04-07) — maintenance release, no component-specific changes
  • 1.260.0 (2026-03-17) — maintenance release, no component-specific changes
  • 1.247.2 (2026-01-21) — maintenance release, no component-specific changes
  • 1.243.0 (2025-12-23) — maintenance release, no component-specific changes
  • 1.242.0 (2025-12-19) — maintenance release, no component-specific changes
  • 1.219.0 (2025-09-12) — breaking: e3 tokenization (#15265)
  • 1.165.0 (2025-02-27) — maintenance release, no component-specific changes
  • 1.155.0 (2025-01-23) — maintenance release, no component-specific changes
  • 1.115.0 (2024-07-17) — maintenance release, no component-specific changes
  • 1.102.0 (2024-04-16) — maintenance release, no component-specific changes
  • 1.94.0 (2024-02-14) — feat: add tiny size variation (#13299)
  • 1.93.0 (2024-02-08) — maintenance release, no component-specific changes
  • 1.92.1 (2024-02-05) — maintenance release, no component-specific changes

Last updated: 22 October 2026

Did this help?