For progress shown as a horizontal bar take CdsProgressBar, and to dim a container while it loads — CdsOverlay.

Variations

Value

The model-value prop is the current progress in percent, from 0 to 100. A change of the value is animated with a smooth transition of the arc.

Sandbox Storybook

<script setup lang="ts">
import { CdsProgressCircle } from '@central-design-system/components';

const values = [15, 40, 75, 100];
</script>

<template>
  <div class="flex flex-wrap items-center justify-center gap-4">
    <CdsProgressCircle v-for="value in values" :key="value" :model-value="value" />
  </div>
</template>

The rotate prop turns the starting point of the arc by the given number of degrees. By default the progress grows clockwise from "12 o'clock".

Sandbox Storybook

<script setup lang="ts">
import { CdsProgressCircle } from '@central-design-system/components';

const rotations = [0, 90, 180, 270];
</script>

<template>
  <div class="flex flex-wrap items-center justify-center gap-4">
    <CdsProgressCircle v-for="rotate in rotations" :key="rotate" :model-value="25" :rotate="rotate" />
  </div>
</template>

Indeterminate progress

The indeterminate prop turns on an endless animation — use it when the course of the operation is unknown. The value disable-shrink leaves only the rotation without the pulsation of the arc: this animation is simpler and does not load the main thread. It is also enabled automatically for users with the prefers-reduced-motion setting.

Sandbox Storybook

<script setup lang="ts">
import { CdsProgressCircle } from '@central-design-system/components';
</script>

<template>
  <div class="flex flex-wrap items-center justify-center gap-4">
    <CdsProgressCircle indeterminate />
    <CdsProgressCircle indeterminate="disable-shrink" />
  </div>
</template>

Sizes

The size prop sets the diameter: from xs to xl or a number in pixels. The default size is md.

Sandbox Storybook

<script setup lang="ts">
import { CdsProgressCircle } from '@central-design-system/components';

const { sizes } = CdsProgressCircle.constants;
</script>

<template>
  <div class="flex flex-wrap items-center justify-center gap-4">
    <CdsProgressCircle v-for="size of sizes" :key="size" :size="size" :model-value="65" />
    <CdsProgressCircle :size="72" :model-value="65" />
  </div>
</template>

Stroke

The width prop sets the thickness of the stroke in pixels regardless of the diameter.

Sandbox Storybook

<script setup lang="ts">
import { CdsProgressCircle } from '@central-design-system/components';

const widths = [2, 4, 8];
</script>

<template>
  <div class="flex flex-wrap items-center justify-center gap-4">
    <CdsProgressCircle v-for="width in widths" :key="width" :model-value="65" :width="width" size="lg" />
  </div>
</template>

The rounded prop rounds the ends of the arc.

Sandbox Storybook

<script setup lang="ts">
import { CdsProgressCircle } from '@central-design-system/components';
</script>

<template>
  <div class="flex flex-wrap items-center justify-center gap-4">
    <CdsProgressCircle :model-value="65" :width="6" size="lg" />
    <CdsProgressCircle :model-value="65" :width="6" size="lg" rounded />
  </div>
</template>

Colors

The color prop paints the progress arc, bg-color paints the background ring underneath. Both accept color tokens of the design system.

Sandbox Storybook

<script setup lang="ts">
import { CdsProgressCircle } from '@central-design-system/components';
</script>

<template>
  <div class="flex flex-wrap items-center justify-center gap-4">
    <CdsProgressCircle :model-value="65" color="green" />
    <CdsProgressCircle :model-value="65" color="lemon" />
    <CdsProgressCircle :model-value="65" color="red" />
    <CdsProgressCircle :model-value="65" color="brand-primary" bg-color="red" />
  </div>
</template>

Content

The default slot renders content in the center of the ring and receives the current value through the value slot prop — a handy way to show the percentage next to the arc.

Sandbox Storybook

<script setup lang="ts">
import { CdsProgressCircle } from '@central-design-system/components';
</script>

<template>
  <div class="flex justify-center">
    <CdsProgressCircle :model-value="68" :size="64">
      <template #default="{ value }">{{ Math.round(value) }}%</template>
    </CdsProgressCircle>
  </div>
</template>

Reveal animation

The reveal prop animates the arc from zero to the current value when the component appears. The duration is configured with an object: :reveal="{ duration: 1500 }".

Sandbox Storybook

<script setup lang="ts">
import { CdsButton, CdsProgressCircle } from '@central-design-system/components';
import { ref } from 'vue';

const key = ref(0);
</script>

<template>
  <div class="flex flex-col items-center gap-3">
    <CdsProgressCircle :key="key" :model-value="75" :size="64" reveal />
    <CdsButton variant="soft" color="brand" size="sm" text="Повторить" @click="key++" />
  </div>
</template>

Guidelines

Storybook

Scenarios

File upload

