The form does not render the fields itself — build them out of CdsTextInput, CdsSelect, CdsCheckbox and other controls. The validation rules are declared on the fields themselves through the rules prop.

Anatomy

The form is a native form with an optional header: the heading and the description are rendered above the content, and the fields from the default slot stay as they are. The heading is bound to the form through aria-labelledby, the description — through aria-describedby.

Storybook

Variations

Heading and description

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

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>

Validity status

The v-model of the form is the common status of its fields: null while the form has not been checked, false on errors and true when all the fields are valid. The status is updated on the fly — it is handy for blocking the submit button, for example.

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>

The moment of validation

The validate-on prop sets the moment the check runs for all the fields of the form; the field's own validate-on takes precedence. Switch the mode and try it out: with input (the default) the error appears as you type, with blur — after leaving the field, with submit — only when the form is submitted.

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>

Fast validation

The first-fail prop stops the check at the first invalid field. Submit the form: the error is shown only for "Имя", although "Фамилия" is invalid too.

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>

States

disabled blocks all the fields of the form at once, readonly keeps the values visible and copyable but forbids changing them. There is no need to configure the individual fields — the state is inherited.

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>

Hiding the details

The bottom block with the messages is controlled by the hide-details prop on the fields themselves: true always hides the block — errors included, false always reserves space for it, auto shows the block only when there is something to show. In dense forms use auto: the fields sit right next to each other, but the validation errors are not lost. Switch the value and submit an empty form.

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>

Slots

The default slot receives the state of the form and the control methods — the "Check" and "Reset" buttons are built without a ref to the component.

Slot name	Description
label	Heading content (replaces label)
description	Description content (replaces description)
default	Form content; slot props: 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>

Guidelines

Storybook

Scenarios

Submitting a form

The submit event is a Promise: await event returns the validation result, and the handler decides on its own whether to send the data. The .prevent modifier turns off the native page submission. The request here is simulated with setTimeout, and the button shows loading for the duration of the "request".

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>

Control from outside

The validate, reset and resetValidation methods are also available through a ref to the form. That is how the form is driven from outside — from the footer of a modal or a wizard panel, where the buttons live outside the form markup.

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

The form gets along with external validation libraries. With vee-validate the schema is set in useForm, and the error messages of the fields are passed into 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

With vuelidate the rules are declared declaratively, and the field errors are passed into error-messages in the same way.

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

Props

Name	Type	Default	Description
description	string | undefined	—	Description of the form. Rendered under the heading through CdsDescription.
disabled	boolean | null | undefined	null	Disabled state
firstFail	boolean | undefined	—	Stops the validation at the very first invalid field — the remaining fields are not checked
label	string | undefined	—	Heading of the form. Rendered above the content through CdsDescription.
modelValue	boolean | null | undefined	null	Resulting validity of the form: true — every field passed the check, false — there are errors, null — the form has not been validated yet
readonly	boolean | null | undefined	null	Read-only state
validateOn	ValidateOn | undefined	'input'	When to run the validation of the form fields: on input, on blur or manually only

Events

Name	Type	Description
submit	[payload: SubmitEventPromise]	Submission of the form. The event is a Promise with the validation result.
update:modelValue	[value: boolean | null]	The overall validity status of the form changed (v-model).

Slots

Name	Type	Description
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; }	Main content of the form. Receives the current state and the validation methods.
description	any	Description of the form (overrides the description prop).
label	any	Heading of the form (overrides the label prop).

Exposed

Name	Type	Description
errors	{ id: string | number; errorMessages: string[]; }[]	Validation errors of the form fields: the identifier of a field and its error messages.
isDisabled	boolean | null | undefined	Whether all the fields of the form are blocked.
isReadonly	boolean | null | undefined	Whether the fields of the form are read-only.
isValid	boolean | null | undefined	Validity of the form: true — every field passed the check, false — there are errors, null — the form has not been validated yet.
isValidating	boolean	Whether the form is being validated right now.
items	{ id: string | number; validate: () => Promise<string[]>; reset: () => Promise<void>; resetValidation: () => Promise<void>; vm: Raw<ComponentInternalInstance>; isValid: boolean | null; errorMessages: string[]; }[]	The fields registered in the form together with their validation state.
resetValidation	() => void	Resets the validation state only, keeping the entered values.
validate	() => Promise<{ valid: boolean; errors: FieldValidationResult[] | { id: string | number; errorMessages: string[]; }[]; }>	Runs the validation of all the form fields and returns the result together with the list of errors.