Для многострочного текста используйте CdsTextArea, для выбора из готовых вариантов — CdsSelect.

Анатомия

Первая схема — каркас компонента: лейбл, описание, поле и нижний блок с сообщениями и счётчиком. Вторая — устройство самого поля: зоны prepend и append снаружи рамки, prepend-inner и append-inner внутри, кнопка очистки. Каждая зона доступна и как проп *-icon, и как одноимённый слот.

Storybook

Вариации

Лейбл и описание

Свойство label называет поле, description добавляет вспомогательный текст под лейблом. Одноимённые слоты принимают произвольную разметку.

Sandbox Storybook

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

<template>
  <CdsTextInput
    label="Заголовок"
    description="Описание для элемента формы или вспомогательный текст"
    placeholder="Введите текст"
    class="max-w-sm m-auto"
  />
</template>

Сообщения и подсказки

Под полем есть одна текстовая строка, и свойства делят её по состояниям: messages виден в покое, hint — при фокусе, error-messages — при ошибке и поверх остальных. Слоты messages и details переопределяют содержимое.

Sandbox Storybook

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

<template>
  <CdsTextInput
    label="Заголовок"
    placeholder="Введите текст"
    hint="Сообщение подсказка"
    messages="Пользовательское сообщение"
    class="max-w-sm m-auto"
  />
</template>

Скрытие деталей

Свойство hide-details убирает нижний блок целиком — поля можно ставить вплотную. Значение auto скрывает блок, только пока показывать нечего: как только появляется ошибка или подсказка, блок рендерится и сдвигает контент ниже.

Sandbox Storybook

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

<template>
  <CdsForm class="flex flex-col gap-2 w-[350px] m-auto">
    <template #default="{ reset }">
      <CdsTextInput
        label="Логин"
        placeholder="Очистите поле!"
        hide-details="auto"
        :rules="[(value: string) => !!value || 'Логин не может быть пустым']"
        clearable
      />
      <CdsTextInput
        label="Пароль"
        placeholder="Введите пароль"
        type="password"
        hide-details="auto"
        :rules="[(value: string) => !!value || 'Пароль не может быть пустым']"
      />

      <div class="flex gap-2 mt-2 justify-end">
        <CdsButton text="Сбросить" variant="soft" color="neutral" @click="reset" />
        <CdsButton type="submit" text="Отправить" />
      </div>
    </template>
  </CdsForm>
</template>

Иконки

Свойства prepend-icon и append-icon ставят иконку снаружи поля, prepend-inner-icon и append-inner-icon — внутри.

Sandbox Storybook

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

<template>
  <div class="max-w-sm m-auto">
    <CdsTextInput prepend-icon="user" placeholder="prepend-icon" />
    <CdsTextInput append-icon="add" placeholder="append-icon" />
    <CdsTextInput prepend-inner-icon="user" placeholder="prepend-inner-icon" />
    <CdsTextInput append-inner-icon="add" placeholder="append-inner-icon" />
    <CdsTextInput prepend-icon="user" append-icon="add" placeholder="prepend-icon & append-icon" />
    <CdsTextInput
      prepend-inner-icon="user"
      append-inner-icon="add"
      placeholder="prepend-inner-icon & append-inner-icon"
    />
  </div>
</template>

Префикс и суффикс

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

Sandbox Storybook

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

<template>
  <div class="max-w-sm m-auto">
    <CdsTextInput type="number" label="Число" prefix="$" value="100" />
    <CdsTextInput type="email" label="Электронная почта" suffix="@email.com" value="example" />
    <CdsTextInput type="tel" label="Телефон" prefix="+7" placeholder="(000) 000-00-00" />
    <CdsTextInput type="time" label="Время" model-value="10:45:00" prefix="UTC" />
  </div>
</template>

Очистка

Свойство clearable показывает иконку очистки при наведении или фокусе, persistent-clearable держит её видимой всегда.

