---
layout: ../../layouts/PageLayout.astro
title: useFieldArray
description: API reference for the useFieldArray composition API function
menuTitle: useFieldArray()
order: 7
---

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

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

`useFieldArray` is a custom composition API function that allows you to manage repeatable fields and forms entries and provides common operation helpers.

Basic usage:

```vue
<template>
  <form @submit="onSubmit" novalidate>
    <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({ url: '' })">Add</button>

    <button>Submit</button>
  </form>
</template>

<script setup>
import { Field, useForm, useFieldArray } from 'vee-validate';

const { handleSubmit } = useForm({
  initialValues: {
    links: [{ id: 1, url: 'https://github.com/logaretm' }],
  },
});

const { remove, push, fields } = useFieldArray('links');
const onSubmit = handleSubmit(values => {
  console.log(JSON.stringify(values, null, 2));
});
</script>
```

## API Reference

The full signature of the `useFieldArray` function looks like this:

```ts
interface FieldEntry<TValue = unknown> {
  value: Ref<TValue>;
  key: string | number;
  isFirst: boolean;
  isLast: boolean;
}

interface FieldArrayContext<TValue = unknown> {
  fields: Ref<FieldEntry<TValue>[]>;
  remove(idx: number): void;
  replace(newArray: TValue[]): void;
  update(idx: number, value: TValue): void;
  push(value: TValue): void;
  swap(indexA: number, indexB: number): void;
  insert(idx: number, value: TValue): void;
  prepend(value: TValue): void;
  move(oldIdx: number, newIdx: number): void;
}

function useFieldArray: (arrayPath: string): FieldArrayContext;
```

### Composable API

The following sections documents each available property on the `useFieldArray` composable.

<CodeTitle level="4">

`fields: Ref<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 as readonly, 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;
}
```

```js
// call composable in component setup to get readable version of links array
const { fields } = useFieldArray('links');
```

<CodeTitle level="4">

`push(item: any)`

</CodeTitle>

Adds an item to the end of the array.

```js
// get push function from composable in component setup
const { push } = useFieldArray('links');

// call push function within custom function
const myPushFunction = () => {
  // adds a new item to the array
  push({ url: '' });
};
```

<CodeTitle level="4">

`prepend(item: any)`

</CodeTitle>

Adds an item to the start of the array.

```js
// get prepend function from composable in component setup
const { prepend } = useFieldArray('links');

// call prepend function within custom function
const myPrependFunction = () => {
  // adds a new item to the array
  prepend({ url: '' });
};
```

<CodeTitle level="4">

`remove(idx: number)`

</CodeTitle>

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

```js
// get remove function from composable in component setup
const { remove } = useFieldArray('links');

// call remove function within custom function
const myRemoveFunction = () => {
  // removes the second item from the array
  remove(1);
};
```

<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.

```js
// get swap function from composable in component setup
const { swap } = useFieldArray('links');

// call swap function within custom function
const mySwapFunction = () => {
  // Swaps the 4th item with the 5th
  swap(3, 4);
};
```

<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.

```js
// get insert function from composable in component setup
const { insert } = useFieldArray('links');

// call insert function within custom function
const myInsertFunction = () => {
  // inserts a new item to the array at the second index
  insert(1, { url: '' });
};
```

<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.

```js
// get update function from composable in component setup
const { update } = useFieldArray('links');

// call update function within custom function
const myUpdateFunction = () => {
  // updates the 2nd item value
  update(1, { url: '' });
};
```

<CodeTitle level="4">

`replace(items: any[])`

</CodeTitle>

Replaces the entire array of fields.

```js
// get replace function from composable in component setup
const { replace } = useFieldArray('links');

// call replace function within custom function
const myReplaceFunction = () => {
  // replace the entire array with these items
  replace([{ url: 'https://google.com' }, { url: 'https://vuejs.org' }]);
};
```

<CodeTitle level="4">

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

</CodeTitle>

Moves an array item to a different position within the array.

```js
// get move function from composable in component setup
const { move } = useFieldArray('links');

// call move function within custom function
const myMoveFunction = () => {
  // move array item to a different position
  move(2, 1);
};
```
