- Redux Form
- API
Fields
Fields
The
Fields component is similar to the
Field component, but operates on multiple
fields at a time. Rather than passing a single
name prop,
Fields takes an array of names in
the
names prop.
IMPORTANT: Connecting to multiple fields should be used sparingly, as it will require the
entire
<Fields> component to re-render every time any of the fields it is connected to change.
This can be a performance bottleneck. Unless you absolutely need to, you should connect to your
fields individually with
<Field>.
Importing
var Fields = require('redux-form').Fields; // ES5
import { Fields } from 'redux-form'; // ES6
Props you can pass to
Fields
names : Array<String> [required]
An array of strings (or the pseudo-array
fields provided by
FieldArray),
in dot-and-bracket notation, corresponding to form values. They may
be as simple as
'firstName' or as complicated as
contact.billing.address[2].phones[1].areaCode. See the Usage section below for details.
component : Component|Function [required]
A
Component or stateless function that will be given all the props necessary to render the
field inputs. See the Usage section below for details.
format : (value, name) => formattedValue [optional]
Formats the value from the Redux store to be displayed in the field input. Common use cases are
to format
Numbers into currencies or
Dates into a localized date format.
format is called with the field
value and
name as arguments and should return the
new formatted value to be displayed in the field input.
To respect React 15 input behavior there is
defaultFormat = value => value == null ? '' : value internally used. To disable that you can pass
null as
format prop.
props : object [optional]
Object with custom props to pass through the
Fields component into a component provided
to
component prop. This props will be merged to props provided by
Fields itself. This may be
useful if you are using TypeScript. This construct is completely optional; the primary way of
passing props along to your
component is to give them directly to the
Fields component, but
if, for whatever reason, you prefer to bundle them into a separate object, you may do so by
passing them into
props.
parse : (value, name) => parsedValue [optional]
Parses the value given from the field input component to the type that you want stored in the
Redux store. Common use cases are to parse currencies into
Numbers into currencies or
localized date formats into
Dates.
parse is called with the field
value and
name as arguments and should return the new
parsed value to be stored in the Redux store.
withRef : 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.
Usage
The
component prop will be passed to
React.createElement(),
which accepts one of two possible things:
1. A component
This can be any component class that you have written or have imported from a third party library.
To learn what props will be passed to your component, see the Props section below.
2. A stateless function
This is the most flexible way to use
<Fields>, as it gives you complete control over how the
inputs is rendered. It is especially useful for displaying validation errors. It will also be the
most familiar to people migrating from previous versions of
redux-form. You must define the
stateless function outside of your
render() method, or else it will be recreated on every
render and will force the
Fields to rerender because its
component prop will be different.
If you are defining your stateless function inside of
render(), it will not only be slower, but
your input will lose focus whenever the entire form component rerenders.
// outside your render() method const renderFields = (fields) => ( <div> <div className="input-row"> <input {...fields.firstName.input} {fields.firstName.meta.touched && fields.firstName.meta.error && <span className="error">{fields.firstName.meta.error}</span>} </div> <div className="input-row"> <input {...fields.lastName.input} {fields.lastName.meta.touched && fields.lastName.meta.error && <span className="error">{fields.lastName.meta.error}</span>} </div> </div> ) // inside your render() method <Fields names={[ 'firstName', 'lastName' ]} component={renderFields}/>
To learn what props will be passed to your stateless function, see the Props section below.
Instance API
The following properties and methods are available on an instance of a
Field component.
dirty : boolean
trueif the current value of any of the fields is different from the initialized value,
falseotherwise.
names : Array<String>
When nested in
FormSection, returns the
namesprop prefixed with the
FormSectionname. Otherwise, returns a copy of the
namesprop that you passed in.
pristine : boolean
trueif the all of the current values are the same as the initialized values,
falseotherwise.
values : any
The current values of the fields. If they are nested, the values will duplicate the structure. For example, if your
namesare
[ 'name.first', 'name.last', 'email' ], the
valueswill be
{ name: { first: 'John', last: 'Smith' }, email: '[email protected]' }
getRenderedComponent()
Returns the instance of the rendered component. For this to work, you must provide a
withRefprop, and your component must not be a stateless function component.
####
Props
The props that
Fields will pass to your component are the same
input and
meta structures
that
Field generates, except that
they are broken up into the structure of the fields you gave as
names.
Any additional props that you pass to
Field will be included at the root of the props structure
given to your component
For example, if the fields you gave are...
...the props given to your component would be of the structure:...the props given to your component would be of the structure:
x <Fields names={[ 'name', 'email', 'address.street', 'address.city', 'address.postalCode' ]} component={MyMultiFieldComponent}
x { name: { input: { ... }, meta: { ... } }, email: { input: { ... }, meta: { ... } }, address: { street: { input: { ... }, meta: { ... } }, city: { input: { ... }, meta: { ... } }, postalCode: { input: { ... }, meta: { ... } } }, anotherCustomProp: 'Some other information' }