Sandbox Storybook

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

const value = ref('Очисти меня!');
</script>

<template>
  <CdsTextInput
    v-model="value"
    placeholder="Введите значение"
    hint="Это поле можно очистить"
    clearable
    persistent-clearable
    class="max-w-sm m-auto"
  />
</template>

Состояния

disabled блокирует ввод и снижает контрастность, readonly запрещает изменение, но оставляет фокус и копирование, loading показывает индикатор загрузки — полосой или кругом (loading="circle").

Sandbox Storybook

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

<template>
  <div class="max-w-sm m-auto">
    <CdsTextInput label="Disabled" value="Значение" disabled />
    <CdsTextInput label="Readonly" value="Только для чтения" readonly />
    <CdsTextInput label="Loading" value="Загрузка" loading />
    <CdsTextInput label="Loading circle" value="Загрузка" loading="circle" />
  </div>
</template>

Валидация

Свойство rules принимает массив функций-валидаторов: каждая возвращает true либо строку с сообщением об ошибке. validate-on задаёт момент запуска — blur, input или submit (только по вызову validate()).

Sandbox Storybook

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

const title = ref('Удалите значение');
</script>

<template>
  <CdsTextInput
    v-model="title"
    :rules="[
      (value: string) => !!value || 'Не может быть пустым',
      (value: string) => value.length <= 10 || 'Допустимое значение 10 символов'
    ]"
    label="Заголовок"
    placeholder="Введите текст"
    required
    class="max-w-sm m-auto"
  />
</template>

Валидаторы — обычные функции: объявите их один раз и переиспользуйте между полями формы. Здесь заголовок проверяется на обязательность и длину (в паре с maxlength и счётчиком), почта — на формат.

Sandbox Storybook

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

const title = ref('Предварительный отчёт');
const email = ref('');

const rules = {
  required: (value: string) => !!value || 'Обязательное поле',
  counter: (value: string) => value.length <= 20 || 'Не больше 20 символов',
  email: (value: string) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value) || 'Некорректная почта'
};
</script>

<template>
  <CdsForm class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsTextInput
      v-model="title"
      label="Заголовок"
      :rules="[rules.required, rules.counter]"
      persistent-counter
      maxlength="20"
      counter="20"
    />

    <CdsTextInput
      v-model="email"
      label="Электронная почта"
      placeholder="name@company.ru"
      :rules="[rules.required, rules.email]"
    />
  </CdsForm>
</template>

Ошибки извне

Свойство error-messages показывает готовые сообщения — например, пришедшие с сервера — независимо от rules. error включает визуальное состояние ошибки без текста, max-errors ограничивает число сообщений.

Sandbox Storybook

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

<template>
  <div class="flex flex-col max-w-sm m-auto gap-2">
    <CdsTextInput
      label="Состояние ошибки"
      placeholder="errorMessages (string)"
      error-messages="Поле заполнено некорректно"
    />
    <CdsTextInput
      label="Состояние ошибки"
      placeholder="errorMessages (array)"
      :error-messages="['Ошибка 1', 'Ошибка 2']"
      :max-errors="2"
    />
    <CdsTextInput label="Состояние ошибки" placeholder="Без сообщения, но error: true" error />
  </div>
</template>

Счётчик

Свойство counter показывает счётчик символов: true — без лимита, число — с лимитом. counter-value принимает свою формулу подсчёта, persistent-counter оставляет счётчик видимым вне фокуса.

Sandbox Storybook

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

const wordCount = (value: unknown) => (value ?? '').toString().trim().split(/\s+/).filter(Boolean).length;
</script>

<template>
  <div class="max-w-sm m-auto">
    <CdsTextInput label="counter true" placeholder="Просто счётчик" counter />
    <CdsTextInput label="counter с лимитом" placeholder="До 20 символов" counter="20" maxlength="20" />
    <CdsTextInput label="persistentCounter" placeholder="Счётчик всегда виден" counter persistent-counter />
    <CdsTextInput label="counterValue (слова)" placeholder="Считаем слова" counter :counter-value="wordCount" />
  </div>
