Field

The Field component is how you connect each individual input to the Redux store. There are three fundamental things that you need to understand in order to use Field correctly:

1. The name prop is required. It is 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.

2. The component prop is required. It may be a Component, a stateless function, or a factory, like those provided under React.DOM. See Usage section below. To learn about the props that will provided to whatever your component is, see the Props section below.

3. All other props will be passed along to the element generated by the component prop.

Importing

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

import { Field } from 'redux-form';  // ES6

Props you can pass to Field

component : Component|Function|factory [required]

A Component, stateless function, or ReactElement factory that will render the input. See the Usage section below for details.

defaultValue: any [optional]

A value to be used if the current value for this field is undefined in the Redux Store. Defaults to '' to ensure that the input is controlled.

Usage

Let's look at the three kinds of things that can be given to the component prop:

1. A component

This can be any component class that you have written or have imported from a third party library.

// MyCustomInput.js
import React, { Component } from 'react'

class MyCustomInput extends Component {
  render() {
    const { value, onChange } = this.props
    return (
      <div>
        <span>The current value is {value}.</span>
        <button type="button" onClick={() => onChange(value + 1)}>Inc</button>
        <button type="button" onClick={() => onChange(value - 1)}>Dec</button>
      </div>
    )
  }
}

Then, somewhere in your form...

import MyCustomInput from './MyCustomInput'

...

<Field component={MyCustomInput}/>

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 <Field>, as it gives you complete control over how the input 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.

<Field component={(props) => {
  return (
    <div class="input-row">
      <input type="text" {...props}/>
      {props.touched && props.error && <span className="error">{props.error}</span>}
    </div>
  )
}}/>

To learn what props will be passed to your stateless function, see the Props section below.

3. A factory

In React terminology, "a factory is simply a function that generates a ReactElement with a particular type property."

When it comes to forms, the most important built-in factories are:

• React.DOM.input
• React.DOM.select
• React.DOM.textarea

So all you really need to render an redux-form-connected text input is:

<Field component={React.DOM.input} type="text"/>

Remember the second rule above that all other props are passed to the element generated by component? So the type="text" prop will be given to the input.

Props

active : boolean

true if this field currently has focus. It will only work if you are passing onFocus to your input element.

checked : boolean [optional]

An alias for value only when value is a boolean. Provided for convenience of destructuring the whole field object into the props of a form element.

dirty : boolean

true if the field value has changed from its initialized value. Opposite of pristine.

error : String [optional]

The error for this field if its value is not passing validation. Both synchronous, asynchronous, and submit validation errors will be reported here.

invalid : boolean

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

name : String

The name of the field. It will be the same as the key in the fields Object, but useful if bundling up a field to send down to a specialized input component.

onBlur(eventOrValue) : Function

A function to call when the form field loses focus. It expects to either receive the React SyntheticEvent or the current value of the field.

onChange(eventOrValue) : Function

A function to call when the form field is changed. It expects to either receive the React SyntheticEvent or the new value of the field.

onDragStart(event) : Function

A function to call when the form field receives a dragStart event. Saves the field value in the event for giving the field it is dropped into.

onDrop(event) : Function

A function to call when the form field receives a drop event.

onFocus(event) : Function

A function to call when the form field receives focus.

onUpdate(eventOrValue) : Function

An alias for onChange. Provided for convenience of destructuring the whole field object into the props of a form element. Added to provide out-of-the-box support for Belle components' onUpdate API.

pristine : boolean

true if the field value is the same as its initialized value. Opposite of dirty.

touched : boolean

true if the field has been touched. By default this will be set when the field is blurred.

valid : boolean

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

value: any

The value of this form field. It will be a boolean for checkboxes, and a string for all other input types. If there is no value in the Redux state for this field, it will default to the defaultValue prop given to Field. If no such defaultValue is specified, it will be ''. This is to ensure that the input is controlled.

visited: boolean

true if this field has ever had focus. It will only work if you are passing onFocus to your input element.