FieldArray

View source on GitHub

The FieldArray component is how you render an array of fields. It works a lot like Field. With Field, you give a name, referring to the location of the field in the Redux state, and a component to render the field, which is given the props to connect the field to the Redux state.

With FieldArray, you provide a name just like with Field, but the component you give to FieldArray will be given a set of props to query, update, and iterate through the field array.

Importing

var FieldArray = require('redux-form').FieldArray // ES5

import { FieldArray } from 'redux-form' // ES6

Props you can pass to FieldArray

name : String [required]

A string path, in dot-and-bracket notation, corresponding to a value in the form values. It may be as simple as 'firstName' or as complicated as contact.billing.address[2].phones[1].areaCode.

component : Component|Function [required]

A Component or stateless function to render the field array.

validate : (value, allValues, props) => error [optional]

Allows you to provide a field-level validation rule. The function will be given the current value of the array field, all the other form values, and any props passed to the form. If the array is valid, it should return undefined, if the array is invalid, it should return an error (usually, but not necessarily, a String).

warn : (value, allValues, props) => warning [optional]

Allows you to provide a field-level warning rule. The function will be given the current value of the array field, all the other form values, and any props passed to the form. If the array needs a warning, it should return the warning (usually, but not necessarily, a String). If the array does not need a warning, it should return undefined.

forwardRef : boolean [optional]

If true, the rendered component will be available with the getRenderedComponent() method. Defaults to false. Cannot be used if your component is a stateless function component.

props : object [optional]

Object with custom props to pass through the FieldArray component into a component provided to component prop. This props will be merged to props provided by FieldArray itself.

rerenderOnEveryChange : boolean [optional]

If true, the rendered component will be rerender after every change of Field inside FieldArray. This can reduce performance for large lists.

Instance API

The following properties and methods are available on an instance of a FieldArray component.

name : String

When nested in FormSection, returns the name prop prefixed with the FormSection name. Otherwise, returns the name prop that you passed in.

valid : boolean

true if this field passes validation, false otherwise.

getRenderedComponent()

Returns the instance of the rendered component. For this to work, you must provide a forwardRef prop, and your component must not be a stateless function component.

Props

These are props that FieldArray will pass to your wrapped component. All the props provided to your component by redux-form are divided into fields and meta objects.

Any additional props that you pass to your FieldArray will be in the root of the props object, alongside fields and meta.

Fields Props

The fields object is a "pseudo-array", in that it has many of the same properties and methods as a javascript Array, providing both reading and writing functionality.

fields.name : Function

When nested in FormSection, returns the name prop prefixed with the FormSection name. Otherwise, returns the name prop that you passed in.

fields.forEach(callback) : Function

A method to iterate over each value of the array. See the section on Iteration for more details.

fields.get(index) : Function

A method to get a single value from the array value.

fields.getAll() : Function

A method to get all the values in the array. If you are using ImmutableJS, it will be an ImmutableJS List.

fields.insert(index:Integer, value:Any) : Function

A function to insert a new value into the array at any arbitrary index.

fields.length : Number

The current length of the array.

fields.map(callback) : Function

A method to iterate over each value of the array. Returns an array of the results of each call to the callback. See the section on Iteration for more details.

fields.move(from:Integer, to:Integer) : Function

Moves an element from one index in the array to another.

This is not a mutator; it dispatches an action which updates the state in Redux, which will cause your component to rerender.

fields.pop() : Function

Removes an item from the end of the array. Returns the item removed.

This is not a mutator; it dispatches an action which updates the state in Redux, which will cause your component to rerender.

fields.push(value:Any) : Function

Adds a value to the end of the array. Returns nothing.

This is not a mutator; it dispatches an action which updates the state in Redux, which will cause your component to rerender.

fields.remove(index:Integer) : Function

Removes an item from the array at an arbitrary index. Returns nothing.

This is not a mutator; it dispatches an action which updates the state in Redux, which will cause your component to rerender.

fields.removeAll() : Function

Removes all the values from the array.

This is not a mutator; it dispatches an action which updates the state in Redux, which will cause your component to rerender.

fields.shift() : Function

Removes an item from beginning of the array. Returns the item removed.

This is not a mutator; it dispatches an action which updates the state in Redux, which will cause your component to rerender.

fields.splice(index:Number, removeNum:Number|null, value:Any) : Function

Performs an Array.splice operation on the given array in your form. Returns nothing.

This is not a mutator; it dispatches an action which updates the state in Redux, which will cause your component to rerender.

fields.swap(indexA:Integer, indexB:Integer) : Function

Swaps two items in the array at the given indexes. Returns nothing.

This is not a mutator; it dispatches an action which updates the state in Redux, which will cause your component to rerender.

fields.unshift(value:Any) : Function

Adds an item to the beginning of the array. Returns nothing.

This is not a mutator; it dispatches an action which updates the state in Redux, which will cause your component to rerender.

Meta Props

The props under the meta key are metadata about the state of this field array that redux-form is tracking for you.

meta.dirty : boolean

true if the any of the fields in the field array have changed from their initialized value. Opposite of pristine.

meta.error : String [optional]

The error for this field array if its value is not passing validation. Both synchronous, asynchronous, and submit validation errors will be reported here. Array-specific errors should be returned from the validation function as an _error key on the array.

meta.form : String

Name of your form provided to reduxForm() as the form config property.

meta.invalid : boolean

true if the field array value fails validation (has a validation error). Opposite of valid.

meta.pristine : boolean

true if the all of the fields in the field array are the same as their initialized value. Opposite of dirty.

meta.submitFailed : boolean

true if form submission has failed for any reason

meta.submitting : boolean

true if the field is currently being submitted

meta.valid : boolean

true if the field value passes validation (has no validation errors). Opposite of invalid.

meta.warning : String [optional]

The warning for this field array if its value is not passing warning validation. Array-specific errors should be returned from the validation function as an _warning key on the array.

Iteration

When you iterate through a field array with either forEach() or map(), your callback will be passed following parameters:

name : String

The name needed to give to Field to render the fields in this array. If the name prop you give to FieldArray is 'foo.bar', and there are three items in the array, your callback will be called three times, with 'foo.bar[0]', 'foo.bar[1]', and 'foo.bar[2]'.

index : Number

The index of the item in the array.

fields : Object

A reference to the fields prop to allow for the access to swap, remove, pop, etc., without requiring closure scoping.

const renderSubFields = (member, index, fields) => (
  <li key={index}>
    <button
      type="button"
      title="Remove Member"
      onClick={() => fields.remove(index)}
    />
    <h4>Member #{index + 1}</h4>
    <Field
      name={`${member}.firstName`}
      type="text"
      component={renderField}
      label="First Name"
    />
    <Field
      name={`${member}.lastName`}
      type="text"
      component={renderField}
      label="Last Name"
    />
  </li>
)
const renderMembers = ({ fields }) => (
  <ul>
    <button type="button" onClick={() => fields.push({})}>
      Add Member
    </button>
    {fields.map(renderSubFields)}
  </ul>
)