The stepper shows the progress of a business process without step navigation on its own: without the interactive prop the steps are not clickable, and the header without items works as a status tracker — see the "Request status" scenario. The CdsStages component, which used to solve the same task, is deprecated. For sections of equal weight that are switched in any order, use CdsTabs.

Anatomy

The stepper consists of a header with the steps, a content area and the navigation buttons — the last two appear when the steps are set through items. Every step is a state indicator with a progress line up to the next step, a title and a description.

Storybook

Variations

Steps from an array

Pass an array of objects into items — the title, the description and the value of a step are read by the item-title, item-text and item-value keys (by default title, text, and the value is the ordinal number of the step starting from one). The content of a step comes from the item.{value} slots or from the shared item slot, and the "Back" / "Next" buttons are rendered automatically: their texts are changed by the prev-text / next-text props, and hide-actions hides the buttons.

Sandbox Storybook

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

const step = ref(1);
const items = [
  { title: 'ФИО', text: 'Имя и фамилия' },
  { title: 'Паспортные данные', text: 'Номер паспорта и дата рождения' },
  { title: 'Способ оплаты', text: 'Данные банковской карты' },
  { title: 'Подтверждение', text: 'Код из смс' }
];
</script>

<template>
  <div class="m-auto max-w-[750px]">
    <CdsSteps v-model="step" :items="items">
      <template v-for="(item, index) in items" :key="item.title" #[`item.${index+1}`]>
        <CdsCard :title="item.title" :text="`Контент шага «${item.title}»: ${item.text.toLowerCase()}.`" borderless />
      </template>
    </CdsSteps>
  </div>
</template>

States

Steps can also be declared by hand — with CdsStepsItem components in the default slot: only the header is rendered, the content and the navigation stay up to you. A step has three states: error — finished with an error, warning — needs attention, disabled — unavailable.

Sandbox Storybook

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

const step = ref(1);
</script>

<template>
  <CdsSteps v-model="step">
    <CdsStepsItem title="ФИО" text="Имя и фамилия" />
    <CdsStepsItem title="Паспортные данные" error text="Номер паспорта и дата рождения" />
    <CdsStepsItem title="Способ оплаты" disabled text="Данные банковской карты" />
    <CdsStepsItem title="Подтверждение" warning text="Код из смс" />
  </CdsSteps>
</template>

Interactive steps

The interactive prop allows jumping to any step by click or from the keyboard — the progress animates in a cascade and disabled steps are skipped. The readonly prop turns the transitions off while keeping the appearance.

Sandbox Storybook

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

const step = ref(2);
</script>

<template>
  <CdsSteps v-model="step" interactive>
    <CdsStepsItem title="ФИО" text="Имя и фамилия" />
    <CdsStepsItem title="Паспортные данные" text="Номер паспорта и дата рождения" />
    <CdsStepsItem title="Способ оплаты" text="Данные банковской карты" />
    <CdsStepsItem title="Подтверждение" text="Код из смс" />
  </CdsSteps>
</template>

Vertical layout

The vertical prop turns the header into a column — a good fit for status trackers and narrow panels.

Sandbox Storybook

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

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

<template>
  <div class="flex h-[350px] w-full items-center justify-center">
    <CdsSteps v-model="step" vertical interactive>
      <CdsStepsItem title="ФИО" text="Имя и фамилия" />
      <CdsStepsItem title="Паспортные данные" text="Номер паспорта и дата рождения" />
      <CdsStepsItem title="Способ оплаты" text="Данные банковской карты" />
      <CdsStepsItem title="Подтверждение" text="Код из смс" />
    </CdsSteps>
  </div>
</template>

Slots

Slots give control over every area of the stepper:

Slot	Description
default	Your own CdsStepsItem when items is not set
title, text	Title and description of every step
header-item, header-item.{value}	Full replacement of the step content in the header
item, item.{value}	Step content in the content area
actions	Your own navigation buttons (receives the prev / next methods)
prev, next	Replacement of a single button inside the default navigation block

The title and text slots receive the state of the step (selected, complete, error, first, last…) — handy for adding tags and hints.