</template>

Цвета

Свойство color задаёт основной цвет, active-color — цвет при фокусе, icon-color — цвет иконок, bg-color — фон поля.

Sandbox Storybook

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

<template>
  <div class="max-w-sm m-auto">
    <CdsTextInput label="color" value="Цвет компонента" color="green" />
    <CdsTextInput label="activeColor" placeholder="Цвет при фокусе" active-color="purple" />
    <CdsTextInput label="iconColor" placeholder="Цвет иконки" prepend-inner-icon="user" icon-color="brand-primary" />
    <CdsTextInput label="bgColor" placeholder="Цвет фона" bg-color="status-success-fill" />
  </div>
</template>

Слоты

Когда пропсов недостаточно, содержимое любого блока заменяется слотом. prepend / append кладут элементы снаружи поля, prepend-inner / append-inner — внутрь; в отличие от пропсов *-icon, слоты принимают любые компоненты — кнопки, ссылки, бейджи.

Имя слота	Описание
label	Содержимое лейбла (замещает label)
description	Содержимое описания (замещает description)
prepend	Элемент до поля ввода
append	Элемент после поля ввода
prepend-inner	Элемент в начале поля, внутри рамки
append-inner	Элемент в конце поля, внутри рамки
clear	Своя иконка очистки (при clearable)
loader	Свой индикатор загрузки (при loading)
counter	Содержимое счётчика
details	Нижний блок целиком — сообщения и счётчик
messages	Содержимое блока сообщений

Sandbox Storybook

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

const showed = ref(false);
</script>

<template>
  <CdsTextInput loading placeholder="Введите текст" class="max-w-sm m-auto">
    <template #label>
      <span class="inline-flex items-center gap-1">
        <CdsIcon name="user" />
        <strong>Кастомный заголовок</strong>
      </span>
    </template>
    <template #description>
      <em>Описание через <span class="text-purple-500 font-bold">слот</span></em>
    </template>
    <template #messages>
      <span class="text-green-500">✓ Кастомное сообщение</span>
    </template>

    <template #prepend="props">
      <CdsButton variant="soft" color="neutral" icon="add" :size="props.size.value" />
    </template>
    <template #append="props">
      <CdsButton variant="solid" color="brand" text="OK" :size="props.size.value" />
    </template>

    <template #prepend-inner="props">
      <CdsIcon name="user" :size="props.size.value" />
    </template>
    <template #append-inner>
      <CdsFunctionalButton :icon="showed ? 'visibility-off' : 'visibility'" @click="showed = !showed" />
    </template>

    <template #loader>
      <CdsProgressBar color="purple" height="4" indeterminate />
    </template>
  </CdsTextInput>
</template>

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

Storybook

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

Поиск по списку

Поисковое поле собирается из иконки prepend-inner-icon="search" и clearable — пользователь одним кликом сбрасывает запрос и видит полный список. Лейбл здесь не нужен: роль поля очевидна из иконки и placeholder.

Sandbox Storybook

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

const query = ref('');

const items = ['Договор поставки', 'Договор аренды', 'Акт сверки', 'Счёт на оплату'];

const filtered = computed(() => items.filter((item) => item.toLowerCase().includes(query.value.trim().toLowerCase())));
</script>

<template>
  <div class="flex w-full max-w-md flex-col gap-3 m-auto">
    <CdsTextInput v-model="query" placeholder="Поиск по документам" prepend-inner-icon="search" clearable />

    <ul class="m-0 flex list-none flex-col gap-1 p-0">
      <li v-for="item in filtered" :key="item">{{ item }}</li>
      <li v-if="filtered.length === 0">Ничего не найдено</li>
    </ul>
  </div>
</template>

