Компонент Form
Главный составной компонент Form и его подкомпоненты
Form
Корневой составной компонент. Предоставляет контекст формы и валидацию.
<Form
schema={Schema}
initialValue={data}
onSubmit={async ({ value }) => { ... }}
>
{/* Компоненты полей */}
</Form>Props
| Проп | Тип | Описание |
|---|---|---|
schema | ZodObject | Zod схема валидации |
initialValue | T | Начальные данные формы |
onSubmit | (props: { value: T }) => Promise<void> | Обработчик отправки |
onError | (errors: FieldErrors) => void | Обработчик ошибок |
offline | OfflineConfig | Конфигурация офлайн-режима |
persistence | PersistenceConfig | Автосохранение в localStorage |
debug | boolean | 'force' | Показать DebugValues (только FromSchema) |
children | ReactNode | Содержимое формы |
persistence
<Form
schema={Schema}
initialValue={data}
onSubmit={handleSubmit}
persistence={{
key: 'checkout-form',
debounceMs: 500,
dialogTitle: 'Восстановить черновик?',
dialogDescription: 'У вас есть несохранённые изменения.',
restoreLabel: 'Восстановить',
discardLabel: 'Отменить',
}}
>Form.Field.*
40+ компонентов полей. См. Типы полей.
Общие пропсы всех полей:
| Проп | Тип | Описание |
|---|---|---|
name | string | Имя поля, совпадающее с ключом схемы |
label | string | Переопределить метку из схемы |
placeholder | string | Переопределить placeholder |
helperText | string | Дополнительная подсказка |
required | boolean | Обязательное поле |
disabled | boolean | Отключить поле |
Form.Group
Группировка полей во вложенный объект:
<Form.Group name="address">
<Form.Field.String name="street" />
</Form.Group>List
API: Form.Group.List
Динамический массив элементов:
<Form.Group.List name="items" sortable>
<Form.Field.String name="title" />
<Form.Group.List.Button.Add />
<Form.Group.List.Button.Remove />
</Form.Group.List>Steps
API: Form.Steps
Мультистеп мастер. См. Мультистеп формы.
Form.When
Условный рендеринг. См. Условные поля.
Form.Errors
Компонент сводки ошибок:
<Form.Errors title="Исправьте:" showFieldNames />Submit
API: Form.Button.Submit
Кнопка отправки, которая автоматически показывает спиннер загрузки во время отправки формы. Подписывается на состояние isSubmitting — когда onSubmit возвращает Promise, кнопка остаётся в состоянии загрузки до его разрешения.
Props
| Проп | Тип | По умолчанию | Описание |
|---|---|---|---|
children | ReactNode | "Submit" | Содержимое кнопки — текст, иконка, любой элемент |
loadingText | ReactNode | — | Текст при отправке (заменяет children) |
disabled | boolean | false | Отключить кнопку |
colorPalette | string | — | Цветовая палитра ("brand", "blue", "red") |
size | "xs" | "sm" | "md" | "lg" | "md" | Размер кнопки |
variant | "solid" | "outline" | "ghost" | "subtle" | "solid" | Вариант кнопки |
width | string | number | — | Ширина кнопки ("100%" для полной ширины) |
Базовое использование
<Form.Button.Submit>Сохранить</Form.Button.Submit>Текст при загрузке
Показать кастомный текст во время отправки:
<Form.Button.Submit loadingText="Сохранение...">Сохранить</Form.Button.Submit>Кастомная стилизация
<Form.Button.Submit colorPalette="brand" size="lg" width="100%">
Создать аккаунт
</Form.Button.Submit>Как работает загрузка
Кнопка автоматически переходит в состояние загрузки, когда onSubmit — асинхронная функция. Чтобы увидеть эффект, добавьте задержку:
<Form
schema={Schema}
initialValue={data}
onSubmit={async ({ value }) => {
await new Promise((r) => setTimeout(r, 1500))
alert(`Отправлено: ${JSON.stringify(value)}`)
}}
>
<Form.Field.String name="name" />
<Form.Button.Submit loadingText="Отправка...">Отправить</Form.Button.Submit>
</Form>Reset
API: Form.Button.Reset
Сброс формы к начальным значениям:
<Form.Button.Reset>Сбросить</Form.Button.Reset>Form.FromSchema
Автогенерация формы из схемы:
<Form.FromSchema schema={Schema} initialValue={data} onSubmit={handleSubmit} submitLabel="Создать" columns={2} />Form.AutoFields
Автогенерация полей с фильтрацией:
<Form.AutoFields />
<Form.AutoFields include={['name', 'email']} />
<Form.AutoFields exclude={['id', 'createdAt']} />| Проп | Тип | Описание |
|---|---|---|
include | string[] | Только эти поля |
exclude | string[] | Пропустить эти поля |
recursive | boolean | Авто вложенные объекты (по умолчанию: true) |
Form.DebugValues
Интерактивный JSON-инспектор значений формы:
<Form.DebugValues title="Текущие значения" collapsed={3} />Form.DirtyGuard
Предупреждение о несохранённых изменениях при уходе со страницы (закрытие вкладки, обновление, клик по внутренней ссылке):
<Form.DirtyGuard />Тексты (dialogTitle, dialogDescription, confirmText, cancelText, message) резолвятся так: проп →
перевод приложения по ключу formDirtyGuard.<проп> (FormI18nProvider с t) → встроенный словарь ru/en по
locale → английский, если провайдера нет. Проп сильнее всего:
<Form.DirtyGuard dialogTitle="Уйти?" confirmText="Да, уйти" cancelText="Нет, остаться" />Включите её сразу для всех форм инстанса, не расставляя компонент вручную (v2.18.0+):
const AppForm = createForm({ dirtyGuard: true }) // или { dialogTitle, dialogDescription, confirmText, cancelText }
<AppForm dirtyGuard={false} onSubmit={login}>…</AppForm> // логин, фильтры: выключитьПроп формы перебивает опцию инстанса (false — выключить, true — оставить тексты инстанса, объект — дополнить
их). По умолчанию выключено. Вручную поставленный <Form.DirtyGuard /> в форме с автозащитой берёт работу на
себя без второго окна, а dirtyGuard={false} явно поставленный компонент не отключает.
Не ловится: программный router.push() / router.replace() и кнопки «Назад»/«Вперёд» браузера (popstate
приходит уже после смены адреса, отменить его нельзя). Для программной навигации проверяйте
form.state.isDirty сами перед router.push.
Form.Subscribe
Реактивная подписка на значения формы:
<Form.Subscribe>{(values) => <Preview data={values} />}</Form.Subscribe>createForm
Создание расширенной формы. См. createForm guide.