Sandbox Storybook

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

const step = ref(3);
const items = [
  { title: 'ФИО', text: 'Имя и фамилия' },
  { title: 'Паспортные данные', text: 'Номер паспорта и дата рождения', error: true },
  { title: 'Способ оплаты', text: 'Данные банковской карты', disabled: true },
  { title: 'Подтверждение', text: 'Код из смс' }
];
</script>

<template>
  <CdsSteps v-model="step">
    <CdsStepsItem v-for="item in items" :key="item.title" :disabled="item.disabled" :error="item.error">
      <template #title>
        <span class="inline-flex items-center gap-1">
          {{ item.title }}
          <CdsTag v-if="!item.disabled" text="Доступ" />
        </span>
      </template>
      <template #text="{ last }">
        <span class="inline-flex items-center gap-1">
          <CdsTooltip v-if="last">
            <template #activator="{ props }">
              <CdsIcon icon="info" v-bind="props" />
            </template>
            Push уведомления
          </CdsTooltip>
          {{ item.text }}
        </span>
      </template>
    </CdsStepsItem>
  </CdsSteps>
</template>

Model

The active step is controlled through v-model. For steps from items the default value is the ordinal number starting from one; for steps declared by hand it is the index starting from zero. Your own value is set by the item-value key or by the value prop of CdsStepsItem. The prev / next methods are available through the component ref.

Sandbox Storybook

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

const step = ref(2);
const items = [
  { title: 'ФИО', text: 'Имя и фамилия' },
  { title: 'Паспортные данные', text: 'Номер паспорта и дата рождения' },
  { title: 'Способ оплаты', text: 'Данные банковской карты' },
  { title: 'Подтверждение', text: 'Код из смс' }
];
const next = () => {
  if (step.value < items.length - 1) step.value++;
};
const prev = () => {
  if (step.value > 0) step.value--;
};
</script>

<template>
  <div>
    <div class="mb-4 flex w-full items-center justify-center gap-2">
      <CdsFunctionalButton icon="chevron-left" @click="prev" />
      v-model: {{ step }}
      <CdsFunctionalButton icon="chevron-right" @click="next" />
    </div>
    <CdsSteps v-model="step">
      <CdsStepsItem v-for="item in items" :key="item.title" :title="item.title" :text="item.text" />
    </CdsSteps>
  </div>
</template>

Guidelines

Storybook

Scenarios

Checkout wizard

A classic wizard: every step gets its own item.{value} slot with a form. The built-in buttons page through the steps, and the fields are bound to shared state through v-model, so the data survives the transitions.

Sandbox Storybook

<script setup lang="ts">
import { CdsForm, CdsRadio, CdsRadioGroup, CdsSteps, CdsTextInput } from '@central-design-system/components';
import { ref } from 'vue';

const step = ref(1);
const city = ref('');
const address = ref('');
const payment = ref('card');

const items = [
  { title: 'Доставка', text: 'Город и адрес' },
  { title: 'Оплата', text: 'Способ оплаты' },
  { title: 'Проверка', text: 'Данные заказа' }
];
</script>

<template>
  <div class="m-auto max-w-[750px]">
    <CdsSteps v-model="step" :items="items">
      <template #[`item.1`]>
        <CdsForm class="m-auto flex w-[350px] flex-col gap-2 py-2">
          <CdsTextInput v-model="city" label="Город" placeholder="Москва" />
          <CdsTextInput v-model="address" label="Адрес" placeholder="Улица, дом, офис" />
        </CdsForm>
      </template>

      <template #[`item.2`]>
        <CdsRadioGroup v-model="payment" label="Как оплатите заказ?" class="m-auto w-[350px] py-2" hide-details>
          <CdsRadio value="card" label="Банковской картой" />
          <CdsRadio value="invoice" label="Счётом на компанию" />
        </CdsRadioGroup>
      </template>

      <template #[`item.3`]>
        <div class="m-auto flex w-[350px] flex-col gap-1 py-2">
          <p>Доставка: {{ [city, address].filter(Boolean).join(', ') || 'не указана' }}</p>
          <p>Оплата: {{ payment === 'card' ? 'банковской картой' : 'счётом на компанию' }}</p>
        </div>
      </template>
    </CdsSteps>
  </div>
