Для обычного короткого текста или числа возьмите CdsTextInput: CdsOtpInput нужен там, где длина ввода известна заранее и каждый символ показывается отдельной ячейкой.

Анатомия

Ячейки (CdsOtpField) только рисуют код — введённый символ, заполнитель или мигающую каретку. Настоящий ввод принимает скрытый input: он прижат к нижнему краю компонента, поэтому подсказка автозаполнения из SMS появляется под ячейками и ничего не перекрывает. Между ячейками может стоять разделитель (CdsOtpSeparator), а в слитном виде ячейки собираются в группу (CdsOtpGroup).

Storybook

Вариации

Длина и тип кода

Свойство length задаёт число ячеек, type — что можно вводить: number (по умолчанию) принимает только цифры и открывает цифровую клавиатуру на мобильных, text — любые символы, password дополнительно скрывает введённое точками. Тот же эффект без смены типа даёт masked.

Sandbox Storybook

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

<template>
  <div class="flex flex-col items-center gap-4">
    <CdsOtpInput :length="4" model-value="1234" />
    <CdsOtpInput type="text" model-value="AB12CD" />
    <CdsOtpInput type="password" model-value="123456" />
  </div>
</template>

Допустимые символы

Свойство pattern сужает набор символов: имя готового набора (numeric, alpha, alphanumeric, unicode-alpha, unicode-alphanumeric) или своё регулярное выражение. Проверка идёт посимвольно — лишние символы не попадут в поле ни с клавиатуры, ни из буфера обмена.

Sandbox Storybook

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

<template>
  <div class="flex flex-col items-center gap-4">
    <CdsOtpInput type="text" pattern="alpha" :length="4" placeholder="A" />
    <CdsOtpInput type="text" pattern="alphanumeric" placeholder="X" />
    <CdsOtpInput type="text" :pattern="/[0-9A-F]/" placeholder="F" />
  </div>
</template>

Разделитель

Свойство divider ставит символ между ячейками — например, дефис в коде вида 123-456. Слот divider даёт полную свободу разметки и получает index — номер ячейки слева от разделителя, так что разделитель можно поставить только в нужном месте.

Sandbox Storybook

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

<template>
  <div class="flex flex-col items-center gap-4">
    <CdsOtpInput divider="-" model-value="123456" />

    <CdsOtpInput model-value="123456">
      <template #divider="{ index }">
        <CdsIcon v-if="index === 2" name="minus" size="sm" />
      </template>
    </CdsOtpInput>
  </div>
</template>

Слитный вид

Свойство merged убирает промежутки: ячейки становятся одним полем с общей рамкой. Такой вид компактнее и меньше дробит форму.

Sandbox Storybook

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

<template>
  <div class="flex justify-center">
    <CdsOtpInput merged model-value="1234" />
  </div>
</template>

Заполнитель

Свойство placeholder показывает символ в пустых ячейках — подсказку формата или просто точку, чтобы ряд не выглядел пустым.

Sandbox Storybook

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

<template>
  <div class="flex flex-col items-center gap-4">
    <CdsOtpInput placeholder="0" />
    <CdsOtpInput placeholder="•" />
  </div>
</template>

Размеры

Свойство size меняет высоту ячеек и размер шрифта. Размер по умолчанию — md.

Sandbox Storybook

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

const sizes = ['xs', 'sm', 'md', 'lg', 'xl'] as const;
</script>

<template>
  <div class="flex flex-col items-center gap-4">
    <CdsOtpInput v-for="size of sizes" :key="size" :size="size" :length="4" model-value="1234" />
  </div>
</template>

Состояния

disabled блокирует ввод, error подсвечивает весь ряд ошибкой, loading показывает индикатор поверх ячеек и не стирает набранный код. focus-all подсвечивает весь ряд, пока поле в фокусе, а не только активную ячейку.

Sandbox Storybook

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

<template>
  <div class="flex flex-col items-center gap-4">
    <CdsOtpInput :length="4" model-value="12" disabled />
    <CdsOtpInput :length="4" model-value="1234" error />
    <CdsOtpInput :length="4" model-value="1234" loading />
    <CdsOtpInput :length="4" model-value="12" focus-all />
  </div>
</template>

Слоты

Слот	Описание
fields	Ряд ячеек целиком — своя разметка из CdsOtpGroup, CdsOtpField и CdsOtpSeparator
divider	Разделитель между ячейками, index — номер ячейки слева от него
loader	Свой индикатор загрузки (при loading)
default	Произвольный контент поверх ячеек

