> To build a Wix site agentically, or add Wix features like bookings or a store to a site you already have, follow https://www.wix.com/headless/skill.md
> 
> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: CircularProgressBar Component

## Article: CircularProgressBar Component

## Article Link: https://dev.wix.com/docs/wix-design-system/components/feedback/circular-progress-bar-component.md

## Article Content:

# CircularProgressBar

_Components/Feedback_

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

## Overview

```jsx
<Box align="center">
  <CircularProgressBar size="large" label="50% complete" value={50} />
</Box>;
```

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.

```jsx
<StorybookComponents.Stack>
  <CircularProgressBar size="large" label="Large" value={20} />
  <CircularProgressBar size="medium" label="Medium" value={20} />
  <CircularProgressBar size="small" label="Small" value={20} />
  <CircularProgressBar size="tiny" label="Tiny" value={20} />
</StorybookComponents.Stack>;
```

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

```jsx
<StorybookComponents.Background skin="light">
  <StorybookComponents.Stack padding="24px">
    <CircularProgressBar skin="standard" label="Standard" value="20" />
    <CircularProgressBar skin="success" label="Success" value="20" />
    <CircularProgressBar skin="premium" label="Premium" value="20" />
  </StorybookComponents.Stack>
</StorybookComponents.Background>;
```

#### Light

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

```jsx
<StorybookComponents.Stack flexDirection="column">
  <StorybookComponents.Background skin="light">
    <StorybookComponents.Stack padding="24px">
      <CircularProgressBar value={20} skin="standard" label="20%" />
      <CircularProgressBar value={20} skin="success" label="20%" />
      <CircularProgressBar value={20} skin="premium" label="20%" />
    </StorybookComponents.Stack>
  </StorybookComponents.Background>
  <StorybookComponents.Background skin="dark">
    <StorybookComponents.Stack padding="24px">
      <CircularProgressBar value={20} skin="standard" light label="20%" />
      <CircularProgressBar value={20} skin="success" light label="20%" />
      <CircularProgressBar value={20} skin="premium" light label="20%" />
    </StorybookComponents.Stack>
  </StorybookComponents.Background>
</StorybookComponents.Stack>;
```

#### Progress indication

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

```jsx
<StorybookComponents.Stack>
  <CircularProgressBar value={20} />
  <CircularProgressBar showProgressIndication value={20} />
</StorybookComponents.Stack>;
```

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

```jsx
<StorybookComponents.Stack flexDirection="column">
  <StorybookComponents.Background skin="light">
    <StorybookComponents.Stack padding="24px">
      <CircularProgressBar value="0" label="0%" />
      <CircularProgressBar value="20" label="20%" />
      <CircularProgressBar value="100" label="100%" />
      <CircularProgressBar
        value="20"
        label="Error"
        error
        errorMessage="This is the message that explains what went wrong."
      />
    </StorybookComponents.Stack>
  </StorybookComponents.Background>
  <StorybookComponents.Background skin="light">
    <StorybookComponents.Stack padding="24px">
      <CircularProgressBar value="0" skin="success" label="0%" />
      <CircularProgressBar value="20" skin="success" label="20%" />
      <CircularProgressBar value="100" skin="success" label="100%" />
      <CircularProgressBar
        value="20"
        skin="success"
        label="Error"
        error
        errorMessage="This is the message that explains what went wrong."
      />
    </StorybookComponents.Stack>
  </StorybookComponents.Background>
  <StorybookComponents.Background skin="light">
    <StorybookComponents.Stack padding="24px">
      <CircularProgressBar value="0" skin="premium" label="0%" />
      <CircularProgressBar value="20" skin="premium" label="20%" />
      <CircularProgressBar value="100" skin="premium" label="100%" />
      <CircularProgressBar
        value="20"
        skin="premium"
        label="Error"
        error
        errorMessage="This is the message that explains what went wrong."
      />
    </StorybookComponents.Stack>
  </StorybookComponents.Background>
</StorybookComponents.Stack>;
```

#### Label

Add custom label for the progress bar using `label` prop.

```jsx
<StorybookComponents.Stack>
  <CircularProgressBar value={20} />
  <CircularProgressBar label="1/5" value={20} />
</StorybookComponents.Stack>;
```

#### Label placement

Control custom label position using `labelPlacement` prop:

- `bottom` (default)
- `center`