Пароль с просмотром

Слот append-inner принимает интерактивные элементы — например, кнопку, которая переключает type между password и text. Подсказка в hint сообщает требования к паролю до того, как пользователь ошибётся.

Sandbox Storybook

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

const password = ref('qwerty123');
const visible = ref(false);
</script>

<template>
  <CdsTextInput
    v-model="password"
    class="w-full max-w-md m-auto"
    label="Пароль"
    :type="visible ? 'text' : 'password'"
    hint="Минимум 8 символов"
  >
    <template #append-inner>
      <CdsFunctionalButton
        :icon="visible ? 'visibility-off' : 'visibility'"
        :aria-label="visible ? 'Скрыть пароль' : 'Показать пароль'"
        @click="visible = !visible"
      />
    </template>
  </CdsTextInput>
</template>

Ошибка с сервера

Ответ сервера кладётся в error-messages как есть — валидация через rules для этого не нужна. Сбрасывайте ошибку при изменении значения, чтобы поле не ругалось на уже исправленный ввод.

Sandbox Storybook

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

const email = ref('taken@company.ru');
const loading = ref(false);
const serverErrors = ref<string[]>([]);

const save = async () => {
  loading.value = true;
  serverErrors.value = [];

  // Имитация ответа сервера
  await new Promise((resolve) => setTimeout(resolve, 1000));

  loading.value = false;
  serverErrors.value = ['Эта почта уже занята — укажите другую'];
};
</script>

<template>
  <form class="flex w-full max-w-md flex-col gap-4 m-auto" @submit.prevent="save">
    <CdsTextInput
      v-model="email"
      label="Электронная почта"
      placeholder="name@company.ru"
      :error-messages="serverErrors"
      @update:model-value="serverErrors = []"
    />

    <CdsButton class="self-start" type="submit" text="Сохранить" :loading="loading" />
  </form>
</template>

События

Каждая иконная зона испускает своё событие клика: click:prepend, click:append, click:prepend-inner, click:append-inner и click:clear (последнее срабатывает уже после сброса значения). Здесь иконка слева перебирает варианты, замок внутри поля переключается, кнопка отправки очищает сообщение. Когда вместо иконки нужен сложный элемент — кнопка, бейдж — используйте одноимённые слоты, как в примере с паролем выше.

Sandbox Storybook

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

const message = ref('Привет!');
const locked = ref(false);
const iconIndex = ref(0);

const icons = ['message', 'star', 'flag', 'bookmark'];
const icon = computed(() => icons[iconIndex.value]);

const changeIcon = () => {
  iconIndex.value = (iconIndex.value + 1) % icons.length;
};

const toggleLock = () => {
  locked.value = !locked.value;
};

const resetIcon = () => {
  iconIndex.value = 0;
};

const sendMessage = () => {
  resetIcon();
  message.value = '';
};
</script>

<template>
  <CdsTextInput
    v-model="message"
    class="w-[350px] m-auto"
    label="Сообщение"
    :prepend-icon="icon"
    :append-inner-icon="locked ? 'lock' : 'unlock'"
    append-icon="telegram"
    clearable
    @click:prepend="changeIcon"
    @click:append-inner="toggleLock"
    @click:append="sendMessage"
    @click:clear="resetIcon"
  />
</template>

API

Пропсы

