---
title: "Quickstart"
description: "Learn the core design philosophy and basic usage of AutoForm."
canonical_url: "https://nuxt.mhaibaraai.cn/en/docs/auto-form/quickstart"
---
# 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.

> [!NOTE]
> 
> **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:

```vue [AutoFormBasicExample.vue]
<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

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

### Slots

```ts
/**
 * Slots for the MAutoForm component
 */
interface MAutoFormSlots {
  header(): any;
  footer(): any;
  submit(): any;
  field-label(): any;
  field-hint(): any;
  field-description(): any;
  field-help(): any;
  field-error(): any;
  field-default(): any;
}
```

> [!NOTE]
> 
> 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

```ts
/**
 * Emitted events for the MAutoForm component
 */
interface MAutoFormEmits {
  error: (payload: [FormErrorEvent]) => void;
}
```

### Expose

You can access the typed component instance via [`useTemplateRef`](https://vuejs.org/api/composition-api-helpers.html#usetemplateref).

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

> [!TIP]
> See: https://ui.nuxt.com/docs/components/form#expose
> 
> 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

<component-theme slug="AutoForm">



</component-theme>

## Changelog

See commit history for [src/runtime/components/Quickstart.vue](https://github.com/mhaibaraai/movk-nuxt/commits/main/src/runtime/components/Quickstart.vue).


## Sitemap

See the full [sitemap](https://nuxt.mhaibaraai.cn/sitemap.md) for all pages.