```jsx
<StorybookComponents.Stack flexDirection="column">
  <StorybookComponents.Background skin="light">
    <StorybookComponents.Stack padding="24px">
      <CircularProgressBar value="20" label="1/5" />
      <CircularProgressBar value="20" skin="success" label="1/5" />
      <CircularProgressBar value="20" skin="premium" label="1/5" />
    </StorybookComponents.Stack>
  </StorybookComponents.Background>
  <StorybookComponents.Background skin="light">
    <StorybookComponents.Stack padding="24px">
      <CircularProgressBar value="20" label="1/5" labelPlacement="center" />
      <CircularProgressBar
        value="20"
        skin="success"
        label="1/5"
        labelPlacement="center"
      />
      <CircularProgressBar
        value="20"
        skin="premium"
        label="1/5"
        labelPlacement="center"
      />
    </StorybookComponents.Stack>
  </StorybookComponents.Background>
</StorybookComponents.Stack>;
```

### Common use case examples

#### Setup progress

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

```jsx
<Layout>
  <Cell span={5}>
    <Card>
      <Card.Header title="SEO assistant" />
      <Card.Divider />
      <Card.Content>
        <Box direction="vertical" gap="SP2" paddingBottom="SP4">
          <CircularProgressBar
            size="medium"
            value="20"
            label="1/5"
            labelPlacement="center"
          />
          <Text weight="normal">SEO setup checklist</Text>
          <Text size="small" secondary>
            Fix current issues and follow recommendations to improve this site’s
            performance in search results.
          </Text>
        </Box>
        <Button priority="secondary" size="small">
          Continue Setup
        </Button>
      </Card.Content>
    </Card>
  </Cell>
</Layout>;
```

## Code

```jsx
import { CircularProgressBar } from '@wix/design-system';
```

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | — | Specifies a CSS class name to be appended to the component's root element. |
| `dataHook` | `string` | — | Applies a data-hook HTML attribute that can be used in the tests. |
| `error` | `boolean` | — | Should be true if had failure during the progress. |
| `errorLabel` | `string` | — | Label to display when an error happens. |
| `errorMessage` | `string` | — | Message to display when an error happens. |
| `label` | `string` | — | Use to display custom text in the progress bar. |
| `labelPlacement` | `"center" \| "bottom"` | — | Placement of the label in the progress bar. |
| `light` | `boolean` | — | Use light theme instead of dark theme. |
| `showProgressIndication` | `boolean` | — | Use to display a percentage progress. |
| `size` | `"small" \| "tiny" \| "medium" \| "large"` | — | Size of the bar. |
| `skin` | `"standard" \| "premium" \| "success"` | — | Skin of the bar. |
| `value` | `string \| number` | — | The number of the percentage progress. |

## Testkit

Import the driver matching your test environment:

```jsx
// UniDriver
import { CircularProgressBarUniDriver } from '@wix/design-system/dist/testkit/unidriver';

// Vanilla
import { CircularProgressBarTestkit } from '@wix/design-system/dist/testkit';

// Puppeteer
import { CircularProgressBarTestkit } from '@wix/design-system/dist/testkit/puppeteer';

// Testing Library
import { CircularProgressBarTestkit } from '@wix/design-system/dist/testkit/testing-library';
```

### Driver methods

| Method | Description |
| --- | --- |
| `isSuccessIconDisplayed` | Checks whether the success icon is displayed |
| `isErrorIconDisplayed` | Checks whether the error icon is displayed |
| `isLabelDisplayed` | Checks whether the label text is displayed |
| `getLabelTextContent` | Gets the text content displayed |
| `isPercentagesProgressDisplayed` | Checks whether the progress percentages are displayed |
| `getValue` | Gets the progress percentages value |
| `isCompleted` | Checks whether the progress completed (value is 100) |
| `hasError` | Checks whether an error occurred |
| `getAttribute` | — |
| `isSingleElementRendered` | — |
| `isErrorIconShown` | Checks whether error icon is shown |
| `isSuccessIconShown` | Checks whether success icon is shown |
| `getSize` | Gets size. |
| `getTooltipErrorMessage` | Gets the tooltip error message |
| `hasSkin` | Checks whether progress bar has a given skin |
| `exists` | Checks whether the component found with the given data hook. |
| `element` | Gets the component root element. |
| `click` | Clicks on the component root element. |
| `base` | Returns 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](invalid-url)) — 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](invalid-url))
- **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](invalid-url))
- **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](invalid-url))
- **1.93.0** (2024-02-08) — maintenance release, no component-specific changes
- **1.92.1** (2024-02-05) — maintenance release, no component-specific changes