underdog-react-redux-form

Library for easily creating forms with React and Redux. Inspired by react-redux-form.

Quickstart

import {
  combineReducers,
  createStore
} from 'redux';
import {Provider} from 'react-redux';
import React from 'react';

import {
  Control,
  FieldError,
  Form,
  createFormReducer
} from 'underdog-react-redux-form';

// Create a reducer for your form
const validate = (value) => value.trim().length > 0;
const exampleForm = createFormReducer('exampleForm', {
  fields: {
    first: {
      initialValue: 'Bark',
      validate
    },
    last: {
      initialValue: 'Ruffalo',
      validate
    }
  }
});

const reducer = combineReducers({
  forms: {
    exampleForm
  }
});
const store = createStore(reducer);

// Create a form
const Application = () => (
  <Provider store={store}>
    <Form form="forms.exampleForm">
      {
        (formState, updateForm) => (
          <div>
            <label>
              <span className="block-label">First name</span>
              <Control.Text field="first" />
              <FieldError field="first">
                <strong>This field is invalid!</strong>
              </FieldError>
            </label>
            <label>
              <span className="block-label">Last name</span>
              <Control.Text field="last" />
              <FieldError field="last">
                <strong>This field is invalid!</strong>
              </FieldError>
            </label>
          </div>
        );
      }
    </Form>
  </Provider>
);

Check out example/app.js for a more thorough example.

Getting started

Installation

npm install underdog-react-redux-form underdog-pup react redux react-redux

Creating a form

Creating a form reducer

Before you can create a form, you're going to have to create a reducer that manages the state of your form.

You can create a form reducer with the createFormReducer function. This function accepts two arguments: a unique identifier for your form and a configuration object for the initial values for your form.

Example form reducer.

The initial state for the form reducer will look something like this:

{
  "name": "formName",

  // Indicates if the form has been submitted at least once.
  "didSubmit": false,

  // Indicates if the form's current values are different from its configured value.
  "isClean": true,

  // Indicates if all of the form's fields are considered "valid".
  "isValid": false,

  // Indicates if errors should be shown to the user.
  "showErrors": false,

  // Indicates if a user has interacted with a form field.
  "touched": false,

  // The current state of the form's fields.
  "fields": {
    "fieldName": {
      // The initial value for this field.
      "initialValue": "",

      // Boolean that indicates if the current value of this field is different from its initial value.
      "isClean": true,

      // Indicates if this field is valid.
      "isValid": false,

      // Indicates if the user has interacted with this field.
      "touched": false,

      // The current value of this form field.
      "value": ""
    }
  }
}

Updating a form's state

If you are using the <Form /> component with any of the included controls, the form will automatically be updated as the value for the control is updated:

import {
  Control,
  Form
} from 'underdog-react-redux';

<Form form="path.to.form.reducer.in.store.state">
  {
    (formState, updateForm) => (
      <div>
        <Control.Text field="fieldName" />
        <Control.Select field="otherFieldName">
          <option value="">Select an option</option>
          <option value="option_1">Option 1</option>
          <option value="option_2">Option 2</option>
        </Control.Select>
      </div>
    )
  }
</Form>

If you are using a custom control, you can update a form with the updateForm function that is provided to the <Form />'s children:

<Form form="path.to.form.reducer.in.store.state">
  {
    (formState, updateForm) => (
      <div>
        <input
          type="text"
          value={formState.fields.fieldName.value}
          onChange={(event) => {
            updateForm('fieldName', event.target.value);
          }}>
      </div>
    )
  }
</Form>

You can also update a form's state manually with the updateForm action creator:

import {
  updateForm
} from 'underdog-react-redux';

// Where-ever dispatch is available
dispatch(
  updateForm('formName', 'fieldName', 'Some new value')
);