For regular input take the ready-made fields — CdsTextInput, CdsSelect, CdsTextArea: they are already assembled from CdsInput and CdsField. CdsInput is needed when your control is not in the library.

Anatomy

CdsInput lays out on a grid the label (CdsLabel), the description (CdsDescription), the outer icons, your control and the block of messages (CdsMessages). The default slot gives out id, messagesId and the validation states — all of them are refs, so reach for id.value in the template.

Storybook

Variations

Label and description

The label prop names the field, description adds an explanation under the label. The slots of the same names accept arbitrary markup.

Sandbox Storybook

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

const value = ref('');
</script>

<template>
  <CdsInput
    v-slot="{ id }"
    label="ИНН организации"
    description="10 цифр для юрлица, 12 — для ИП"
    class="w-[350px] m-auto"
  >
    <CdsField v-slot="{ props: fieldProps, focus, blur }" :id="id.value">
      <input v-bind="fieldProps" v-model="value" placeholder="0000000000" @focus="focus" @blur="blur" />
    </CdsField>
  </CdsInput>
</template>

Messages and hints

There is a single line of text under the field, and the props split it by states: messages is visible at rest, hint while focused, and error-messages on top of the rest. CdsInput does not track the focus state itself: pass it with the focused prop.

Sandbox Storybook

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

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

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsInput v-slot="{ id }" label="Сообщение" messages="Видно всегда">
      <CdsField v-slot="{ props: fieldProps }" :id="id.value">
        <input v-bind="fieldProps" readonly />
      </CdsField>
    </CdsInput>

    <CdsInput v-slot="{ id }" label="Подсказка" hint="Видна, пока поле в фокусе" :focused="focused">
      <CdsField v-slot="{ props: fieldProps }" :id="id.value" :focused="focused">
        <input v-bind="fieldProps" @focus="focused = true" @blur="focused = false" />
      </CdsField>
    </CdsInput>

    <CdsInput v-slot="{ id }" label="Ошибка" :error-messages="['Заполните поле']">
      <CdsField v-slot="{ props: fieldProps }" :id="id.value" error>
        <input v-bind="fieldProps" readonly />
      </CdsField>
    </CdsInput>
  </div>
</template>

Hiding the details

The hide-details prop removes the bottom block entirely — the fields can be placed tight against each other. The auto value hides the block only while there is nothing to show.

Sandbox Storybook

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

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsInput v-slot="{ id }" label="Блок деталей на месте">
      <CdsField v-slot="{ props: fieldProps }" :id="id.value">
        <input v-bind="fieldProps" readonly />
      </CdsField>
    </CdsInput>

    <CdsInput v-slot="{ id }" label="Блок деталей скрыт" hide-details>
      <CdsField v-slot="{ props: fieldProps }" :id="id.value">
        <input v-bind="fieldProps" readonly />
      </CdsField>
    </CdsInput>

    <CdsInput v-slot="{ id }" label="Скрыт, пока нечего показать" hide-details="auto" messages="А теперь есть">
      <CdsField v-slot="{ props: fieldProps }" :id="id.value">
        <input v-bind="fieldProps" readonly />
      </CdsField>
    </CdsInput>
  </div>
</template>

Icons

The prepend-icon and append-icon props put an icon outside the control. Clicks on them are caught by @click:prepend and @click:append.

Sandbox Storybook

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

<template>
  <CdsInput v-slot="{ id }" label="Дата поставки" prepend-icon="calendar" append-icon="info" class="w-[350px] m-auto">
    <CdsField v-slot="{ props: fieldProps }" :id="id.value">
      <input v-bind="fieldProps" readonly />
    </CdsField>
  </CdsInput>
</template>

Direction

The direction prop changes the grid: horizontal puts the icons on the sides of the control, vertical puts them above and below it.

Sandbox Storybook

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

<template>
  <div class="flex flex-col gap-3 w-[350px] m-auto">
    <CdsInput v-slot="{ id }" label="Горизонтально" prepend-icon="file" append-icon="info">
      <CdsField v-slot="{ props: fieldProps }" :id="id.value">
        <input v-bind="fieldProps" readonly />
      </CdsField>
    </CdsInput>

    <CdsInput v-slot="{ id }" label="Вертикально" direction="vertical" prepend-icon="file" append-icon="info">
      <CdsField v-slot="{ props: fieldProps }" :id="id.value">
        <input v-bind="fieldProps" readonly />
      </CdsField>
    </CdsInput>
  </div>
</template>

Scenarios

Validating your own field

The rules prop accepts validation functions, validation-value accepts the value to pass to them. The result arrives in the slot through isValid: bind it to the error prop of CdsField and the frame turns red together with the message.

Sandbox Storybook

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

const inn = ref('770');
const focused = ref(false);

const rules = [
  (value: string) => !!value || 'Заполните ИНН',
  (value: string) => /^\d{10}$|^\d{12}$/.test(value) || 'ИНН состоит из 10 или 12 цифр'
];
</script>

<template>
  <CdsInput
    v-slot="{ id, isValid }"
    label="ИНН организации"
    description="10 цифр для юрлица, 12 — для ИП"
    :validation-value="inn"
    :rules="rules"
    :focused="focused"
    class="w-[350px] m-auto"
  >
    <CdsField
      v-slot="{ props: fieldProps }"
      :id="id.value"
      :error="isValid.value === false"
      :focused="focused"
      :dirty="!!inn"
      prepend-inner-icon="company"
      clearable
      @click:clear="inn = ''"
    >
      <input
        v-bind="fieldProps"
        v-model="inn"
        placeholder="0000000000"
        @focus="focused = true"
        @blur="focused = false"
      />
    </CdsField>
  </CdsInput>
</template>

API

Props

Name	Type	Default	Description
activeColor	string | undefined	—	Color of the component in its active state
appendIcon	IconValue | undefined	—	Icon in the append slot, after the content
baseColor	string | undefined	—	Color of the component in its inactive state
bgColor	string | undefined	—	Background color of the component
centerAffix	boolean | undefined	true	Vertically center the appendInner, prependInner, clearIcon and label elements.
color	string | undefined	—	Component color
description	string | undefined	—	Description of the component, shown under the label
direction	"horizontal" | "vertical" | undefined	'horizontal'	Switches the component between horizontal and vertical layout.
disabled	boolean | null | undefined	null	Disabled state
error	boolean | undefined	—	Puts the component into the 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
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
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
persistentHint	boolean | undefined	—	Always show the hint, not only on focus
prependIcon	IconValue | undefined	—	Icon in the prepend slot, before the content
readonly	boolean | null | undefined	null	Read-only state
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
textColor	string | undefined	—	Text color of the component
theme	string | undefined	—	Component theme
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
update:modelValue	[value: any]	Fires when the model of the component changes

Slots

Name	Type	Description
append	CdsInputSlot	Adds an element after the input
default	CdsInputSlot	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
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

Exposed

Name	Type	Description
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