---
title: "Array"
description: "Element definition, metadata override and mapping of afz.array() to multi-value controls."
canonical_url: "https://nuxt.mhaibaraai.cn/en/docs/auto-form/array"
---
# Array

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

> [!NOTE]
> See: https://zod.dev/api#arrays
> 
> Use 
> 
> afz.array()
> 
>  to create an array field:

## ElementSchema

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

```ts
// 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

> [!NOTE]
> 
> Used to 
> 
> override the default control of array elements
> 
>  and configure metadata, while keeping the output type unchanged:

> [!TIP]
> 
> 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:
> 
> ```ts
> 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:
> 
> ```ts
> 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:
> 
> ```ts
> import MyArrayControl from './MyArrayControl.vue'
> 
> afz.array(afz.string(), {
>   component: MyArrayControl,
>   controlProps: { /* ... */ }
> })
> ```

## `InputTags`

> [!NOTE]
> See: https://ui.nuxt.com/docs/components/input-tags
> 
> InputTags component documentation

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

```vue [AutoFormFieldArrayInputTagsExample.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({
  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`

> [!NOTE]
> See: https://ui.nuxt.com/docs/components/checkbox-group
> 
> CheckboxGroup component documentation

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

```vue [AutoFormFieldArrayCheckboxGroupExample.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({
  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

> [!NOTE]
> See: https://ui.nuxt.com/docs/components/collapsible
> 
> Collapsible component documentation

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

```vue [AutoFormFieldArrayObjectExample.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({
  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>
```


## Sitemap

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