Array

Element definition, metadata override and mapping of afz.array() to multi-value controls.

Use afz.array() to create an array field:

ElementSchema

Defines the type of array elements, determining the output type as T[]:

// String array
const schema1 = afz.array(afz.string())
// Output type: string[]

// Object array
const schema2 = afz.array(afz.object({
  name: afz.string(),
  age: afz.number()
}))
// Output type: { name: string, age: number }[]

Meta

Used to override the default control of array elements and configure metadata, while keeping the output type unchanged:

For object arrays (e.g. afz.array(afz.object({...}))), the system automatically renders using collapsible panels — no need to manually specify a control type.

Without specifying a control type, array elements use the default mapping:

afz.array(afz.string(), {
  label: 'Tag List',
  hint: 'Add multiple tags'
})
// string[] - elements use the input control by default

Override the default control of array elements via type, output type remains unchanged:

afz.array(afz.string(), {
  type: 'checkboxGroup',  // overrides the default input control for string
  controlProps: {
    items: ['reading', 'gaming', 'sports']
  }
})
// Output type is still: string[]
// but rendered as checkboxGroup (multi-select)

afz.string() would normally map to an input control. The type: 'checkboxGroup' in the second argument overrides this default mapping, changing it to a checkbox form.

Pass a custom component instance directly:

import MyArrayControl from './MyArrayControl.vue'

afz.array(afz.string(), {
  component: MyArrayControl,
  controlProps: { /* ... */ }
})

`InputTags`

InputTags component documentation

Tag input field, set type: 'inputTags', suitable for free-text tags:

<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({
  tags: afz.array(afz.string(), {
    type: 'inputTags'
  })
    .default(['tag1', 'tag2'])
    .meta({
      label: '标签输入',
      hint: '输入后按 Enter 添加标签'
    })
})

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

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

`CheckboxGroup`

CheckboxGroup component documentation

Checkbox group, set type: 'checkboxGroup', suitable for multi-selecting predefined options:

<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({
  notifications: afz.array(afz.string(), {
    type: 'checkboxGroup',
    controlProps: {
      items: [
        { label: '邮件', value: 'email' },
        { label: '短信', value: 'sms' },
        { label: '电话', value: 'phone' }
      ]
    }
  })
    .default(['email'])
    .meta({
      label: '复选框组',
      hint: '多选通知方式'
    })
})

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

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

Object Array

Collapsible component documentation

Object arrays are automatically rendered using collapsible panels, supporting add and delete items:

<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({
  experience: afz.array(
    afz.object({
      company: afz.string({
        controlProps: {
          placeholder: '公司名称'
        }
      }).min(1).meta({ label: '公司' }),
      position: afz.string({
        controlProps: {
          placeholder: '职位'
        }
      }).min(1).meta({ label: '职位' }),
      years: afz.number({
        controlProps: {
          placeholder: '工作年限'
        }
      }).int().min(0).max(50).meta({ label: '年限', hint: '工作年数' })
    }).meta({ label: '工作经历' })
  ).default([{
    company: '示例公司',
    position: '软件工程师',
    years: 3
  }]).meta({
    label: '工作经历列表',
    collapsible: { defaultOpen: true }
  })
})

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

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

Enum

Configuration methods for afz.enum() and its mapping to selection controls.

Object

Invocation methods, nested structures and extra key handling strategies for afz.object().