π° Wanna get paid the big bucks writing React? Take this quiz and get offers from top tech companies! π°
π React Final Form Arrays
Installation
npm install --save react-final-form-arrays react-final-form final-form final-form-arrays
or
yarn add react-final-form-arrays react-final-form final-form final-form-arrays
Usage
π React Final Form Arrays provides a way to render arrays in π React Final Form.
import { Form, Field } from 'react-final-form'
import arrayMutators from 'final-form-arrays'
import { FieldArray } from 'react-final-form-arrays'
const MyForm = () => (
<Form
onSubmit={onSubmit}
mutators={{
// potentially other mutators could be merged here
...arrayMutators
}}
validate={validate}
render={({ handleSubmit, pristine, invalid }) => (
<form onSubmit={handleSubmit}>
<FieldArray name="customers">
{({ fields }) => (
<div>
{fields.map((name, index) => (
<div key={name}>
<div>
<label>First Name</label>
<Field name={`${name}.firstName`} component="input" />
</div>
<div>
<label>Last Name</label>
<Field name={`${name}.lastName`} component="input" />
</div>
<button type="button" onClick={() => fields.remove(index)}>
Remove
</button>
</div>
))}
<button
type="button"
onClick={() => fields.push({ firstName: '', lastName: '' })}
>
Add
</button>
</div>
)}
</FieldArray>
</form>
)}
/>
)
Table of Contents
- Examples
- Rendering
- API
- Types
FieldArrayProps
children?: ((props: FieldArrayRenderProps) => React.Node) | React.Node
component?: React.ComponentType<FieldArrayRenderProps>
name: string
render?: (props: FieldArrayRenderProps) => React.Node
defaultValue?: any
initialValue?: any
isEqual?: (allPreviousValues: Array<any>, allNewValues: Array<any>) => boolean
subscription?: FieldSubscription
validate?: (value: ?any[], allValues: Object) => ?any
FieldArrayRenderProps
fields.forEach: (iterator: (name: string, index: number) => void) => void
fields.insert: (index: number, value: any) => void
fields.map: (iterator: (name: string, index: number) => any) => any[]
fields.move: (from: number, to: number) => void
fields.name: string
fields.pop: () => any
fields.push: (value: any) => void
fields.remove: (index: number) => any
fields.shift: () => any
fields.swap: (indexA: number, indexB: number) => void
fields.update: (index: number, value: any) => void
fields.unshift: (value: any) => void
meta.active?: boolean
meta.data: Object
meta.dirty?: boolean
meta.error?: any
meta.initial?: any
meta.invalid?: boolean
meta.pristine?: boolean
meta.submitError?: any
meta.submitFailed?: boolean
meta.submitSucceeded?: boolean
meta.touched?: boolean
meta.valid?: boolean
meta.visited?: boolean
Examples
Simple Example
Demostrates how to use <FieldArray/>
to render an array of inputs, as well as
use push
, pop
, and remove
mutations.
React Beautiful DnD Example
Demostrates how to integrate the simple example with react-beautiful-dnd
Rendering
There are three ways to tell <FieldArray/>
what to render:
Method | How it is rendered |
---|---|
component prop |
return React.createElement(this.props.component, props) |
render prop |
return this.props.render(props) |
a render function as children |
return this.props.children(props) |
API
The following can be imported from react-final-form-arrays
.
FieldArray : React.ComponentType<FieldArrayProps>
A component that takes FieldArrayProps
and renders an
array of fields
useFieldArray
The useFieldArray
hook takes two parameters, the first is the name of the field, and the second is an optional object that looks just like FieldArrayProps
, except without the name. It returns an object just like FieldArrayRenderProps
.
useFieldArray
is used interally inside FieldArray
.
version: string
The current used version of π React Final Form Arrays.
Types
FieldArrayProps
These are props that you pass to
<FieldArray/>
. You must
provide one of the ways to render: component
, render
, or children
.
children?: ((props: FieldArrayRenderProps) => React.Node) | React.Node
A render function that is given
FieldArrayRenderProps
, as well as any non-API props
passed into the <FieldArray/>
component.
component?: React.ComponentType<FieldArrayRenderProps>
A component that is given FieldArrayRenderProps
as
props, as well as any non-API props passed into the <FieldArray/>
component.
name: string
The name of your field array.
render?: (props: FieldArrayRenderProps) => React.Node
A render function that is given
FieldArrayRenderProps
, as well as any non-API props
passed into the <FieldArray/>
component.
defaultValue?: any
initialValue
!
Before using this prop, read and understand the π Final Form documentation on initialValue
and defaultValue
!
initialValue?: any
See the π Final Form docs on initialValue
isEqual?: (allPreviousValues: Array<any>, allNewValues: Array<any>) => boolean
A function that can be used to compare two arrays of values (before and after every change) and calculate pristine/dirty checks. Defaults to a function that will ===
check each element of the array.
subscription?: FieldSubscription
A
FieldSubscription
that selects of all the items of
FieldState
that you
wish to update for. If you don't pass a subscription
prop, it defaults to
all of FieldState
.
validate?: (value: ?any[], allValues: Object) => ?any
A function that takes the field value, and all the values of the form and
returns an error if the array value is invalid, or undefined
if the value is
valid.
FieldArrayRenderProps
These are the props that
<FieldArray/>
provides to
your render function or component. This object is divided into a fields
object
that mimics an iterable (e.g. it has map()
and forEach()
and length
), and
meta
data about the field array. Keep in mind that the values in meta
are
dependent on you having subscribed to them with the
subscription
prop
fields.forEach: (iterator: (name: string, index: number) => void) => void
Iterates through all of the names of the fields in the field array in bracket
format, e.g. foo[0]
, foo[1]
, foo[2]
.
fields.insert: (index: number, value: any) => void
A function to insert a value into any arbitrary index of the array.
fields.map: (iterator: (name: string, index: number) => any) => any[]
Iterates through all of the names of the fields in the field array in bracket
format, e.g. foo[0]
, foo[1]
, foo[2]
, and collects the results of the
iterator function. You will use this in almost every implementation.
fields.move: (from: number, to: number) => void
A function to move a value from one index to another. Useful for drag-and-drop reordering.
fields.name: string
The name of the field array.
fields.pop: () => any
A function to remove a value from the end of the array. The value will be returned.
fields.push: (value: any) => void
A function to add a value to the end of the array.
fields.remove: (index: number) => any
A function to remove a value from an arbitrary index of the array.
fields.shift: () => any
A function to remove a value from the beginning of the array. The value will be returned.
fields.swap: (indexA: number, indexB: number) => void
A function to swap two values in the array.
fields.update: (index: number, value: any) => void
Updates a value of the specified index of the array field.
fields.unshift: (value: any) => void
A function to add a value to the beginning of the array.
fields.value: any[]
The value of the array. Should be treated as readonly.
meta.active?: boolean
See the π Final Form docs on active
.
meta.data: Object
See the π Final Form docs on data
.
meta.dirty?: boolean
See the π Final Form docs on dirty
.
meta.error?: any
See the π Final Form docs on error
.
meta.initial?: any
See the π Final Form docs on initial
.
meta.invalid?: boolean
See the π Final Form docs on invalid
.
meta.pristine?: boolean
See the π Final Form docs on pristine
.
meta.submitError?: any
See the π Final Form docs on submitError
.
meta.submitFailed?: boolean
See the π Final Form docs on submitFailed
.
meta.submitSucceeded?: boolean
See the π Final Form docs on submitSucceeded
.
meta.touched?: boolean
See the π Final Form docs on touched
.
meta.valid?: boolean
See the π Final Form docs on valid
.