Learn about our RFC process, Open RFC meetings & more.Join in the discussion! »

redux-formo

3.0.0-preview.21 • Public • Published

redux-formo

Build Status

An alternate forms framework for Redux+React.

Why not redux-form?

  • validate on blur, not change
  • validate individual fields, not the whole form

Installation

npm install --save redux-formo

Usage

createStore.js

import {createStore, applyMiddleware, combineReducers} from 'redux';
import thunk from 'redux-thunk';
import {reducer} from 'redux-formo';
 
const createStoreWithMiddleware = applyMiddleware(thunk)(createStore);
export createStoreWithMiddleware(combineReducers({
  formreducer
}));

App.jsx

import React from 'react';
import form from 'redux-formo';
import filter from './filter';
import validate from './validate';
import submit from './submit';
 
class App extends React.Component {
 
  render() {
    const {
      valid,
      submitting,
      submitted,
      error,
      fields: {name, phone},
      onSubmit 
    } = this.props;
 
    return (
      <form onSubmit={onSubmit(submit)}>
 
        {error && <p>{error}</p>}
 
        <div>
          <label>
            Name: <input {...name}/>
          </label>
          {name.error && <p>{name.error}</p>}
        </div>
 
        <br/>
 
        <div>
          <label>
            Phone: <input {...phone}/>
          </label>
          {phone.error && <p>{phone.error}</p>}
        </div>
 
        <br/>
 
        <input
          type="submit"
          value={submitted ? 'Saved.' : (submitting ? 'Saving...' : 'Save')}
          disabled={submitting || submitted}
        />
 
      </form>
    );
  }
 
}
 
export default form({
  name: 'personal-details',
  fields: ['name', 'phone'],
  filter, validate
})(App);

Methods

form(config : Object, [mapStateToProps], [mapDispatchToProps], [mergeProps], [options])(Component)

Decorate a React Component, connecting the Redux form state and providing helper methods for handling form and field events e.g. onSubmit(), onChange(), onBlur().

config : Object

.name : String

The name of the form.

Required.

.fields : Array

The names of the fields.

Required.

.defaults : Array

The default values of the fields.

Optional.

.filter({field, value, values}) : String | Promise

A function used to filter a field value.

Optional.

Parameters:

  • field - The name of the field being filtered
  • value - The value of the field being filtered
  • values - All the valid field values

Returns:

The filtered value.

.validate({field, value, values}) : Boolean | String | Promise

A function used to validate a field value.

Optional.

Parameters:

  • field - The name of the field being filtered
  • value - The value of the field being filtered
  • values - All the valid field values

Returns:

True if the value is valid. An error string if the value is not valid.

.submit({dispatch, values}) : void | FSA | Promise

A function used to submit the field values.

Optional.

Parameters:

  • dispatch - The dispatch method
  • values - All the valid field values

Returns:

Void, a Flux Standard Action or a Promise.

  • if an error is thrown, the error property will be set and the form will not be marked as submitted
  • if a FSA error is returned, the error property will be set and the form will not be marked as submitted
  • if a promise is returned:
    • if the promise is rejected, the error property will be set and the form will not be marked as submitted
    • if the promise resolves a FSA error, the error property will be set and the form will not be marked as submitted
  • in all other cases, the form will be marked as submitted
.filterOnChange : Boolean

Whether a field should be filtered when the field value changes.

Optional. Defaults to false.

.validateOnChange : Boolean

Whether a field should be validated when the field value changes.

Optional. Defaults to false.

.filterOnBlur : Boolean

Whether a field should be filtered when the field loses focus.

Optional. Defaults to true.

.validateOnBlur : Boolean

Whether a field should be validated when the field loses focus.

Optional. Defaults to true.

.filterOnSubmit : Boolean

Whether a field should be filtered when the form is submitted.

Optional. Defaults to true.

.validateOnSubmit : Boolean

Whether a field should be validated when the form is submitted.

Optional. Defaults to true.

.stateKey : String

The name of the property where the form reducer is mounted on the state.

Optional. Defaults to form.

.propKey : String

The name of the property where the form state is passed in props to the react component.

Optional. Defaults to none.

.destroyOnUnmount : Boolean

Whether the form state is destroyed when the component is unmounted.

