---
layout: ../../layouts/PageLayout.astro
title: FieldArray
description: API reference for the Field Array component
menuTitle: '<FieldArray />'
order: 4
---

import DocTip from '@/components/DocTip.vue';
import DocBadge from '@/components/DocBadge.vue';
import CodeTitle from '@/components/CodeTitle.vue';

# FieldArray <DocBadge title="v4.5" />

<DocTip title="Form Context" type="warn">

The `<FieldArray />` component requires being used inside a `Form` component or a `useForm` to be called at its parent tree.

</DocTip>

The `<FieldArray />` component is used to manage repeatable array fields. It is a renderless component, meaning it doesn't render anything of its own.

```vue
<template>
  <Form @submit="onSubmit" :initial-values="initialValues">
    <FieldArray name="links" v-slot="{ fields, push, remove }">
      <div v-for="(field, idx) in fields" :key="field.key">
        <Field :name="`links[${idx}].url`" type="url" />

        <button type="button" @click="remove(idx)">Remove</button>
      </div>

      <button type="button" @click="push({ id: Date.now(), name: '', url: '' })">Add</button>
    </FieldArray>

    <button>Submit</button>
  </Form>
</template>

<script setup>
// you can set initial values for those array fields
const initialValues = {
  links: [{ id: 1, url: 'https://github.com/logaretm' }],
};

function onSubmit(values) {
  alert(JSON.stringify(values, null, 2));
}
</script>
```

## API Reference

### Props

| Prop        | Type     | Required/Default | Description                            |
| :---------- | :------- | :--------------- | :------------------------------------- |
| `arrayPath` | `string` | Yes              | The form array path you wish to manage |

### Slots

#### default

The default slot gives you access to the following props:

<CodeTitle level="4">

`fields: FieldArrayEntry<TValue>`

</CodeTitle>

This is a **read-only** version of your array items, wrapped inside a `FieldArrayEntry` object which has the following interface:

```ts
interface FieldEntry<TValue = unknown> {
  // The actual value of the item, this is what exists in the form values
  value: TValue;
  // a value you can use as a key for iteration, automatically generated.
  key: string | number;
  // true if this is the first array item
  isFirst: boolean;
  // true if this is the last array item
  isLast: boolean;
}
```

<CodeTitle level="4">

`push(item: any)`

</CodeTitle>

Adds an item to the end of the array.

<CodeTitle level="4">

`prepend(item: any)`

</CodeTitle>

Adds an item to the start of the array.

<CodeTitle level="4">

`remove(idx: number)`

</CodeTitle>

Removes the item at the specified index from the array if it exists.

<CodeTitle level="4">

`swap(idxA: number, idxB: number)`

</CodeTitle>

Swaps the items at the given indexes with each other. Both indexes must exist in the array or it won't have an effect.

<CodeTitle level="4">

`insert(idx: number, item: any)`

</CodeTitle>

Adds an item at the specified index. If the specified index will place the item out of bounds (i.e: larger than length) the operation will be ignored, you still can add items as the last item of the array.

<CodeTitle level="4">

`update(idx: number, value: any)`

</CodeTitle>

Updates the value at the specified index, note that it doesn't merge the values if they are objects. If the specified index is outside the array boundary the operation will be ignored.

<CodeTitle level="4">

`replace(items: any[])`

</CodeTitle>

Replaces the entire array of fields.

<CodeTitle level="4">

`move(oldIdx: number, newIdx: number)`

</CodeTitle>

Moves an array item to a different position within the array. If one of the indices is outside of the array boundaries the operation will be ignored.
