For progress shown as a ring take CdsProgressCircle, and to dim a container while it loads — CdsOverlay.

Anatomy

The bar is built from three layers: the indicator of the current value, the buffer and the background. The content of the default slot is drawn on top of the layers. By default the background and the buffer are tinted with the color of the indicator at a high transparency — the intensity is tuned by the bg-opacity and buffer-opacity props.

Storybook

Variations

Value

The model-value prop is the current progress. The bar counts from 0 to max (100 by default), so you can pass raw values — seconds or megabytes — without converting them into percent. A change of the value is animated with a smooth transition, and reverse fills the bar from right to left.

Sandbox Storybook

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

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

<template>
  <div class="m-auto flex w-[400px] flex-col gap-4">
    <CdsProgressBar v-for="value in values" :key="value" :model-value="value" />
  </div>
</template>

Indeterminate progress

The indeterminate prop turns on the running animation — use it when the course of the operation is unknown and there is no percentage to show.

Sandbox Storybook

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

<template>
  <div class="m-auto w-[400px]">
    <CdsProgressBar indeterminate color="brand-primary" />
  </div>
</template>

Buffer

The buffer-value prop is a second bar between the indicator and the background: the part that is already prepared but not passed yet — a preloaded fragment of a video, for example. To make the buffer readable against the bar, raise buffer-opacity; a separate color comes from buffer-color.

Sandbox Storybook

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

<template>
  <div class="m-auto w-[400px]">
    <CdsProgressBar :model-value="30" :buffer-value="65" buffer-opacity="0.3" color="brand-primary" />
  </div>
</template>

The stream prop adds a dashed animation from the edge of the buffer to the end of the bar — a signal that the data keeps coming. The edge of the stream is set by buffer-value, and the background is hidden.

Sandbox Storybook

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

<template>
  <div class="m-auto w-[400px]">
    <CdsProgressBar :model-value="25" :buffer-value="60" buffer-opacity="0.3" stream color="brand-primary" />
  </div>
</template>

Height

The height prop sets the height of the bar in pixels. The default is 4.

Sandbox Storybook

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

<template>
  <div class="m-auto flex w-[400px] flex-col gap-4">
    <CdsProgressBar :model-value="60" :height="2" />
    <CdsProgressBar :model-value="60" />
    <CdsProgressBar :model-value="60" :height="8" />
    <CdsProgressBar :model-value="60" :height="16" />
  </div>
</template>

Rounding

The rounded-bar prop rounds the leading edge of the indicator. The start stays straight — the bar reads as continuous from the zero mark.

Sandbox Storybook

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

<template>
  <div class="m-auto flex w-[400px] flex-col gap-4">
    <CdsProgressBar :model-value="60" :height="8" color="brand-primary" />
    <CdsProgressBar :model-value="60" :height="8" color="brand-primary" rounded-bar />
  </div>
</template>

Colors

The color prop paints the indicator and — as long as separate colors are not set — the buffer and the background too. Your own background color comes from bg-color, and the transparency of the layers from opacity for the indicator and bg-opacity for the background.

Sandbox Storybook

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

<template>
  <div class="m-auto flex w-[400px] flex-col gap-4">
    <CdsProgressBar :model-value="60" color="green" />
    <CdsProgressBar :model-value="60" color="lemon" />
    <CdsProgressBar :model-value="60" color="red" />
    <CdsProgressBar :model-value="60" color="brand-primary" bg-color="red" />
  </div>
</template>

Stripes

The striped prop lays running diagonal stripes over the indicator — they bring long operations with a known course to life.

Sandbox Storybook

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

<template>
  <div class="m-auto flex w-[400px] flex-col gap-4">
    <CdsProgressBar :model-value="45" striped color="brand-primary" :height="12" />
    <CdsProgressBar :model-value="70" striped color="green" :height="12" />
  </div>
</template>

Segments

The chunk-count prop splits the bar into equal segments — by the number of steps, for example — while chunk-width builds segments of a fixed width. The gap between them comes from chunk-gap. The indicator fills segments whole: the value snaps to the edge of the nearest segment.

Sandbox Storybook

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

<template>
  <div class="m-auto flex w-[400px] flex-col gap-4">
    <CdsProgressBar :model-value="60" :chunk-count="10" :height="8" color="brand-primary" />
    <CdsProgressBar :model-value="60" :chunk-width="12" :height="8" color="brand-primary" />
    <CdsProgressBar :model-value="60" :chunk-count="10" :chunk-gap="8" :height="8" color="brand-primary" />
  </div>
</template>

The variant="split" option does not cut the bar into pieces but separates the filled part from the rest with a single gap — the indicator and the background read as two independent segments.

Sandbox Storybook

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

<template>
  <div class="m-auto flex w-[400px] flex-col gap-4">
    <CdsProgressBar variant="split" :model-value="40" :height="8" color="brand-primary" />
    <CdsProgressBar
      variant="split"
      :model-value="40"
      :buffer-value="70"
      buffer-opacity="0.4"
      :height="8"
      color="brand-primary"
    />
  </div>
</template>

Content

The default slot renders content in the center of the bar and receives the value and buffer slot props — normalized percentages. Increase height so that the content fits.

Sandbox Storybook

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

<template>
  <div class="m-auto w-[400px]">
    <CdsProgressBar :model-value="64" :height="20" color="green">
      <template #default="{ value }">{{ Math.round(value) }}%</template>
    </CdsProgressBar>
  </div>
</template>

Guidelines

Storybook

Scenarios

File upload

The button starts the upload: the bar grows as the data arrives, and the caption above it shows the file and the percentage. The green color supports the positive scenario, and once it is done the button offers to upload again.

Sandbox Storybook