</template>

Confirmation before moving on

The actions slot replaces the built-in buttons and receives the prev and next methods — you define the conditions of the transition yourself. Here the "Next" button stays disabled until the user accepts the terms of service.

Sandbox Storybook

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

const step = ref(1);
const agreed = ref(false);

const items = [
  { title: 'Условия', text: 'Договор оферты' },
  { title: 'Данные', text: 'Реквизиты компании' },
  { title: 'Готово', text: 'Заявка отправлена' }
];
</script>

<template>
  <div class="m-auto max-w-[750px]">
    <CdsSteps v-model="step" :items="items">
      <template #[`item.1`]>
        <div class="m-auto flex w-[350px] flex-col gap-2 py-2">
          <p>Перед заполнением заявки ознакомьтесь с условиями обслуживания.</p>
          <CdsCheckbox v-model="agreed" label="Принимаю условия обслуживания" hide-details />
        </div>
      </template>

      <template #[`item.2`]>
        <p class="py-2 text-center">Здесь будет форма с реквизитами компании.</p>
      </template>

      <template #[`item.3`]>
        <p class="py-2 text-center">Заявка отправлена — подтверждение придёт на почту.</p>
      </template>

      <template #actions="{ prev, next }">
        <div class="flex items-center justify-between">
          <CdsButton variant="soft" color="brand" text="Назад" :disabled="step === 1" @click="prev" />
          <CdsButton text="Далее" :disabled="step === 3 || (step === 1 && !agreed)" @click="next" />
        </div>
      </template>
    </CdsSteps>
  </div>
</template>

Request status

A header without items works as a process tracker: only the steps, no content and no buttons. The completed stages are marked with indicators, and the descriptions carry the dates and the deadlines. The vertical prop lays the history out in a column.

Sandbox Storybook

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

<template>
  <div class="flex justify-center">
    <CdsSteps :model-value="2" vertical>
      <CdsStepsItem title="Заявка отправлена" text="12 марта, 10:24" />
      <CdsStepsItem title="Документы проверены" text="13 марта, 16:02" />
      <CdsStepsItem title="Согласование" text="Обычно занимает до двух дней" />
      <CdsStepsItem title="Заключение договора" />
    </CdsSteps>
  </div>
</template>

API

CdsSteps

Props

Name	Type	Default	Description
disabled	boolean | null | undefined	null	Disabled state
hideActions	boolean | undefined	—	Hides the step navigation buttons
interactive	boolean | undefined	—	Allows jumping to a step by click
itemProps	SelectItemKey	'props'	Object field that holds the props of the item, or a function that returns them
items	any[] | undefined	[]	Array of items to display
itemText	SelectItemKey	'text'	Key of the step description in an items element object
itemTitle	SelectItemKey	'title'	Object field used as the item title, or a function that returns it
itemValue	SelectItemKey	'value'	Object field used as the item value, or a function that returns it
mandatory	boolean | "force" | undefined	'force'	Requires at least one item to stay selected
max	number | undefined	—	Maximum number of items that can be selected
modelValue	any	—	Value of the selected items of the group
multiple	boolean | undefined	—	Allows selecting several items at once
nextText	string | undefined	'$cds.steps.next'	Text of the next step button
prevText	string | undefined	'$cds.steps.prev'	Text of the previous step button
readonly	boolean | null | undefined	null	Read-only state
required	boolean | "force" | undefined	'force'	Requires at least one item to stay selected
selectedClass	string | undefined	'cds-steps-item--current'	CSS class applied in the selected state
tag	string | JSXComponent<any> | undefined	'div'	Custom HTML tag or component to render
theme	string | undefined	—	Component theme
vertical	boolean | undefined	—	Vertical layout

Events

Name	Type	Description
update:modelValue	[value: unknown]	Fired when the v-model value changes

Slots

