For multiline text use CdsTextArea, to pick from a ready list of options use CdsSelect.

Anatomy

The first diagram shows the frame of the component: the label, the description, the field and the bottom block with messages and the counter. The second one shows how the field itself is built: the prepend and append zones outside the border, prepend-inner and append-inner inside it, and the clear button. Every zone is available both as a *-icon prop and as a slot of the same name.

Storybook

Variations

Label and description

The label prop names the field, description adds a supporting text under the label. The slots of the same name accept arbitrary markup.

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 and hints

There is a single text line under the field, and props split it by state: messages is visible at rest, hint — on focus, error-messages — on an error and on top of the rest. The messages and details slots override the content.

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>

Hiding the details

The hide-details prop removes the bottom block entirely — fields can then sit right next to each other. The auto value hides the block only while there is nothing to show: as soon as an error or a hint appears, the block is rendered and pushes the content below.

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>

Icons

The prepend-icon and append-icon props put an icon outside the field, prepend-inner-icon and append-inner-icon — inside it.

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 and suffix

The prefix and suffix props add an immutable text at the edges of the entered value — a currency, a country code, a domain.

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>

Clearing

The clearable prop shows the clear icon on hover or focus, persistent-clearable keeps it visible at all times.

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>

States

disabled blocks the input and lowers the contrast, readonly forbids changes but keeps focus and copying, loading shows a loading indicator — as a bar or as a circle (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>

Validation

The rules prop accepts an array of validator functions: each one returns either true or a string with an error message. validate-on sets the moment they run — blur, input or submit (only on a validate() call).

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>

Validators are plain functions: declare them once and reuse them across the fields of a form. Here the title is checked for being required and for its length (together with maxlength and the counter), and the email — for its format.

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>

Errors from outside

The error-messages prop shows ready messages — the ones coming from the server, for example — independently of rules. error turns on the visual error state without any text, max-errors limits the number of messages.

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

The counter prop shows a character counter: true — without a limit, a number — with a limit. counter-value accepts your own counting formula, persistent-counter keeps the counter visible outside of focus.

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>

Colors

The color prop sets the main color, active-color — the color on focus, icon-color — the color of the icons, bg-color — the background of the field.

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>

Slots

When props are not enough, the content of any block is replaced by a slot. prepend / append put elements outside the field, prepend-inner / append-inner — inside it; unlike the *-icon props, slots accept any components — buttons, links, badges.

Slot name	Description
label	Label content (replaces label)
description	Description content (replaces description)
prepend	Element before the input
append	Element after the input
prepend-inner	Element at the start of the field, inside the border
append-inner	Element at the end of the field, inside the border
clear	Your own clear icon (with clearable)
loader	Your own loading indicator (with loading)
counter	Counter content
details	The whole bottom block — messages and counter
messages	Content of the messages block

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>

Guidelines

Storybook

Scenarios

Searching through a list

A search field is made of the prepend-inner-icon="search" icon and clearable — the user resets the query in one click and sees the full list again. A label is not needed here: the role of the field is obvious from the icon and the 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>

Password with a preview

The append-inner slot accepts interactive elements — a button that toggles type between password and text, for example. The hint in hint states the password requirements before the user makes a mistake.

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>

An error from the server

The server response goes into error-messages as is — validation through rules is not needed for that. Reset the error when the value changes, so that the field does not complain about an input that is already fixed.

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>

Events

Every icon zone emits its own click event: click:prepend, click:append, click:prepend-inner, click:append-inner and click:clear (the last one fires after the value has already been reset). Here the icon on the left cycles through the options, the lock inside the field toggles, and the submit button clears the message. When you need a complex element instead of an icon — a button, a badge — use the slots of the same name, like in the password example above.

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

Props

Name	Type	Default	Description
active	boolean | undefined	—	Active state of the field
activeColor	string | undefined	—	Color of the component in its active state
appendIcon	IconValue | undefined	—	Icon in the append slot, after the content
appendInnerIcon	IconValue | undefined	—	Icon in the inner append slot, after the content of the field
autocomplete	string | undefined	—	Helps to influence browser suggestions. The suppress value changes the name attribute of the fields, and off relies on the browser to stop suggesting values on its own. Any other value is passed to the built-in autocomplete of the corresponding element.
autofocus	boolean | undefined	—	Enables autofocus
baseColor	string | undefined	—	Color of the component in its inactive state
bgColor	string | undefined	—	Background color of the component
centerAffix	boolean | undefined	—	Vertically center the appendInner, prependInner, clearIcon and label elements.
clearable	boolean | undefined	—	Shows the clear button
clearIcon	IconValue | undefined	'remove'	Icon of the clear button
color	string | undefined	—	Component color
counter	string | number | boolean | undefined	—	Character counter. Accepts a boolean, a number or a string
counterValue	number | ((value: any) => number) | undefined	—	Custom counter value. Either a number or a function computing it from the current value
description	string | undefined	—	Description of the component, shown under the label
dirty	boolean | undefined	—	Marks that the value of the field was changed by the user
disabled	boolean | null | undefined	null	Disabled state
error	boolean | undefined	—	Error state
errorMessages	string | readonly string[] | null | undefined	[]	Puts the component into the error state and passes custom error messages. They are merged with any checks defined in the rules prop. This field does not trigger validation.
focused	boolean | undefined	—	Controls the focus state of the component. When true, the component is considered focused and may apply the corresponding styles or behavior.
hideDetails	boolean | "auto" | undefined	—	Hides the details block (messages and hints). With the 'auto' value the block is hidden when there are no messages
hideMessages	boolean | undefined	—	Hide the messages under the input
hint	string | undefined	—	Hint text shown under the input
iconColor	string | boolean | undefined	—	Icon color. Accepts a boolean or a color string
id	string | undefined	—	Unique identifier of the component
label	string | undefined	—	Label text of the component
loading	string | boolean | undefined	—	Loading indicator for the component
maxErrors	string | number | undefined	1	Maximum number of validation errors shown
maxWidth	string | number | undefined	—	Maximum component width
messages	string | readonly string[] | undefined	[]	Messages shown under the input
minWidth	string | number | undefined	—	Minimum component width
modelModifiers	Record<string, boolean> | undefined	—	v-model modifiers passed by Vue to process the field value
modelValue	any	—	Value of the component in v-model. If the component supports the multiple prop, an empty array is used by default.
name	string | undefined	—	Name of the input
persistentClearable	boolean | undefined	—	Always show the clear button, not only on hover or focus
persistentCounter	boolean | undefined	—	Always show the counter, not only while the field is in use
persistentHint	boolean | undefined	—	Always show the hint, not only on focus
persistentPlaceholder	boolean | undefined	—	Always show the placeholder instead of hiding it while the field is in use
placeholder	string | undefined	—	Placeholder text shown in an empty field
prefix	string | undefined	—	Text prefix shown before the field value
prependIcon	IconValue | undefined	—	Icon in the prepend slot, before the content
prependInnerIcon	IconValue | undefined	—	Icon in the inner prepend slot, before the content of the field
readonly	boolean | null | undefined	null	Read-only state
reverse	boolean | undefined	—	Reverses the order of the elements inside the field
role	string | undefined	—	ARIA role for the native input element
rules	readonly ValidationRule[] | undefined	[]	Accepts an array of items of different types: functions, booleans and strings. Functions take the input value as an argument and must return either true / false, or a string with an error message. The input goes into the error state if a function returns false (or any value in the array is false) or is a string.
size	number | "xs" | "sm" | "md" | "lg" | "xl" | undefined	'md'	Size of the component
suffix	string | undefined	—	Text suffix shown after the field value
textColor	string | undefined	—	Text color of the component
theme	string | undefined	—	Component theme
type	string | undefined	'text'	Type of the native input
validateOn	ValidateOn | undefined	—	Changes the type of the event that triggers validation
validationValue	any	—	Value used when applying the validation rules
width	string | number | undefined	—	Component width

Events

Name	Type	Description
click:append	[e: MouseEvent]	Click on the outer append icon (append-icon prop)
click:appendInner	[e: MouseEvent]	Click on the inner append icon (append-inner-icon prop)
click:clear	[e: MouseEvent]	Click on the clear icon (clearable); fires after the value has been reset
click:control	[e: MouseEvent]	Fires on a click in the main area of the control
click:prepend	[e: MouseEvent]	Click on the outer prepend icon (prepend-icon prop)
click:prependInner	[e: MouseEvent]	Click on the inner prepend icon (prepend-inner-icon prop)
mousedown:control	[e: MouseEvent]	Fires on a mouse button press in the main area of the control
update:focused	[focused: boolean]	Fires when the element gains or loses focus
update:modelValue	[value: string]	Fires when the model of the component changes

Slots

Name	Type	Description
append	CdsInputSlot	Adds an element after the input
append-inner	CdsInputDefaultSlot	Slot added at the end of the input
clear	CdsInputDefaultSlot & { props: Record<string, any>; }	Slot for a custom clear icon (shown when the clearable prop is true).
counter	CdsCounterSlot	Slot for a custom counter
default	{ id: Readonly<Ref<string, string>>; }	Default slot
description	{ description: string | undefined; props: Record<string, any>; }	Default slot of the CdsDescription component
details	CdsInputSlot	Slot for custom content that lets you customize how the messages are displayed
label	{ label: string | undefined; props: Record<string, any>; }	Default slot of the CdsLabel component
loader	LoaderSlotProps	Slot for a custom loader (shown when the loading prop is true).
message	CdsMessageSlot	Slot for customizing the content of a message
messages	CdsInputSlot	Slot for custom content that lets you customize how the messages are displayed
prepend	CdsInputSlot	Adds an element before the input
prepend-inner	CdsInputDefaultSlot	Slot added at the start of the input

Exposed

Name	Type	Description
controlRef	HTMLElement | undefined	Ref to the control of the input
fieldIconColor	string | undefined	Icon color
isDirty	boolean	Whether the input is dirty
isDisabled	boolean	Whether the input is disabled
isPure	boolean	Whether the input is pure
isReadonly	boolean	Whether the input is read-only
isValid	boolean | null	Whether the input is valid
isValidating	boolean	Whether the input is being validated
reset	() => Promise<void>	Resets the input to its initial state
resetValidation	() => Promise<void>	Resets the validation of the input
validate	(silent?: boolean) => Promise<string[]>	Validates the input