Форма не рендерит поля сама — собирайте их из CdsTextInput, CdsSelect, CdsCheckbox и других контролов. Правила валидации объявляются на самих полях пропом rules.

Анатомия

Форма — нативный form с необязательной шапкой: заголовок и описание рендерятся над контентом, поля из default-слота остаются как есть. Заголовок связывается с формой через aria-labelledby, описание — через aria-describedby.

Storybook

Вариации

Заголовок и описание

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

Sandbox Storybook

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

<template>
  <CdsForm
    label="Адрес доставки"
    description="Привезём заказ по этому адресу"
    class="flex flex-col gap-2 w-[350px] m-auto"
  >
    <CdsTextInput label="Город" placeholder="Москва" />
    <CdsTextInput label="Улица и дом" placeholder="Тверская, 1" />
  </CdsForm>
</template>

Статус валидности

v-model формы — общий статус её полей: null, пока форма не проверялась, false при ошибках и true, когда все поля валидны. Статус обновляется на лету — например, им удобно блокировать кнопку отправки.

Sandbox Storybook

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

const valid = ref<boolean | null>(null);
const login = ref('');
const password = ref('');

const rules = {
  login: [(value: string) => !!value || 'Введите логин'],
  password: [(value: string) => value.length >= 8 || 'Минимум 8 символов']
};
</script>

<template>
  <CdsForm v-model="valid" class="flex flex-col gap-2 w-[350px] m-auto" @submit.prevent>
    <CdsTextInput v-model="login" :rules="rules.login" label="Логин" placeholder="Введите логин" />
    <CdsTextInput
      v-model="password"
      :rules="rules.password"
      type="password"
      label="Пароль"
      placeholder="Минимум 8 символов"
    />
    <div class="mt-2">
      <CdsButton :disabled="!valid" type="submit" block>Войти</CdsButton>
    </div>
  </CdsForm>
</template>

Момент валидации

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

Sandbox Storybook

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

const mode = ref<'input' | 'blur' | 'submit'>('input');
const formRef = ref<InstanceType<typeof CdsForm>>();

const name = ref('');
const email = ref('');

const rules = {
  name: [(value: string) => !!value || 'Обязательное поле'],
  email: [(value: string) => /.+@.+\..+/.test(value) || 'Некорректная почта']
};

watch(mode, () => unref(formRef)?.resetValidation());
</script>

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <div class="flex items-center justify-between">
      <span class="text-sm text-content-secondary">validate-on</span>
      <CdsButtonToggle v-model="mode" mandatory variant="soft" color="neutral" size="sm">
        <CdsButton text="input" value="input" />
        <CdsButton text="blur" value="blur" />
        <CdsButton text="submit" value="submit" />
      </CdsButtonToggle>
    </div>

    <CdsForm ref="formRef" :validate-on="mode" class="flex flex-col gap-2" @submit.prevent>
      <CdsTextInput v-model="name" :rules="rules.name" label="Имя" placeholder="Введите имя" />
      <CdsTextInput v-model="email" :rules="rules.email" label="Электронная почта" placeholder="name@company.ru" />
      <div class="mt-2">
        <CdsButton type="submit">Отправить</CdsButton>
      </div>
    </CdsForm>
  </div>
</template>

Быстрая валидация

Свойство first-fail останавливает проверку на первом невалидном поле. Отправьте форму: ошибку покажет только «Имя», хотя «Фамилия» тоже невалидна.

Sandbox Storybook

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

const firstName = ref('');
const lastName = ref('1020');

const rules = {
  firstName: [(value: string) => value.length >= 3 || 'Имя не короче 3 символов'],
  lastName: [(value: string) => !/\d/.test(value) || 'Фамилия не может содержать цифры']
};
</script>

<template>
  <CdsForm first-fail class="flex flex-col gap-2 w-[350px] m-auto" @submit.prevent>
    <CdsTextInput v-model="firstName" :rules="rules.firstName" label="Имя" placeholder="Введите имя" />
    <CdsTextInput v-model="lastName" :rules="rules.lastName" label="Фамилия" placeholder="Введите фамилию" />
    <div class="mt-2">
      <CdsButton type="submit">Отправить</CdsButton>
    </div>
  </CdsForm>
</template>

Состояния

disabled блокирует все поля формы разом, readonly оставляет значения видимыми и копируемыми, но запрещает их менять. Отдельные поля настраивать не нужно — состояние наследуется.

Sandbox Storybook

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

<template>
  <div class="flex flex-col gap-4 w-[350px] m-auto">
    <CdsForm disabled label="Недоступная форма" class="flex flex-col gap-2">
      <CdsTextInput label="Имя" value="Анна Смирнова" />
      <CdsTextInput label="Электронная почта" value="anna@company.ru" />
    </CdsForm>
    <CdsForm readonly label="Только для чтения" class="flex flex-col gap-2">
      <CdsTextInput label="Имя" value="Анна Смирнова" />
      <CdsTextInput label="Электронная почта" value="anna@company.ru" />
    </CdsForm>
  </div>
