@letar/forms — Declarative Form Components for React

Generate forms automatically from Zod schemas — from zero-JSX to fine-grained control

Full example

The complete sandbox example, read directly from the form-develop-app / form-develop-app-shadcn source at build time. The chakra source uses Form.AutoFields; the shadcn source uses FieldAuto — a different level of the control hierarchy below, but the same idea of generating fields automatically from a Zod schema. No Vue/Angular equivalent exists yet — those tabs show as disabled.

apps/form-develop-app/src/app/auto-fields-demo/page.tsx

'use client'

import { Badge, Box, Code, Heading, HStack, Separator, Text, VStack } from '@chakra-ui/react'
import { Form } from '@letar/forms'
import { useState } from 'react'
import { z } from 'zod/v4'
import { DemoPageLayout, SubmittedDataPreview } from '../_components'

/**
 * Демонстрация автоматической генерации форм из Zod схемы
 *
 * Три подхода:
 * 1. Form.FromSchema — полностью автоматическая форма
 * 2. Form.AutoFields — генерация полей внутри Form
 * 3. Смешанный подход — AutoFields + ручные поля
 */

// === Схема для Form.FromSchema ===
const UserSchema = z.object({
  firstName: z
    .string()
    .min(2)
    .meta({ ui: { title: 'Имя', placeholder: 'Введите имя' } }),
  lastName: z
    .string()
    .min(2)
    .meta({ ui: { title: 'Фамилия', placeholder: 'Введите фамилию' } }),
  email: z
    .string()
    .email()
    .meta({ ui: { title: 'Email', placeholder: 'user@example.com' } }),
  age: z
    .number()
    .min(18)
    .max(120)
    .meta({ ui: { title: 'Возраст' } }),
  bio: z
    .string()
    .max(500)
    .meta({ ui: { title: 'О себе', fieldType: 'textarea', placeholder: 'Расскажите о себе...' } }),
  role: z.enum(['admin', 'user', 'guest']).meta({ ui: { title: 'Роль' } }),
  isActive: z.boolean().meta({ ui: { title: 'Активен' } }),
})

type UserFormData = z.infer<typeof UserSchema>

const userInitialValues: UserFormData = {
  firstName: '',
  lastName: '',
  email: '',
  age: 25,
  bio: '',
  role: 'user',
  isActive: true,
}

// === Схема для AutoFields с вложенными объектами ===
const ProfileSchema = z.object({
  name: z.string().meta({ ui: { title: 'Имя профиля' } }),
  settings: z.object({
    theme: z.enum(['light', 'dark', 'auto']).meta({ ui: { title: 'Тема' } }),
    notifications: z.boolean().meta({ ui: { title: 'Уведомления' } }),
    language: z.enum(['ru', 'en', 'de']).meta({ ui: { title: 'Язык' } }),
  }),
})

type ProfileFormData = z.infer<typeof ProfileSchema>

const profileInitialValues: ProfileFormData = {
  name: 'Мой профиль',
  settings: {
    theme: 'auto',
    notifications: true,
    language: 'ru',
  },
}

// === Схема для смешанного подхода ===
const ArticleSchema = z.object({
  title: z
    .string()
    .min(5)
    .max(100)
    .meta({ ui: { title: 'Заголовок' } }),
  slug: z.string().meta({ ui: { title: 'URL slug' } }),
  category: z.enum(['news', 'blog', 'tutorial']).meta({ ui: { title: 'Категория' } }),
  content: z.string().meta({ ui: { title: 'Содержимое', fieldType: 'richText' } }),
  published: z.boolean().meta({ ui: { title: 'Опубликовано', fieldType: 'switch' } }),
  rating: z
    .number()
    .min(1)
    .max(5)
    .meta({ ui: { title: 'Рейтинг', fieldType: 'rating' } }),
})

type ArticleFormData = z.infer<typeof ArticleSchema>

const articleInitialValues: ArticleFormData = {
  title: '',
  slug: '',
  category: 'blog',
  content: '',
  published: false,
  rating: 3,
}