Имя	Тип	По умолчанию	Описание
active	boolean | undefined	—	Активное состояние поля
activeColor	string | undefined	—	Цвет компонента, когда он находится в активном состоянии
appendIcon	IconValue | undefined	—	Иконка в слоте append после контента
appendInnerIcon	IconValue | undefined	—	Иконка во внутреннем слоте append после содержимого поля
autocomplete	string | undefined	—	Помогает влиять на предложения браузера. Значение «suppress» изменяет атрибут name полей, а значение «off» полагается на то, что браузер по собственной инициативе перестанет предлагать значения. Любое другое значение передается встроенной функции автозаполнения для соответствующего элемента.
autofocus	boolean | undefined	—	Включает автофокус
baseColor	string | undefined	—	Цвет неактивного компонента
bgColor	string | undefined	—	Цвет фона компонента
centerAffix	boolean | undefined	—	Выровнять по вертикали элементы appendInner, prependInner, clearIcon и label по центру.
clearable	boolean | undefined	—	Отображать кнопку очистки значения
clearIcon	IconValue | undefined	'remove'	Иконка кнопки очистки
color	string | undefined	—	Цвет компонента
counter	string | number | boolean | undefined	—	Счетчик символов. Принимает булево значение, число или строку
counterValue	number | ((value: any) => number) | undefined	—	Пользовательское значение счетчика. Может быть числом или функцией вычисления от текущего значения
description	string | undefined	—	Описание компонента, отображаемое под меткой
dirty	boolean | undefined	—	Признак того, что значение поля было изменено пользователем
disabled	boolean | null | undefined	null	Заблокированное состояние
error	boolean | undefined	—	Состояние ошибки
errorMessages	string | readonly string[] | null | undefined	[]	Отображает компонент в состояние ошибки и передает пользовательские сообщения об ошибках. Будет объединяться с любыми проверками, заданными в свойстве rules. Это поле не запускает валидацию.
focused	boolean | undefined	—	Управляет состоянием фокуса компонента. Когда true, компонент считается сфокусированным и может применять соответствующие стили или поведение.
hideDetails	boolean | "auto" | undefined	—	Скрытие блока с деталями (сообщениями и подсказками). При значении 'auto' блок скрывается, если нет сообщений
hideMessages	boolean | undefined	—	Скрыть сообщения под полем ввода
hint	string | undefined	—	Текст подсказки, отображаемый под полем ввода
iconColor	string | boolean | undefined	—	Цвет иконки. Принимает булево значение или строку с цветом
id	string | undefined	—	Уникальный идентификатор компонента
label	string | undefined	—	Текст метки (label) компонента
loading	string | boolean | undefined	—	Индикатор загрузки для компонента
maxErrors	string | number | undefined	1	Максимальное число отображаемых ошибок при валидации
maxWidth	string | number | undefined	—	Максимальная ширина компонента
messages	string | readonly string[] | undefined	[]	Сообщения для отображения под полем ввода
minWidth	string | number | undefined	—	Минимальная ширина компонента
modelModifiers	Record<string, boolean> | undefined	—	Модификаторы v-model, переданные Vue для обработки значения поля
modelValue	any	—	Значение компонента в v-model. Если компонент поддерживает свойство multiple, по умолчанию используется пустой массив.
name	string | undefined	—	Имя поля ввода
persistentClearable	boolean | undefined	—	Всегда отображать кнопку очистки, а не только при наведении или фокусе
persistentCounter	boolean | undefined	—	Всегда отображать счетчик, а не только при взаимодействии с полем
persistentHint	boolean | undefined	—	Всегда отображать подсказку, а не только при фокусе
persistentPlaceholder	boolean | undefined	—	Всегда отображать placeholder, а не скрывать его при взаимодействии с полем
placeholder	string | undefined	—	Текст-заполнитель, отображаемый в пустом поле
prefix	string | undefined	—	Текстовый префикс, отображаемый перед значением поля
prependIcon	IconValue | undefined	—	Иконка в слоте prepend перед контентом
prependInnerIcon	IconValue | undefined	—	Иконка во внутреннем слоте prepend перед содержимым поля
readonly	boolean | null | undefined	null	Только для чтения
reverse	boolean | undefined	—	Обратный порядок расположения элементов внутри поля
role	string | undefined	—	ARIA-роль для нативного элемента ввода
rules	readonly ValidationRule[] | undefined	[]	Принимает массив, состоящий из элементов различных типов: функций, логических значений и строк. Функции принимают входное значение в качестве аргумента и должны возвращать либо true / false, либо строку, содержащую сообщение об ошибке. Поле ввода перейдет в состояние ошибки, если функция возвращает значение false (или любое значение в массиве содержит false) либо является строкой.
size	number | "xs" | "sm" | "md" | "lg" | "xl" | undefined	'md'	Размер компонента
suffix	string | undefined	—	Текстовый суффикс, отображаемый после значения поля
textColor	string | undefined	—	Цвет текста компонента
theme	string | undefined	—	Тема компонента
type	string | undefined	'text'	Тип нативного поля ввода
validateOn	ValidateOn | undefined	—	Изменяет тип события, при котором запускается валидация
validationValue	any	—	Значение, используемое при применении правил валидации
width	string | number | undefined	—	Ширина компонента