The upload progress is visible in the center of the ring through the default slot, and once it is done the percentage turns into a success icon. The rounded prop softens the arc, and color supports the positive scenario.

Sandbox Storybook

<script setup lang="ts">
import { CdsButton, CdsIcon, CdsProgressCircle } from '@central-design-system/components';
import { ref } from 'vue';

const progress = ref(0);
const uploading = ref(false);

let timer: ReturnType<typeof setInterval> | undefined;

const upload = () => {
  clearInterval(timer);
  progress.value = 0;
  uploading.value = true;

  timer = setInterval(() => {
    progress.value = Math.min(progress.value + Math.random() * 18, 100);

    if (progress.value === 100) {
      clearInterval(timer);
      uploading.value = false;
    }
  }, 300);
};
</script>

<template>
  <div class="flex flex-col items-center gap-3">
    <CdsProgressCircle :model-value="progress" :size="72" :width="6" rounded color="green">
      <template #default="{ value }">
        <CdsIcon v-if="value === 100" icon="success-fill" color="green" />
        <span v-else>{{ Math.round(value) }}%</span>
      </template>
    </CdsProgressCircle>

    <CdsButton
      prepend-icon="upload"
      :text="progress === 100 ? 'Загрузить ещё раз' : 'Загрузить файл'"
      :disabled="uploading"
      @click="upload"
    />
  </div>
</template>

A filling quota

The ring shows not only a process but also a static value — the used storage space, for example. A computed color switches the indicator from green to yellow and red as the limit approaches.

Sandbox Storybook

<script setup lang="ts">
import { CdsButton, CdsProgressCircle } from '@central-design-system/components';
import { computed, ref } from 'vue';

const used = ref(52);

const color = computed(() => {
  if (used.value >= 90) return 'red';
  if (used.value >= 70) return 'lemon';
  return 'green';
});
</script>

<template>
  <div class="flex flex-col items-center gap-3">
    <CdsProgressCircle :model-value="used" :size="80" :width="8" :color="color">
      <template #default="{ value }">
        <span class="text-content-secondary">{{ Math.round(value) }} ГБ</span>
      </template>
    </CdsProgressCircle>

    <div class="flex gap-2">
      <CdsButton
        variant="soft"
        color="brand"
        size="sm"
        text="Добавить файлы"
        :disabled="used >= 100"
        @click="used = Math.min(used + 15, 100)"
      />
      <CdsButton
        variant="soft"
        color="neutral"
        size="sm"
        text="Очистить"
        :disabled="used <= 0"
        @click="used = Math.max(used - 30, 0)"
      />
    </div>
  </div>
</template>

A background operation

A compact indeterminate indicator of the xs size sits in a line with the text and reports that the operation that was started is still running. The caption next to it explains what to expect — without it a spinning ring says nothing.

Sandbox Storybook

<script setup lang="ts">
import { CdsButton, CdsIcon, CdsProgressCircle } from '@central-design-system/components';
import { ref } from 'vue';

const state = ref<'idle' | 'pending' | 'done'>('idle');

const generate = () => {
  state.value = 'pending';

  setTimeout(() => {
    state.value = 'done';
  }, 2500);
};
</script>

<template>
  <div class="flex flex-col items-center gap-3">
    <CdsButton text="Сформировать отчёт" :disabled="state === 'pending'" @click="generate" />

    <div v-if="state === 'pending'" class="flex items-center gap-2 text-content-secondary">
      <CdsProgressCircle indeterminate size="xs" :width="2" />
      <span>Готовим отчёт — обычно это занимает меньше минуты</span>
    </div>

    <div v-else-if="state === 'done'" class="flex items-center gap-2">
      <CdsIcon icon="success-fill" color="green" />
      <span>Отчёт готов</span>
    </div>
  </div>
</template>

API

Props

Name	Type	Default	Description
bgColor	string | undefined	—	Background color of the loader
color	string | undefined	—	Color of the loader
indeterminate	boolean | "disable-shrink" | undefined	—	Shows the animation continuously; use it when the course of the loading is unknown. The string disable-shrink switches to a simpler animation that does not run on the main thread
modelValue	string | number | undefined	0	Current loading progress in percent
reveal	boolean | { duration?: number | undefined; } | undefined	false	Animates the indicator from zero to the current value when the component appears. The { duration } object sets the animation duration in milliseconds
rotate	string | number | undefined	0	Turns the starting point of the circle by the given number of degrees
rounded	boolean | undefined	—	Rounds the ends of the progress arc
size	number | "xs" | "sm" | "md" | "lg" | "xl" | undefined	'md'	Size of the component
tag	string | JSXComponent<any> | undefined	'div'	Custom HTML tag or component to render
theme	string | undefined	—	Component theme
width	string | number | undefined	4	Sets the thickness of the circle stroke in pixels

Slots

Name	Type	Description
default	{ value: number; }	Default slot. Carries the progress value of the loading indicator.