ArrayField

Render array items with stable identities and mutation methods that keep values, state, and errors aligned.

ArrayField renders no element. It exposes an array field instance through its default slot. Create the instance with form.arrayField(path).

Usage

<template>
  <ArrayField
    v-slot="{ arrayField }"
    :array-field="form.arrayField('tags')"
  >
    <div
      v-for="item in arrayField.items"
      :key="item.id"
    >
      <Field
        v-slot="{ field }"
        :field="item"
      >
        <input
          v-model="field.model"
          v-bind="field.events"
          aria-label="Tag"
        >

        <FieldError :errors="field" />
      </Field>

      <button
        type="button"
        @click="arrayField.remove(item.index)"
      >
        Remove
      </button>
    </div>

    <FieldError :errors="arrayField" />

    <button
      type="button"
      @click="arrayField.append('')"
    >
      Add tag
    </button>
  </ArrayField>
</template>

Use item.id as the Vue key. index and path change with position. id does not.

Props

array-field

ArrayFieldInstance<TItem> required

The array field created by form.arrayField(path).

Slot props

The default slot receives arrayField. Extra attributes passed to ArrayField arrive as additional slot props.

Field members

An array field has the regular field members model, events, path, id, errors, isDirty, isTouched, isValid, isValidating, and validate(), with these array-specific semantics:

errors and isValid refer to issues at the array's own path, such as a minimum item count.
isDirty compares the whole array, so nested edits count.
isValidating includes validation of fields nested in its items.

Array members

Member	Description
`items`	Item instances, in current order.
`append(value)`	Add an item at the end.
`prepend(value)`	Add an item at the start.
`insert(index, value)`	Insert at an index. Clamped to `0..length`.
`remove(index)`	Remove an item and its state. Ignored if out of range.
`move(from, to)`	Move an item. Ignored if either index is out of range.
`swap(indexA, indexB)`	Swap two items. Ignored if either index is out of range.
`update(index, value)`	Replace an item in place. Keeps its id and touched state, drops its old errors. Ignored if out of range.

Item members

Each entry in items is a field for the item's value. It has every field member listed above, plus:

Member	Description
`index`	The item's current position.
`field(path, config?)`	A field nested in the item, with a path relative to the item. Cached, and follows the item when it moves.
`arrayField(path, config?)`	An array field nested in the item.

Behavior

Values passed to append, prepend, insert, and update are deep-cloned.
Every mutation counts as a change event on the array field. By default it re-validates the array's own path.
Errors inside the array are re-pointed to follow their items on every mutation.
Reset creates fresh item ids.
A removed item, and anything created from it, becomes inert: mutations do nothing.

Change the array only through these methods. Direct mutation such as form.values.tags.push('x') bypasses identity and error tracking. See Array fields.

Field

Expose a field instance to a renderless slot to bind its model and events to any control.

FieldError

Display the first validation message from a field, an array field, or an issue list.