События

Имя	Тип	Описание
click:append	[e: MouseEvent]	Клик по внешней append-иконке (проп append-icon)
click:appendInner	[e: MouseEvent]	Клик по внутренней append-иконке (проп append-inner-icon)
click:clear	[e: MouseEvent]	Клик по иконке очистки (clearable); вызывается после сброса значения
click:control	[e: MouseEvent]	Событие, возникающее при клике в основной области контрола
click:prepend	[e: MouseEvent]	Клик по внешней prepend-иконке (проп prepend-icon)
click:prependInner	[e: MouseEvent]	Клик по внутренней prepend-иконке (проп prepend-inner-icon)
mousedown:control	[e: MouseEvent]	Событие, которое срабатывает при нажатии кнопки мыши в основной области контрола
update:focused	[focused: boolean]	Вызывается при переходе фокуса на элемент или при его потере
update:modelValue	[value: string]	Событие, которое срабатывает при изменении модели компонента

Слоты

Имя	Тип	Описание
append	CdsInputSlot	Добавляет элемент после поля ввода
append-inner	CdsInputDefaultSlot	Слот, добавляемый в конце инпута ввода
clear	CdsInputDefaultSlot & { props: Record<string, any>; }	Слот для пользовательского иконки очистки (отображается, когда свойство clearable имеет значение «true»).
counter	CdsCounterSlot	Слот для ввода пользовательского счетчика
default	{ id: Readonly<Ref<string, string>>; }	Слот по умолчанию
description	{ description: string | undefined; props: Record<string, any>; }	Слот по умолчанию для компонента CdsDescription
details	CdsInputSlot	Слот для ввода пользовательских данных, позволяющее настраивать отображение сообщений
label	{ label: string | undefined; props: Record<string, any>; }	Слот по умолчанию для компонента CdsLabel
loader	LoaderSlotProps	Слот для пользовательского загрузчика (отображается, если свойство loading имеет значение true).
message	CdsMessageSlot	Слот для настройки содержания сообщения
messages	CdsInputSlot	Слот для ввода пользовательских данных, позволяющее настраивать отображение сообщений
prepend	CdsInputSlot	Добавляет элемент до поля ввода
prepend-inner	CdsInputDefaultSlot	Слот, добавляемый в начало инпута ввода

Exposed

Имя	Тип	Описание
controlRef	HTMLElement | undefined	Ref-ссылка на контролл поля ввода
fieldIconColor	string | undefined	Цвет иконки
isDirty	boolean	Является ли поле ввода "грязным"
isDisabled	boolean	Является ли поле ввода заблокированным
isPure	boolean	Является ли поле ввода "чистым"
isReadonly	boolean	Является ли поле ввода только для чтения
isValid	boolean | null	Является ли поле ввода валидным
isValidating	boolean	Является ли поле ввода в процессе валидации
reset	() => Promise<void>	Функция сброса поля ввода в исходное состояние
resetValidation	() => Promise<void>	Функция сброса валидации поля ввода
validate	(silent?: boolean) => Promise<string[]>	Функция валидации поля ввода