Optional. Defaults to true.

mapStateToProps(state, ownProps) : Object

See the react-redux documentation on the connect function.

Optional.

mapDispatchToProps(dispatch, ownProps) : Object

See the react-redux documentation on the connect function.

Optional.

mergeProps(stateProps, dispatchProps, ownProps) : Object

See the react-redux documentation on the connect function.

Optional.

options : Object

See the react-redux documentation on the connect function.

Optional.

reducer.plugin(reducers : Object) : Function

Returns a new reducer that will return a new state as a result of chaining the result of the original reducer and then the result of the dictionary of reducers.

Props

The decorated component will receive the following props:

  • filtering : bool - whether one or more values are currently being filtered
  • validating : bool - whether one or more values are currently being validated
  • submitting : bool - whether the form is currently being submitted
  • submitted : bool - whether the form has been submitted one or more times
  • error : string|undefined - the error message from the last failed submission
  • valid : bool - whether all the field values are valid
  • fields : object
    • <name> - object
      • name - string - the name of the field
      • active - bool - whether the field is currently active (i.e. focussed)
      • filtering - bool - whether the filter function is currently running on the field
      • filtered - bool - whether the field has been filtered one or more times since the store was created
      • validating - bool - whether the validation function is currently running on the field
      • validated - bool - whether the field has been validated one or more times since the store was created
      • error - string|undefined - the error message from the previous validation
      • valid - bool - whether the current value is valid
      • lastValidValue *|undefined - the the last successfully validated value
      • value - *|undefined - the current value
      • checked - bool|undefined - true when the value is true, false when the value is false
      • defaultValue - *|undefined - the defaultValue
      • defaultChecked - bool|undefined - true when the value is true, false when the value is false

CHANGE LOG

v3.0.0

  • breaking change: filter and validate actions no longer take the value(s) as parameters, but get the value(s) from the state instead
  • breaking change: afterValidate() no longer receives the last valid values

v2.0.1

  • fix: mapDispatchToProps always returns dispatch so that redux-formo continues to work when mapDispatchToProps is used

v2.0.0

  • breaking change: Destroying the form state when the component is unmounted - set .destroyOnUmount to false to restore the previous behaviour
  • breaking change: In order to enable the submit() function to access the component props, the submit() function is now passed as a parameter to the onSubmit() handler
  • breaking change: Improved how initial values are set and enabled the initial values to be set from the redux state
  • breaking change: Stopped coercing values to empty strings
  • breaking change: Renamed config.form to config.name
  • breaking change: Renamed config.formPropKey to config.propKey
  • breaking change: Renamed config.formStateKey to config.stateKey
  • breaking change: Renamed props.fields[fieldName].validValue to props.fields[fieldName].lastValidValue
  • refactored internals

v1.3.0

  • added an API for hooking into the reducer

v1.2.0

  • added handling of checkbox inputs and custom inputs in the onChange event

v1.1.0

  • added .filterOnChange and .validateOnChange properties to allow configuration of whether validation occurs each time the user changes the value of a field
  • An un-documented function, afterValidate(), is called after validation of each is complete - may change in the future!
  • refactored decorate.jsx to make it more testable

v1.0.0

  • breaking change: The name of the package has changed from the-other-redux-form to redux-formo
  • breaking change: The form state is now merged into the root of your component's props unless configured by formPropKey
  • breaking change: The filter, validate and submit methods now receive an object instead of numerous parameters
  • possible breaking change: The filter, validate and submit methods receive an object containing most recent valid values instead of the current values
  • possible breaking change: For compatibility with packages that adhere to Flux Standard Action (e.g. redux-promise), if the submit method returns/resolves a FSA error the form submission will be assumed to have failed
  • The filter and validate methods can return a promise, like the submit method, in order to perform asynchronous filtration and validation
  • Added unit tests for most methods

Design decisions

  • like redux-form but unlike react-redux-form, use a different subset of the state to store values (let the user choose when they want to sync/update their model with the data on the form)

THANKS

Much of this package is inspired by the work of @erikras on redux-form. Much thanks!

Install

npm i redux-formo

DownloadsWeekly Downloads

75

Version

3.0.0-preview.21

License

MIT

Last publish

Collaborators

  • avatar