useFieldArray 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:

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

`fields: Ref<FieldArrayEntry<TValue>[]>`

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

tsinterface 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');

`push(item: any)`

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: '' });
};

`prepend(item: any)`

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: '' });
};

`remove(idx: number)`

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);
};

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

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);
};

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

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: '' });
};

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

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: '' });
};

`replace(items: any[])`

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' }]);
};

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

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);
};

Edit This Page on GitHub

Sponsor