</template>

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

Нижним блоком с сообщениями управляет проп hide-details на самих полях: true скрывает блок всегда — вместе с ошибками, false всегда резервирует под него место, auto показывает блок, только когда есть что показать. В плотных формах используйте auto: поля стоят вплотную, но ошибки валидации не теряются. Переключите значение и отправьте пустую форму.

Sandbox Storybook

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

const mode = ref('auto');
const hideDetails = computed(() => (mode.value === 'auto' ? ('auto' as const) : mode.value === 'true'));

const rules = {
  login: [(value: string) => !!value || 'Логин не может быть пустым'],
  password: [(value: string) => !!value || 'Пароль не может быть пустым']
};
</script>

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <div class="flex items-center justify-between">
      <span class="text-sm text-content-secondary">hide-details</span>
      <CdsButtonToggle v-model="mode" mandatory variant="soft" color="neutral" size="sm">
        <CdsButton text="auto" value="auto" />
        <CdsButton text="true" value="true" />
        <CdsButton text="false" value="false" />
      </CdsButtonToggle>
    </div>

    <CdsForm class="flex flex-col gap-2" @submit.prevent>
      <template #default="{ reset }">
        <CdsTextInput
          :hide-details="hideDetails"
          :rules="rules.login"
          label="Логин"
          placeholder="Введите логин"
          clearable
        />
        <CdsTextInput
          :hide-details="hideDetails"
          :rules="rules.password"
          type="password"
          label="Пароль"
          placeholder="Введите пароль"
        />
        <div class="flex gap-2 mt-2 justify-end">
          <CdsButton variant="soft" color="neutral" @click="reset">Сбросить</CdsButton>
          <CdsButton type="submit">Отправить</CdsButton>
        </div>
      </template>
    </CdsForm>
  </div>
</template>

Слоты

Default-слот получает состояние формы и методы управления — кнопки «Проверить» и «Сбросить» собираются без ref на компонент.

Имя слота	Описание
label	Содержимое заголовка (замещает label)
description	Содержимое описания (замещает description)
default	Контент формы; слот-пропсы: isValid, errors, isValidating, validate, reset, resetValidation

Sandbox Storybook

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

const valid = ref<boolean | null>(null);
const value = ref('');

const rules = [(input: string) => !!input || 'Не может быть пустым'];
</script>

<template>
  <CdsForm v-model="valid" class="flex flex-col gap-2 w-[350px] m-auto" @submit.prevent>
    <template #default="{ isValid, validate, reset, resetValidation }">
      <CdsTextInput v-model="value" :rules="rules" label="Поле" placeholder="Введите текст" />
      <div class="text-sm text-content-secondary">
        Статус формы: {{ isValid === null ? 'не проверена' : isValid ? 'валидна' : 'есть ошибки' }}
      </div>
      <div class="flex flex-wrap gap-2 mt-2">
        <CdsButton @click="validate">Проверить</CdsButton>
        <CdsButton variant="soft" color="brand" @click="reset">Сброс</CdsButton>
        <CdsButton variant="soft" color="neutral" @click="resetValidation">Сброс валидации</CdsButton>
      </div>
    </template>
  </CdsForm>
</template>

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

Storybook

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

Отправка формы

Событие submit — это Promise: await event возвращает результат валидации, и обработчик сам решает, отправлять ли данные. Модификатор .prevent отключает нативную отправку страницы. Запрос здесь имитируется setTimeout, кнопка на время «запроса» показывает loading.

Sandbox Storybook

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

const name = ref('');
const email = ref('');
const loading = ref(false);
const sent = ref(false);

const rules = {
  name: [(value: string) => !!value || 'Введите имя'],
  email: [(value: string) => /.+@.+\..+/.test(value) || 'Некорректная почта']
};

