Quickstart

Learn the core design philosophy and basic usage of AutoForm.

What is AutoForm

AutoForm is an automatic form generation system based on Zod Schema. Through declarative Schema definitions, it automatically generates a complete form interface including input controls, validation rules, and layout structure.

Core Advantages

Schema is the Form - A single Schema defines data structure, validation rules, and UI configuration simultaneously
Type Safe - Full TypeScript type inference, from Schema to form data
Zero Template Code - No need to write v-for or repetitive form field templates

Basic Example

Create a simple user registration form:

<script lang="ts" setup>
import type { FormSubmitEvent } from '@nuxt/ui'
import type { z } from 'zod'

const { afz } = useAutoForm()
const toast = useToast()

const schema = afz.object({
  username: afz.string('请填写用户名').min(3).max(20).regex(/^\w+$/),
  email: afz.email({
    controlProps: {
      leadingIcon: 'i-lucide-mail',
      placeholder: '请输入您的邮箱'
    },
    error: '请输入有效的邮箱地址'
  }).meta({ hint: '邮箱' }),
  password: afz.string({ type: 'withPasswordToggle' })
    .min(8)
    .regex(/[A-Z]/)
    .regex(/[a-z]/)
    .regex(/\d/),
  confirmPassword: afz.string({ type: 'withPasswordToggle' }),
  acceptTerms: afz.boolean({
    controlProps: { label: '我同意服务条款和隐私政策', required: true }
  })
}).refine(
  data => data.password === data.confirmPassword,
  { message: '两次密码不一致', path: ['confirmPassword'] }
).refine(
  data => data.acceptTerms === true,
  { message: '必须同意条款', path: ['acceptTerms'] }
)

type Schema = z.output<typeof schema>

const form = ref<Partial<Schema>>({})

async function onSubmit(event: FormSubmitEvent<Schema>) {
  toast.add({
    title: 'Success',
    color: 'success',
    description: JSON.stringify(event.data, null, 2)
  })
}
</script>

<template>
  <MAutoForm :schema="schema" :state="form" @submit="onSubmit" />
</template>

API

Props

Prop	Default	Type
`schema`		`S` Zod 对象 schema，定义表单字段
`state`		`N extends false ? Partial<InferInput<S>> : never` 表单的状态对象。
`submitButtonProps`		`ButtonProps` 提交按钮属性
`addButtonProps`		`ButtonProps` 数组字段添加按钮属性
`controls`		`AutoFormControls` 自定义控件映射
`globalMeta`		`ZodAutoFormFieldMeta` 全局字段元数据配置
`validateOn`	`[]`	`FormInputEvents[]` 表单验证时机，详见 UForm 的 validateOn 属性
`id`		`string \| number`
`validate`		`(state: Partial<InferInput<S>>) => FormError<string>[] \| Promise<FormError<string>[]>` Custom validation function to validate the form state.
`name`		`string` The `name` attribute of the form element. For nested forms (`nested` is true), this is also used as the path of the form's state within its parent form.
`validateOnInputDelay`	`300`	`number` Delay in milliseconds before validating the form on input events.
`transform`	`true`	`T` If true, applies schema transformations on submit.
`nested`	`false`	`N` If true, this form will attach to its parent Form and validate at the same time.
`onSubmit`		`(): void \| Promise<void> \| (event: FormSubmitEvent<FormData<S, T>>): void \| Promise<void>`
`acceptcharset`		`string`
`action`		`string`
`autocomplete`		`string`
`enctype`		`string`
`method`		`string`
`novalidate`		`false \| true \| "true" \| "false"`
`target`		`string`
`submit`	`true`	`boolean` 是否显示默认提交按钮
`loadingAuto`	`true`	`boolean` 是否启用自动 loading 功能。
`disabled`		`boolean` Disable all inputs inside the form.
`ui`		`Record<string, ClassNameValue> & { root?: SlotClass; base?: SlotClass; collapsible?: SlotClass; header?: SlotClass; footer?: SlotClass; actions?: SlotClass; }`

Slots

Slot	Type
`header`	`AutoFormSlotProps<AutoFormStateType>`
`footer`	`AutoFormSlotProps<AutoFormStateType>`
`submit`	`AutoFormSlotProps<AutoFormStateType>`
`field-label`	`{ label?: string; } & AutoFormFieldContext<AutoFormStateType, string>`
`field-hint`	`{ hint?: string; } & AutoFormFieldContext<AutoFormStateType, string>`
`field-description`	`{ description?: string; } & AutoFormFieldContext<AutoFormStateType, string>`
`field-help`	`{ help?: string; } & AutoFormFieldContext<AutoFormStateType, string>`
`field-error`	`{ error?: string \| boolean; } & AutoFormFieldContext<AutoFormStateType, string>`
`field-default`	`{ error?: string \| boolean; } & AutoFormFieldContext<AutoFormStateType, string>`

In addition to component-level slots, AutoForm also supports field-level dynamic slots with full TypeScript type inference and editor autocompletion.

Slot Pattern	Example	Description
`field-{slotType}`	`field-label`, `field-default`	Generic slot, applies to all fields
`field-{slotType}:{fieldKey}`	`field-label:username`, `field-default:email`	Specific field slot with full type inference
`field-{position}:{fieldKey}`	`field-before:profile`, `field-content:tasks`	Nested field layout slot

Emits

Event	Type
`error`	`[FormErrorEvent]`

Expose

You can access the typed component instance via useTemplateRef.

Name	Type
`reset()`	`void` Reset the form to its initial state, restoring the `state` from props and applying all default values
`clear()`	`void` Clear all form field data
`formRef`	`Ref<InstanceType<typeof UForm> \| null>` Template ref of the UForm component, provides access to all underlying form methods and properties

Through formRef you can access all UForm underlying functionality, including submit(), validate(), clear(), getErrors(), setErrors() methods, and reactive properties such as errors, disabled, dirty, dirtyFields, touchedFields, blurredFields. See the Nuxt UI Form documentation for details.

Theme

app.config.ts

export default defineAppConfig({
  ui: {
    autoForm: {
      slots: {
        root: '',
        base: 'space-y-4',
        collapsible: 'space-y-4',
        header: '',
        footer: '',
        actions: ''
      }
    }
  }
})

Changelog

No recent changes

WithPasswordToggle

A password input component with show/hide visibility toggle.

String

Mapping of afz.string() to various input controls and their configuration.