export default function AutoFieldsDemoPage() {
  const [fromSchemaData, setFromSchemaData] = useState<UserFormData | null>(null)
  const [autoFieldsData, setAutoFieldsData] = useState<ProfileFormData | null>(null)
  const [mixedData, setMixedData] = useState<ArticleFormData | null>(null)

  return (
    <DemoPageLayout
      title="Auto Fields Demo"
      description="Демонстрация автоматической генерации форм из Zod схемы с использованием Form.FromSchema, Form.AutoFields и смешанного подхода."
      maxW="1200px"
    >
      <VStack gap={8} align="stretch">
        {/* === СЕКЦИЯ 1: Form.FromSchema === */}
        <Box p={6} borderWidth={1} borderRadius="lg">
          <HStack mb={4}>
            <Heading size="md">1. Form.FromSchema</Heading>
            <Badge colorPalette="green">Полностью автоматически</Badge>
          </HStack>
          <Text color="fg.muted" mb={4}>
            Генерирует всю форму из схемы одной строкой. Поля, кнопки — всё автоматически.
          </Text>

          <Code
            display="block"
            whiteSpace="pre"
            mb={4}
            p={3}
            bg="gray.100"
            borderRadius="md"
            _dark={{ bg: 'gray.800' }}
          >
            {`<Form.FromSchema
  schema={UserSchema}
  initialValue={initialValues}
  onSubmit={handleSubmit}
  submitLabel="Создать пользователя"
/>`}
          </Code>

          <Form.FromSchema
            schema={UserSchema}
            initialValue={userInitialValues}
            onSubmit={setFromSchemaData}
            submitLabel="Создать пользователя"
            showReset
            resetLabel="Очистить"
          />

          {fromSchemaData && <SubmittedDataPreview data={fromSchemaData} title="Отправленные данные:" />}
        </Box>

        <Separator />

        {/* === СЕКЦИЯ 2: Form.AutoFields === */}
        <Box p={6} borderWidth={1} borderRadius="lg">
          <HStack mb={4}>
            <Heading size="md">2. Form.AutoFields</Heading>
            <Badge colorPalette="blue">С кастомным layout</Badge>
          </HStack>
          <Text color="fg.muted" mb={4}>
            Генерирует поля из схемы, но layout контролируется вручную. Поддерживает include/exclude.
          </Text>

          <Code
            display="block"
            whiteSpace="pre"
            mb={4}
            p={3}
            bg="gray.100"
            borderRadius="md"
            _dark={{ bg: 'gray.800' }}
          >
            {`<Form schema={ProfileSchema} ...>
  <HStack>
    <Form.AutoFields include={['name']} />
  </HStack>
  <Form.AutoFields exclude={['name']} />
  <Form.Button.Submit />
</Form>`}
          </Code>

          <Form schema={ProfileSchema} initialValue={profileInitialValues} onSubmit={setAutoFieldsData}>
            <VStack gap={4} align="stretch">
              {/* Имя отдельно сверху */}
              <Form.AutoFields include={['name']} />

              {/* Настройки — автоматически развернётся вложенный объект */}
              <Box p={4} bg="gray.50" borderRadius="md">
                <Text fontWeight="bold" mb={2}>
                  Настройки (автоматическая вложенность)
                </Text>
                <Form.AutoFields include={['settings']} />
              </Box>

              <HStack justify="flex-end">
                <Form.Button.Submit>Сохранить профиль</Form.Button.Submit>
              </HStack>
            </VStack>
          </Form>

          {autoFieldsData && <SubmittedDataPreview data={autoFieldsData} title="Отправленные данные:" />}
        </Box>

        <Separator />

        {/* === СЕКЦИЯ 3: Смешанный подход === */}
        <Box p={6} borderWidth={1} borderRadius="lg">
          <HStack mb={4}>
            <Heading size="md">3. Смешанный подход</Heading>
            <Badge colorPalette="purple">AutoFields + ручные поля</Badge>
          </HStack>
          <Text color="fg.muted" mb={4}>
            Часть полей генерируется автоматически, часть — вручную с кастомной логикой. fieldType в meta определяет
            компонент.
          </Text>

          <Code
            display="block"
            whiteSpace="pre"
            mb={4}
            p={3}
            bg="gray.100"
            borderRadius="md"
            _dark={{ bg: 'gray.800' }}
          >
            {`// В схеме:
content: z.string().meta({ ui: { fieldType: 'richText' } })
rating: z.number().meta({ ui: { fieldType: 'rating' } })
published: z.boolean().meta({ ui: { fieldType: 'switch' } })

// В JSX:
<Form.AutoFields exclude={['content']} />
<Form.Field.RichText name="content" />  // Кастомная обёртка`}
          </Code>

          <Form schema={ArticleSchema} initialValue={articleInitialValues} onSubmit={setMixedData}>
            <VStack gap={4} align="stretch">
              {/* Основные поля автоматически */}
              <HStack gap={4} align="flex-start">
                <Box flex={2}>
                  <Form.Field.Auto name="title" />
                </Box>
                <Box flex={1}>
                  <Form.Field.Auto name="slug" />
                </Box>
              </HStack>

              <HStack gap={4}>
                <Box flex={1}>
                  <Form.Field.Auto name="category" />
                </Box>
                <Box flex={1}>
                  <Form.Field.Auto name="rating" />
                </Box>
                <Box flex={1}>
                  <Form.Field.Auto name="published" />
                </Box>
              </HStack>

              {/* Контент — вручную с кастомной высотой */}
              <Box>
                <Form.Field.RichText name="content" label="Содержимое статьи" />
              </Box>

              <HStack justify="flex-end" gap={2}>
                <Form.Button.Reset variant="outline">Сбросить</Form.Button.Reset>
                <Form.Button.Submit>Опубликовать статью</Form.Button.Submit>
              </HStack>
            </VStack>
          </Form>

          {mixedData && <SubmittedDataPreview data={mixedData} title="Отправленные данные:" />}
        </Box>

        <Separator />

        {/* === Документация fieldType === */}
        <Box p={6} borderWidth={1} borderRadius="lg" bg="gray.50">
          <Heading size="md" mb={4}>
            Поддерживаемые fieldType
          </Heading>
          <Text color="fg.muted" mb={4}>
            В <Code>meta(&#123; ui: &#123; fieldType: &apos;...&apos; &#125; &#125;)</Code>{' '}
            можно указать любой тип поля:
          </Text>

          <HStack gap={8} flexWrap="wrap">
            <VStack align="start" gap={1}>
              <Text fontWeight="bold">Текстовые</Text>
              <Code>string</Code>
              <Code>textarea</Code>
              <Code>password</Code>
              <Code>richText</Code>
              <Code>editable</Code>
              <Code>maskedInput</Code>
            </VStack>

            <VStack align="start" gap={1}>
              <Text fontWeight="bold">Числовые</Text>
              <Code>number</Code>
              <Code>numberInput</Code>
              <Code>slider</Code>
              <Code>rating</Code>
              <Code>currency</Code>
              <Code>percentage</Code>
            </VStack>

            <VStack align="start" gap={1}>
              <Text fontWeight="bold">Дата/время</Text>
              <Code>date</Code>
              <Code>time</Code>
              <Code>dateRange</Code>
              <Code>dateTimePicker</Code>
              <Code>duration</Code>
              <Code>schedule</Code>
            </VStack>

            <VStack align="start" gap={1}>
              <Text fontWeight="bold">Выбор</Text>
              <Code>select</Code>
              <Code>nativeSelect</Code>
              <Code>combobox</Code>
              <Code>radioGroup</Code>
              <Code>checkboxCard</Code>
              <Code>tags</Code>
            </VStack>

            <VStack align="start" gap={1}>
              <Text fontWeight="bold">Булевые</Text>
              <Code>checkbox</Code>
              <Code>switch</Code>
            </VStack>

            <VStack align="start" gap={1}>
              <Text fontWeight="bold">Специализированные</Text>
              <Code>phone</Code>
              <Code>address</Code>
              <Code>pinInput</Code>
              <Code>colorPicker</Code>
              <Code>fileUpload</Code>
            </VStack>
          </HStack>
        </Box>
      </VStack>
    </DemoPageLayout>
  )
}

apps/form-develop-app-shadcn/src/app/auto-fields-demo/page.tsx

'use client'

import { FieldAuto } from '@letar/forms-shadcn'
import { z } from 'zod/v4'

import { DemoForm, DemoPageLayout } from '../_components'

const autoDemoSchema = z.object({
  fullName: z.string(),
  bio: z.string().max(500),
  age: z.number(),
  subscribed: z.boolean(),
  plan: z.enum(['free', 'pro', 'enterprise']),
})

export default function AutoFieldsDemoPage() {
  return (
    <DemoPageLayout
      title="FieldAuto (beta)"
      description={'Автоопределение типа поля из Zod-схемы — изолированная песочница со своей схемой (единственная демо-форма '
        + 'на приложении, где DemoForm получает schema).'}
    >
      <DemoForm<{ fullName: string; bio: string; age: number; subscribed: boolean; plan: string }>
        schema={autoDemoSchema}
        defaultValues={{ fullName: '', bio: '', age: 18, subscribed: false, plan: 'free' }}
        onSubmit={(value) => {
          // eslint-disable-next-line no-console
          console.log('auto submit', value)
        }}
      >
        <FieldAuto name="fullName" />
        <FieldAuto name="bio" />
        <FieldAuto name="age" />
        <FieldAuto name="subscribed" config={{ booleanAsSwitch: true }} />
        <FieldAuto name="plan" />

        <button
          type="submit"
          className="bg-primary text-primary-foreground mt-4 rounded-md px-4 py-2 text-sm font-medium"
        >
          Отправить
        </button>
      </DemoForm>
    </DemoPageLayout>
  )
}

The 4-Level Control Hierarchy

The library offers four levels of form generation, each giving you more control:

Level	Component	JSX needed	Use case
1	`Form.FromSchema`	None	CRUD, prototyping, admin panels
2	`Form.AutoFields`	Layout only	Custom layout with auto fields
3	`Form.Field.*`	Fields + layout	Full control over each field
4	`useAppForm`	Everything	Imperative logic, custom hooks

Each level is backward-compatible — you can mix them freely within one form.

Level 1: Form.FromSchema — Zero JSX

Generate a complete form from a Zod schema with no field JSX at all:

import { Form } from '@letar/forms'
import { z } from 'zod/v4'

const UserSchema = z.object({
  firstName: z.string().min(2).meta({ ui: { title: 'First Name' } }),
  lastName: z.string().meta({ ui: { title: 'Last Name' } }),
  email: z.string().email().meta({ ui: { title: 'Email' } }),
  bio: z.string().max(500).meta({ ui: { title: 'Bio', fieldType: 'textarea' } }),
})

<Form.FromSchema
  schema={UserSchema}
  initialValue={{ firstName: '', lastName: '', email: '', bio: '' }}
  onSubmit={save}
  submitLabel="Create User"
/>

This renders all four fields with labels, validation, and a submit button — no JSX for fields required.

FromSchema Props

Prop	Type	Default	Description
`schema`	Zod schema	required	Schema for validation and field generation
`initialValue`	`TData`	required	Initial form values
`onSubmit`	`(data: TData) => void`	required	Submit handler
`submitLabel`	`ReactNode`	`'Save'`	Submit button text
`showReset`	`boolean`	`false`	Show reset button
`resetLabel`	`ReactNode`	`'Reset'`	Reset button text
`exclude`	`string[]`	—	Fields to exclude
`validateOn`	`ValidateOn`	—	Validation trigger mode
`middleware`	`FormMiddleware`	—	Form event middleware
`disabled`	`boolean`	—	Disable all fields
`readOnly`	`boolean`	—	Read-only mode
`persistence`	`FormPersistenceConfig`	—	localStorage config
`offline`	`FormOfflineConfig`	—	Offline mode config
`debug`	`boolean \| 'force'`	—	JSON value inspector
`gap`	`number`	`4`	Gap between fields
`beforeButtons`	`ReactNode`	—	Content before buttons
`afterButtons`	`ReactNode`	—	Content after buttons

Excluding Fields

Hide system fields like id or timestamps:

<Form.FromSchema
  schema={UserSchema}
  initialValue={userData}
  onSubmit={updateUser}
  exclude={['id', 'createdAt', 'updatedAt']}
  showReset
/>

Level 2: Form.AutoFields — Auto Generation + Custom Layout

When you need control over layout but don't want to write every field manually:

<Form schema={Schema} initialValue={data} onSubmit={save}>
  <HStack gap={4}>
    <Form.AutoFields include={['firstName', 'lastName']} />
  </HStack>
  <Form.AutoFields exclude={['firstName', 'lastName']} />
  <Form.Button.Submit />
</Form>

AutoFields Props

Prop	Type	Default	Description
`include`	`string[]`	—	Only render these fields
`exclude`	`string[]`	—	Exclude these fields
`recursive`	`boolean`	`true`	Auto-expand nested objects
`fieldWrapper`	`(props) => ReactElement`	—	Custom wrapper per field

Custom Field Wrapper

Wrap each auto-generated field with custom JSX:

<Form.AutoFields
  fieldWrapper={({ name, children }) => (
    <Box key={name} p={2} borderWidth={1} borderRadius="md">
      {children}
    </Box>
  )}
/>

Mixing Auto and Manual Fields

Combine auto-generated fields with hand-crafted ones:

<Form schema={ArticleSchema} initialValue={data} onSubmit={save}>
  <HStack gap={4}>
    <Box flex={2}>
      <Form.Field.Auto name="title" />
    </Box>
    <Box flex={1}>
      <Form.Field.Auto name="slug" />
    </Box>
  </HStack>
  <Form.Field.RichText name="content" label="Article Content" />
  <Form.Button.Submit>Publish</Form.Button.Submit>
</Form>

Form.Field.Auto renders the appropriate field component based on the schema type for that field.

Type Mapping

The library maps Zod types to field components automatically:

Default Mapping (Zod → Component)

Zod Type	Component	Condition
`z.string()`	`Form.Field.String`	Default
`z.string()`	`Form.Field.Textarea`	When `maxLength > 200`
`z.string().email()`	`Form.Field.String`	With `type="email"`
`z.number()` / `z.int()` / `z.float()`	`Form.Field.Number`
`z.boolean()`	`Form.Field.Checkbox`
`z.date()`	`Form.Field.Date`
`z.enum()` / `z.literal()`	`Form.Field.NativeSelect`
`z.array(z.string())`	`Form.Field.Tags`	String arrays
`z.array(z.object())`	`Form.Group.List`	Object arrays

Override with `fieldType`

Use .meta({ ui: { fieldType } }) to override the default mapping:

const Schema = z.object({
  // Force textarea instead of string input
  description: z.string().meta({ ui: { title: 'Description', fieldType: 'textarea' } }),

  // Use slider instead of number input
  rating: z
    .number()
    .min(0)
    .max(10)
    .meta({ ui: { title: 'Rating', fieldType: 'slider' } }),

  // Use rich text editor
  content: z.string().meta({ ui: { title: 'Content', fieldType: 'richText' } }),

  // Use switch instead of checkbox
  active: z.boolean().meta({ ui: { title: 'Active', fieldType: 'switch' } }),

  // Use radio cards instead of select
  plan: z.enum(['free', 'pro', 'enterprise']).meta({
    ui: {
      title: 'Plan',
      fieldType: 'radioCard',
      fieldProps: {
        options: [
          { value: 'free', label: 'Free', description: 'For individuals' },
          { value: 'pro', label: 'Pro', description: 'For teams' },
          { value: 'enterprise', label: 'Enterprise', description: 'Custom' },
        ],
      },
    },
  }),
})

All Available fieldTypes

Text: string, textarea, password, passwordStrength, editable, richText, maskedInput

Number: number, numberInput, slider, rating, currency, percentage

Date/Time: date, time, dateRange, dateTimePicker, duration, schedule

Boolean: checkbox, switch

Selection: select, nativeSelect, combobox, autocomplete, listbox, radioGroup, radioCard, segmentedGroup, checkboxCard, tags

Specialized: phone, address, pinInput, otpInput, colorPicker, fileUpload

UI Metadata

Control field appearance through .meta({ ui: {...} }):

const Schema = z.object({
  email: z
    .string()
    .email()
    .meta({
      ui: {
        title: 'Email Address', // Label
        placeholder: 'user@example.com', // Placeholder
        description: 'We never share it', // Helper text
        fieldType: 'string', // Component override
        fieldProps: { type: 'email' }, // Props passed to component
      },
    }),
})

Meta Property	Type	Description
`title`	`string`	Field label
`placeholder`	`string`	Placeholder text
`description`	`string`	Helper text below field
`fieldType`	`FieldComponentType`	Override component type
`fieldProps`	`Record<string, unknown>`	Additional component props
`options`	`BaseOption[]`	Options for select fields
`autocomplete`	`string`	HTML autocomplete attribute

If title is not provided, the field name is converted from camelCase to a readable label (e.g., firstName → First Name).

Nested Objects and Arrays

Nested Objects

Objects are automatically rendered as Form.Group with their fields indented:

const ProfileSchema = z.object({
  name: z.string().meta({ ui: { title: 'Name' } }),
  settings: z.object({
    theme: z.enum(['light', 'dark']).meta({ ui: { title: 'Theme' } }),
    notifications: z.boolean().meta({ ui: { title: 'Notifications' } }),
  }),
})

// AutoFields automatically nests settings fields under a group
<Form.FromSchema schema={ProfileSchema} initialValue={data} onSubmit={save} />

Disable recursive expansion with recursive={false}.

Object Arrays

Arrays of objects render as Form.Group.List with add/remove buttons:

const OrderSchema = z.object({
  customer: z.string(),
  items: z.array(
    z.object({
      product: z.string().meta({ ui: { title: 'Product' } }),
      qty: z.number().min(1).meta({ ui: { title: 'Quantity' } }),
    })
  ),
})

// Each array item gets its own card with fields + remove button
<Form.FromSchema schema={OrderSchema} initialValue={data} onSubmit={save} />

Primitive Arrays

String arrays are rendered as Form.Field.Tags:

const Schema = z.object({
  tags: z.array(z.string()).meta({ ui: { title: 'Tags' } }),
})

Automatic Constraints

Zod constraints are passed as component props automatically:

z.string().min(2).max(100) // → minLength={2} maxLength={100}
z.number().min(1).max(10) // → min={1} max={10}
z.string().email() // → type="email"
z.date().min(new Date()) // → min={now}

No need to duplicate constraints in JSX — the schema is the single source of truth.

When to Use Each Level

Scenario	Recommended Level
Admin CRUD forms	`Form.FromSchema`
Rapid prototyping	`Form.FromSchema`
Simple forms with custom layout	`Form.AutoFields`
Complex multi-column layouts	`Form.Field.*` (Compound Components)
Multi-step forms	`Form.Field.*` + `Form.Steps`
Conditional rendering	`Form.Field.*` + `Form.When`
Custom UX (animations, inline editing)	`useAppForm`

Rule of thumb: If the form is a linear vertical flow, FromSchema or AutoFields work great. For complex layouts, use Compound Components.

Live Examples

Try the interactive examples on forms-example.letar.best:

Auto Fields — Basic — FromSchema and AutoFields basics
Auto Fields — Advanced — Filtering, mixed approach, nested objects

Automatic Form Generation