Слот fields нужен, когда ячейки собираются в группы: каждая CdsOtpField получает свой index, а CdsOtpGroup объединяет соседние ячейки в общую рамку.

Sandbox Storybook

<script setup lang="ts">
import { CdsOtpField, CdsOtpGroup, CdsOtpInput, CdsOtpSeparator } from '@central-design-system/components';
</script>

<template>
  <div class="flex justify-center">
    <CdsOtpInput model-value="123456">
      <template #fields>
        <CdsOtpGroup merged>
          <CdsOtpField v-for="index of [0, 1, 2]" :key="index" :index="index" />
        </CdsOtpGroup>

        <CdsOtpSeparator>—</CdsOtpSeparator>

        <CdsOtpGroup merged>
          <CdsOtpField v-for="index of [3, 4, 5]" :key="index" :index="index" />
        </CdsOtpGroup>
      </template>
    </CdsOtpInput>
  </div>
</template>

Рекомендации

Storybook

Сценарии использования

Подтверждение по SMS

Событие finish срабатывает, как только код набран целиком, — отправляйте запрос по нему, отдельная кнопка не нужна. На время проверки включите loading: код остаётся на экране, а поле не выглядит сломанным. Если сервер не принял код, error подсвечивает ряд, а методы reset() и focus() через ref очищают поле и возвращают в него курсор.

Sandbox Storybook

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

const otpRef = ref<InstanceType<typeof CdsOtpInput>>();

const code = ref('');
const loading = ref(false);
const status = ref<'idle' | 'success' | 'error'>('idle');

// Имитация проверки кода на сервере: верный код — 123456
function onFinish(value: string) {
  loading.value = true;
  status.value = 'idle';

  setTimeout(() => {
    loading.value = false;
    status.value = value === '123456' ? 'success' : 'error';

    if (status.value === 'error') {
      otpRef.value?.reset();
      otpRef.value?.focus();
    }
  }, 1000);
}
</script>

<template>
  <div class="flex flex-col items-center gap-3">
    <p class="text-200 text-content-secondary">Код отправлен на +7 999 000-00-00</p>

    <CdsOtpInput
      ref="otpRef"
      v-model="code"
      :loading="loading"
      :error="status === 'error'"
      @finish="onFinish"
      @update:model-value="status = 'idle'"
    />

    <p v-if="status === 'success'" class="text-200 text-status-success-content">Код подтверждён</p>
    <p v-else-if="status === 'error'" class="text-200 text-status-danger-content">
      Код неверный — введите последние цифры из SMS ещё раз
    </p>
    <p v-else class="text-200 text-content-tertiary">Введите 123456, чтобы увидеть подтверждение</p>
  </div>
</template>

Повторная отправка кода

Кнопка «Отправить снова» открывается по таймеру — так пользователь не завалит запросами шлюз. Вместе с новым кодом сбрасывайте поле: reset() очищает ячейки, focus() ставит курсор в первую, и старый код не смешивается с новым.

Sandbox Storybook

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

const otpRef = ref<InstanceType<typeof CdsOtpInput>>();

const code = ref('');
const seconds = ref(15);

let timer: ReturnType<typeof setInterval> | undefined;

function countdown() {
  clearInterval(timer);

  timer = setInterval(() => {
    seconds.value -= 1;

    if (seconds.value <= 0) clearInterval(timer);
  }, 1000);
}

function resend() {
  seconds.value = 15;
  countdown();

  otpRef.value?.reset();
  otpRef.value?.focus();
}

countdown();
onScopeDispose(() => clearInterval(timer));
</script>

<template>
  <div class="flex flex-col items-center gap-3">
    <CdsOtpInput ref="otpRef" v-model="code" placeholder="•" />

    <CdsButton
      variant="soft"
      color="neutral"
      size="sm"
      :disabled="seconds > 0"
      :text="seconds > 0 ? `Отправить снова через ${seconds} с` : 'Отправить код снова'"
      @click="resend"
    />
  </div>
</template>

Код в форме

Когда код — часть формы входа, оставьте кнопку подтверждения: она даёт явный момент отправки. Кнопка ждёт, пока набраны все символы, — длину кода видно из v-model, а disabled на поле фиксирует уже подтверждённый код.

Sandbox Storybook

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

const code = ref('');
const loading = ref(false);
const confirmed = ref(false);

const isComplete = computed(() => code.value.length === 6);

function submit() {
  loading.value = true;

  setTimeout(() => {
    loading.value = false;
    confirmed.value = true;
  }, 1000);
}
</script>