Name	Type	Description
actions	CdsStepsSlot	Custom navigation buttons
default	CdsStepsSlot	Header content: custom CdsStepsItem (used when items is not set)
header-item	CdsStepsItemSlot	Custom rendering of every step content in the header
item	CdsStepsInternalItem	Step content in the content area
next	CdsStepsActionsSlot	Custom next step button
prev	CdsStepsActionsSlot	Custom previous step button
text	CdsStepsItemSlot	Custom description of every step
title	CdsStepsItemSlot	Custom title of every step

Exposed

Name	Type	Description
next	() => void	Moves to the next step.
prev	() => void	Moves to the previous step.

CdsStepsActions

Props

Name	Type	Default	Description
disabled	boolean | "next" | "prev" | undefined	false	Disables the navigation buttons: both or a specific one
nextText	string | undefined	'$cds.steps.next'	Text of the next step button
prevText	string | undefined	'$cds.steps.prev'	Text of the previous step button

Events

Name	Type	Description
click:next	[]	Click on the next step button
click:prev	[]	Click on the previous step button

Slots

Name	Type	Description
next	CdsStepsActionsSlot	Custom next step button
prev	CdsStepsActionsSlot	Custom previous step button

CdsStepsItem

Props

Name	Type	Default	Description
disabled	boolean | null | undefined	null	Disabled state
error	boolean | undefined	—	The step finished with an error
interactive	boolean | undefined	—	Allows jumping to a step by click
readonly	boolean | null | undefined	null	Read-only state
selectedClass	string | undefined	—	CSS class applied in the selected state
text	string | undefined	—	Step description
title	string | undefined	—	Step title
value	any	—	Value of the component within the group
warning	boolean | undefined	—	The step needs attention

Events

Name	Type	Description
group:selected	[value: { value: boolean; }]	Fired when the selected state of the step inside the group changes

Slots

Name	Type	Description
default	CdsStepsItemSlot	Extra step content after the title and the description
text	CdsStepsItemSlot	Custom step description
title	CdsStepsItemSlot	Custom step title

CdsStepsView

Props

Name	Type	Default	Description
crossfade	boolean | undefined	—	Slides change with a smooth crossfade instead of a shift
direction	"horizontal" | "vertical" | undefined	'horizontal'	Switches the component between horizontal and vertical layout.
disabled	boolean | null | undefined	null	Disabled state
max	number | undefined	—	Maximum number of items that can be selected
modelValue	any	—	Value of the selected items of the group
multiple	boolean | undefined	—	Allows selecting several items at once
reverse	boolean | undefined	—	Inverts the direction of the transition animation between slides
selectedClass	string | undefined	—	CSS class applied in the selected state
tag	string | JSXComponent<any> | undefined	'div'	Custom HTML tag or component to render
theme	string | undefined	—	Component theme
transitionDuration	number | undefined	—	Duration of the transition animation between slides, in milliseconds
verticalArrows	boolean | "left" | "right" | undefined	—	Places the navigation arrows vertically: 'left' or 'right' — the side, true — the default side

Events

Name	Type	Description
update:modelValue	[value: any]	Fired when the v-model value changes

Slots

Name	Type	Description
additional	{ group: GroupProvide; }	Extra content above the slides — indicator dots or your own navigation, for example
default	{ group: GroupProvide; }	Slides. The slot props carry the group state for controlling the active slide
next	{ props: ControlProps; }	Button that moves to the next slide. The slot props are ready to bind to your own button
prev	{ props: ControlProps; }	Button that moves to the previous slide. The slot props are ready to bind to your own button

CdsStepsViewItem

Props

Name	Type	Default	Description
disabled	boolean | null | undefined	null	Disabled state
eager	boolean | undefined	—	Renders the content of the component right away. Useful when you have content that is not in the DOM but has to be indexed for SEO.
reverseTransition	string | boolean | undefined	—	Transition used when the slide appears in the reverse direction. A transition component name, or false to turn the animation off
selectedClass	string | undefined	—	CSS class applied in the selected state
transition	string | boolean | undefined	—	Transition used when the slide appears in the forward direction. A transition component name, or false to turn the animation off
value	any	—	Value of the component within the group

Slots

Name	Type	Description
default	any	Content of the slide