async function onSubmit(event: SubmitEventPromise) {
  sent.value = false;

  const { valid } = await event;

  if (!valid) return;

  loading.value = true;

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

<template>
  <CdsForm class="flex flex-col gap-2 w-[350px] m-auto" @submit.prevent="onSubmit">
    <CdsTextInput v-model="name" :rules="rules.name" label="Имя" placeholder="Введите имя" />
    <CdsTextInput v-model="email" :rules="rules.email" label="Электронная почта" placeholder="name@company.ru" />
    <div class="mt-2">
      <CdsButton :loading="loading" type="submit">Отправить заявку</CdsButton>
    </div>
    <div v-if="sent" class="text-sm text-content-secondary">Заявка отправлена — мы напишем вам на почту.</div>
  </CdsForm>
</template>

Управление извне

Методы validate, reset и resetValidation доступны и через ref на форму. Так управляют формой снаружи — из футера модального окна или панели мастера, где кнопки живут вне разметки формы.

Sandbox Storybook

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

const formRef = ref<InstanceType<typeof CdsForm>>();

const name = ref('');
const agree = ref(false);
const result = ref('');

const rules = {
  name: [(value: string) => !!value || 'Введите имя'],
  agree: [(value: boolean) => !!value || 'Нужно согласие, чтобы продолжить']
};

async function validate() {
  const form = unref(formRef);

  if (!form) return;

  const { valid } = await form.validate();

  result.value = valid ? 'Форма валидна' : 'В форме есть ошибки';
}

function reset() {
  unref(formRef)?.reset();
  result.value = '';
}

function resetValidation() {
  unref(formRef)?.resetValidation();
  result.value = '';
}
</script>

<template>
  <div class="flex flex-col gap-2 w-[380px] m-auto">
    <CdsForm ref="formRef" class="flex flex-col gap-2">
      <CdsTextInput v-model="name" :rules="rules.name" label="Имя" placeholder="Введите имя" />
      <CdsCheckbox v-model="agree" :rules="rules.agree" label="Согласен с условиями" />
    </CdsForm>
    <div class="flex flex-wrap gap-2">
      <CdsButton @click="validate">Проверить</CdsButton>
      <CdsButton variant="soft" color="brand" @click="reset">Сбросить</CdsButton>
      <CdsButton variant="soft" color="neutral" @click="resetValidation">Сбросить валидацию</CdsButton>
    </div>
    <div v-if="result" class="text-sm text-content-secondary">{{ result }}</div>
  </div>
</template>

Vee-validate

Форма дружит с внешними библиотеками валидации. С vee-validate схема задаётся в useForm, а сообщения об ошибках полей прокидываются в error-messages.

Sandbox Storybook

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

const { handleSubmit, handleReset } = useForm({
  validationSchema: {
    name(value: string) {
      if (!value) return 'Обязательно для заполнения';
      if (value.length < 3) return 'Минимальное кол-во символов 3';
      if (value.length > 10) return 'Максимальное кол-во символов 10';
      return true;
    },
    phone(value: string) {
      if (!value) return 'Обязательно для заполнения';
      if (value.length < 8) return 'Минимальное кол-во символов 8';
      if (value.length > 9) return 'Максимальное кол-во символов 9';
      return true;
    },
    email(value: string) {
      if (!value) return 'Обязательно для заполнения';
      if (!/^[a-z.-]+@[a-z.-]+\.[a-z]+$/i.test(value)) return 'Некорректный E-mail';
      return true;
    },
    checkbox(value: boolean) {
      if (!value) return 'Обязательно для заполнения';
      return true;
    }
  }
});

const name = useField('name');
const phone = useField('phone');
const email = useField('email');
const checkbox = useField('checkbox');

const result = ref('');

const submit = handleSubmit((values) => {
  result.value = `Отправлено: ${JSON.stringify(values)}`;
});

const clear = () => {
  handleReset();
  result.value = '';
};
</script>

<template>
  <CdsForm class="flex flex-col gap-2 w-[350px] m-auto" @submit.prevent="submit">
    <CdsTextInput
      v-model="name.value.value"
      :error-messages="name.errorMessage.value"
      label="Имя"
      placeholder="Введите имя"
    />
    <CdsTextInput
      v-model="phone.value.value"
      :error-messages="phone.errorMessage.value"
      label="Номер телефона"
      placeholder="Введите номер"
    />
    <CdsTextInput
      v-model="email.value.value"
      :error-messages="email.errorMessage.value"
      label="E-mail"
      placeholder="Введите E-mail"
    />
    <CdsCheckbox
      v-model="checkbox.value.value"
      :error-messages="checkbox.errorMessage.value"
      value="1"
      label="Согласен с условиями"
    />
    <div class="flex gap-2">
      <CdsButton type="submit">Отправить</CdsButton>
      <CdsButton variant="soft" color="brand" @click="clear">Очистить</CdsButton>
    </div>
    <div v-if="result" class="text-sm text-content-secondary break-all">{{ result }}</div>
  </CdsForm>
</template>

Vuelidate

С vuelidate правила объявляются декларативно, а ошибки полей так же прокидываются в error-messages.

Sandbox Storybook

<script setup lang="ts">
import { CdsButton, CdsCheckbox, CdsForm, CdsTextInput } from '@central-design-system/components';
import { useVuelidate } from '@vuelidate/core';
import { email, maxLength, minLength, required } from '@vuelidate/validators';
import { reactive, ref, unref } from 'vue';

const initialState = {
  name: '',
  email: '',
  phone: '',
  checkbox: null as boolean | null
};

const state = reactive({ ...initialState });
const result = ref('');

const rules = {
  name: { required },
  phone: { required, minLength: minLength(8), maxLength: maxLength(9) },
  email: { required, email },
  checkbox: { required }
};

const v$ = useVuelidate(rules, state);

const clear = () => {
  v$.value.$reset();
  result.value = '';

  for (const [key, value] of Object.entries(initialState)) {
    (state as Record<string, any>)[key] = value;
  }
};

const submit = () => {
  if (v$.value.$invalid) {
    v$.value.$touch();
    return;
  }

  result.value = `Отправлено: ${JSON.stringify(state)}`;
};
</script>

<template>
  <CdsForm class="flex flex-col gap-2 w-[350px] m-auto" @submit.prevent="submit">
    <CdsTextInput
      v-model="state.name"
      :error-messages="v$.name.$errors.map((e) => unref(e.$message))"
      label="Имя"
      placeholder="Введите имя"
      @input="v$.name.$touch()"
      @blur="v$.name.$touch()"
    />
    <CdsTextInput
      v-model="state.phone"
      :error-messages="v$.phone.$errors.map((e) => unref(e.$message))"
      label="Номер телефона"
      placeholder="Введите номер"
      @input="v$.phone.$touch()"
      @blur="v$.phone.$touch()"
    />
    <CdsTextInput
      v-model="state.email"
      :error-messages="v$.email.$errors.map((e) => unref(e.$message))"
      label="E-mail"
      placeholder="Введите E-mail"
      @input="v$.email.$touch()"
      @blur="v$.email.$touch()"
    />
    <CdsCheckbox
      v-model="state.checkbox"
      :error-messages="v$.checkbox.$errors.map((e) => unref(e.$message))"
      label="Согласен с условиями"
      @change="v$.checkbox.$touch()"
      @blur="v$.checkbox.$touch()"
    />
    <div class="flex gap-2">
      <CdsButton type="submit">Отправить</CdsButton>
      <CdsButton variant="soft" color="brand" @click="clear">Очистить</CdsButton>
    </div>
    <div v-if="result" class="text-sm text-content-secondary break-all">{{ result }}</div>
  </CdsForm>
</template>

API

Пропсы

Имя	Тип	По умолчанию	Описание
description	string | undefined	—	Описание формы. Рендерится под заголовком через CdsDescription.
disabled	boolean | null | undefined	null	Заблокированное состояние
firstFail	boolean | undefined	—	Останавливает валидацию на первом же невалидном поле — остальные поля не проверяются
label	string | undefined	—	Заголовок формы. Рендерится над контентом через CdsDescription.
modelValue	boolean | null | undefined	null	Итоговая валидность формы: true — все поля прошли проверку, false — есть ошибки, null — форма ещё не валидировалась
readonly	boolean | null | undefined	null	Только для чтения
validateOn	ValidateOn | undefined	'input'	Когда запускать валидацию полей формы: при вводе, потере фокуса или только вручную

События

Имя	Тип	Описание
submit	[payload: SubmitEventPromise]	Отправка формы. Событие — Promise с результатом валидации.
update:modelValue	[value: boolean | null]	Изменение общего статуса валидности формы (v-model).

Слоты

Имя	Тип	Описание
default	{ errors: FieldValidationResult[]; isDisabled: boolean | null | undefined; isReadonly: boolean | null | undefined; isValidating: boolean; isValid: boolean | null | undefined; items: FormField[]; validate: () => Promise<FormValidationResult>; reset: () => void; resetValidation: () => void; }	Основной контент формы. Получает текущее состояние и методы валидации.
description	any	Описание формы (переопределяет проп description).
label	any	Заголовок формы (переопределяет проп label).

Exposed

Имя	Тип	Описание
errors	{ id: string | number; errorMessages: string[]; }[]	Ошибки валидации полей формы: идентификатор поля и его сообщения об ошибках.
isDisabled	boolean | null | undefined	Заблокированы ли все поля формы.
isReadonly	boolean | null | undefined	Доступны ли поля формы только для чтения.
isValid	boolean | null | undefined	Валидность формы: true — все поля прошли проверку, false — есть ошибки, null — форма ещё не валидировалась.
isValidating	boolean	Идёт ли сейчас валидация формы.
items	{ id: string | number; validate: () => Promise<string[]>; reset: () => Promise<void>; resetValidation: () => Promise<void>; vm: Raw<ComponentInternalInstance>; isValid: boolean | null; errorMessages: string[]; }[]	Зарегистрированные в форме поля с их состоянием валидации.
resetValidation	() => void	Сбрасывает только состояние валидации, сохраняя введённые значения.
validate	() => Promise<{ valid: boolean; errors: FieldValidationResult[] | { id: string | number; errorMessages: string[]; }[]; }>	Запускает валидацию всех полей формы и возвращает результат вместе со списком ошибок.