<script setup lang="ts">
import { CdsButton, CdsProgressBar } 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="m-auto flex w-[360px] flex-col items-center gap-3">
    <div class="flex w-full items-center justify-between">
      <span>report.xlsx</span>
      <span>{{ Math.round(progress) }}%</span>
    </div>

    <CdsProgressBar :model-value="progress" :height="8" color="green" />

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

Wizard steps

chunk-count set to the number of steps turns the bar into a wizard indicator: filled segments are the steps behind, semi-transparent ones are the steps ahead. The value is the share of the current step out of the total.

Sandbox Storybook

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

const steps = ['Данные компании', 'Контакты', 'Реквизиты', 'Подтверждение'];
const step = ref(1);

const progress = computed(() => (step.value / steps.length) * 100);
</script>

<template>
  <div class="m-auto flex w-[400px] flex-col gap-3">
    <span>Шаг {{ step }} из {{ steps.length }}: {{ steps[step - 1] }}</span>

    <CdsProgressBar :model-value="progress" :chunk-count="steps.length" :height="8" color="brand-primary" />

    <div class="flex justify-between">
      <CdsButton text="Назад" variant="soft" color="brand" :disabled="step === 1" @click="step--" />
      <CdsButton text="Далее" :disabled="step === steps.length" @click="step++" />
    </div>
  </div>
</template>

Seeking a video

The clickable prop turns the bar into a control: a click writes the new value into v-model. The buffer shows the preloaded fragment, stream shows that the loading continues, and the captions compute the time from the percentages.

Sandbox Storybook

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

const duration = 225;
const position = ref(35);
const buffered = ref(60);

const seek = (value: number) => {
  buffered.value = Math.min(100, value + 25);
};

const format = (percent: number) => {
  const seconds = Math.round((percent / 100) * duration);

  return `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, '0')}`;
};
</script>

<template>
  <div class="m-auto flex w-[400px] flex-col gap-2">
    <CdsProgressBar
      v-model="position"
      clickable
      :buffer-value="buffered"
      buffer-opacity="0.3"
      stream
      :height="8"
      color="brand-primary"
      @update:model-value="seek"
    />

    <div class="flex justify-between">
      <span>{{ format(position) }}</span>
      <span>{{ format(100) }}</span>
    </div>
  </div>
</template>

Refreshing the data in a card

The absolute prop pins the bar to the top edge of a container with position: relative — the indicator does not push the content around. The active prop hides the bar by smoothly collapsing its height to zero, and indeterminate spares you from measuring the progress of a background operation.

Sandbox Storybook

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

const loading = ref(false);

let timer: ReturnType<typeof setTimeout> | undefined;

const refresh = () => {
  clearTimeout(timer);
  loading.value = true;
  timer = setTimeout(() => (loading.value = false), 2500);
};
</script>

<template>
  <CdsCard class="relative m-auto w-[320px] overflow-hidden">
    <CdsProgressBar absolute indeterminate :active="loading" color="brand-primary" />

    <CdsCardItem>
      <CdsCardTitle>Курсы валют</CdsCardTitle>
    </CdsCardItem>
    <CdsCardText>Доллар — 79,8 ₽, евро — 86,2 ₽. Данные обновляются раз в час.</CdsCardText>

    <CdsCardActions class="justify-end p-4 pt-0">
      <CdsButton
        text="Обновить"
        variant="soft"
        color="brand"
        prepend-icon="refresh"
        :loading="loading"
        @click="refresh"
      />
    </CdsCardActions>
  </CdsCard>
</template>

API

Props

Name	Type	Default	Description
absolute	boolean | undefined	—	Absolute positioning of the component
active	boolean | undefined	true	Controls the active state of the progress bar
activeColor	string | undefined	—	Color of the component in its active state
baseColor	string | undefined	—	Color of the component in its inactive state
bgColor	string | undefined	—	Background color of the component
bgOpacity	string | number | undefined	—	Opacity of the progress bar background
bufferColor	string | undefined	—	Color of the buffer part of the progress bar
bufferOpacity	string | number | undefined	—	Opacity of the buffer part of the progress bar
bufferValue	string | number | undefined	0	Buffer value of the progress
chunkCount	string | number | undefined	null	Number of segments the progress bar is split into
chunkGap	string | number | undefined	4	Gap between the segments of the progress bar
chunkWidth	string | number | undefined	null	Width of a single segment of the progress bar
clickable	boolean | undefined	—	Makes the progress bar clickable
color	string | undefined	—	Component color
height	string | number | undefined	4	Height of the progress bar
indeterminate	boolean | undefined	—	Indeterminate progress state with no fixed value
location	Anchor | null | undefined	'top'	Position of the element relative to its container, for example "top left", "center", "bottom right".
max	string | number | undefined	100	Maximum progress value
modelValue	string | number | undefined	0	Current progress value
opacity	string | number | undefined	—	Opacity of the main progress indicator
reverse	boolean | undefined	—	Fills the progress bar in the opposite direction
roundedBar	boolean | undefined	—	Rounds the progress indicator
stream	boolean | undefined	—	Shows a streaming animation over the progress indicator
striped	boolean | undefined	—	Shows stripes on the progress indicator
tag	string | JSXComponent<any> | undefined	'div'	Custom HTML tag or component to render
textColor	string | undefined	—	Text color of the component
theme	string | undefined	—	Component theme
variant	"split" | undefined	—	Display variant of the progress bar segments

Events

Name	Type	Description
update:modelValue	[value: number]	Fires when the progress value changes — on a click on the bar in the clickable mode

Slots

Name	Type	Description
default	{ value: number; buffer: number; }	Content above the bar — a caption with the percentage, for example. The params carry the current value and the buffer value