<template>
  <CdsForm class="flex flex-col items-center gap-3 w-[350px] m-auto" @submit.prevent="submit">
    <p class="text-200 text-content-secondary">Введите код из приложения-аутентификатора</p>

    <CdsOtpInput v-model="code" :disabled="confirmed" divider="-" />

    <CdsButton type="submit" text="Подтвердить вход" :disabled="!isComplete || confirmed" :loading="loading" block />

    <p v-if="confirmed" class="text-200 text-status-success-content">Вход подтверждён</p>
  </CdsForm>
</template>

API

CdsOtpInput

Пропсы

Имя	Тип	По умолчанию	Описание
activeColor	string | undefined	—	Цвет компонента, когда он находится в активном состоянии
autofocus	boolean | undefined	—	Включает автофокус
baseColor	string | undefined	—	Цвет неактивного компонента
bgColor	string | undefined	—	Цвет фона компонента
color	string | undefined	—	Цвет компонента
disabled	boolean | null | undefined	null	Заблокированное состояние
divider	string | undefined	—	Символ-разделитель, который ставится между ячейками кода
error	boolean | undefined	—	Состояние ошибки
focusAll	boolean | undefined	—	Подсвечивать все ячейки, пока поле находится в фокусе, а не только активную
focused	boolean | undefined	—	Управляет состоянием фокуса компонента. Когда true, компонент считается сфокусированным и может применять соответствующие стили или поведение.
height	string | number | undefined	—	Высота компонента
label	string | undefined	'$cds.input.otp'	Доступное имя поля (aria-label). Принимает ключ локализации вида $cds.input.otp
length	string | number | undefined	6	Количество ячеек кода
loading	string | boolean | undefined	—	Индикатор загрузки для компонента
masked	boolean | undefined	—	Скрывать введённые символы точками
maxHeight	string | number | undefined	—	Максимальная высота компонента
maxWidth	string | number | undefined	—	Максимальная ширина компонента
merged	boolean | undefined	—	Слитный вид: ячейки объединяются в одно поле без промежутков между ними
minHeight	string | number | undefined	—	Минимальная высота компонента
minWidth	string | number | undefined	—	Минимальная ширина компонента
modelValue	string | number | undefined	—	Значение компонента v-model
pattern	RegExp | "numeric" | "alpha" | "alphanumeric" | "unicode-alpha" | "unicode-alphanumeric" | undefined	—	Допустимые символы: имя готового паттерна (numeric, alpha, alphanumeric, unicode-alpha, unicode-alphanumeric) или собственное регулярное выражение
placeholder	string | undefined	—	Символ-заполнитель, который показывается в пустой ячейке
size	number | "xs" | "sm" | "md" | "lg" | "xl" | undefined	'md'	Размер компонента
textColor	string | undefined	—	Цвет текста компонента
theme	string | undefined	—	Тема компонента
type	CdsOtpInputType | undefined	'number'	Тип вводимого кода. number ограничивает ввод цифрами, password скрывает символы
width	string | number | undefined	—	Ширина компонента

События

Имя	Тип	Описание
finish	[value: string]	Срабатывает, когда код набран полностью
update:focused	[focused: boolean]	Срабатывает при получении или потере фокуса
update:modelValue	[value: string]	Срабатывает при изменении значения компонента

Слоты

Имя	Тип	Описание
default	any	Произвольный контент поверх ячеек кода
divider	{ index: number; }	Разделитель между ячейками. index — номер ячейки слева от разделителя
fields	any	Полностью заменяет ряд ячеек собственной разметкой из CdsOtpGroup, CdsOtpField и CdsOtpSeparator
loader	any	Пользовательский индикатор загрузки

Exposed

Имя	Тип	Описание
blur	() => void	Снять фокус с поля
focus	() => void	Установить фокус на поле
inputRef	HTMLInputElement | undefined	Ref-ссылка на скрытый input, который принимает ввод кода
isFocused	boolean | undefined	Состояние фокуса поля
reset	() => void	Очистить введённый код

CdsOtpField

Пропсы

Имя	Тип	По умолчанию	Описание
index*	number	—	Порядковый номер ячейки, начиная с нуля

CdsOtpGroup

Пропсы

Имя	Тип	По умолчанию	Описание
merged	boolean | null | undefined	null	Слитный вид группы. По умолчанию наследуется от родительского CdsOtpInput

Слоты

Имя	Тип	Описание
default	any	Ячейки кода группы

CdsOtpSeparator

Слоты

Имя	Тип	Описание
default	any	Содержимое разделителя