immutable-form
Getting Started
Install the package
yarn install immutable-form
To install the latest development version
yarn install immutable-form@devel
Documentation
Overview
The intent of this package is to provide a simple to use implementation of managing form state for React components, streamlining common requirements such as validation, error handling, data fetching and submission.
This package consists of three modules, Form
, FormCollection
, and connectForm
.
Form
is a class which provides an API to read and write form's state. The state is stored within a Immutable object which in turn is resides within a Redux store.
FormCollection
holds references to all existing forms. This is useful if you're trying to access form values across different components.
connectForm
is a React higher order component which passes down form
and field
props into your components and re-renders on the form's state changes.
Creating a form
; // This is just a mock promise for the sake of this code example, in reality this promise should originate from performing an async call to some api.const createUserPromise = Promise; // These props could be anything. This function returns a new Form as a function of props.const mapPropsToForm = hasUsername hasPassword 'userForm' fields: username: hasUsername || undefined && // All these fields are optional, value: 'some value' // Set an initial value // Any validation function in validate which returns a string will cause a validation error. Each validation function receives the field value and the form reference as parameters. validate: usernamelength === 0 && 'Username cannot be be empty' password: hasPassword || undefined && validate: passwordlength < 6 && 'Password must be longer than 6 characters' // Send a request to the server// If the promise resolves, do something with the results// If the promise is rejected, do something.; const UserForm = // fields is a an Immutable Map fields // This is the `Form` object, you can use it do extra actions such submitting the form. form <div> <input type="text" onChange= form value=fields /> fields <input type="text" onChange= form value=fields /> fields <button onClick= form /> </div>; mapPropsToFormUserForm;
Loading async data into the form
; // This is just a mock promise for the sake of this code example, in reality this promise should originate from performing an async call to some api.const loadFormPromise = Promise; // Note that the below example does not use a function to create a new Form. See above for that use case.const userForm = 'userForm' fields: username: validate: usernamelength === 0 && 'Username cannot be be empty' password: validate: passwordlength < 6 && 'Password must be longer than 6 characters' ;
If using connectForm
the load promise will be called automatically in the component's lifecycle. To trigger a manual load, call form.load()
.
Creating a Form with extra options
; const Form = 'form' {} logger: true // Will enable redux-logger (false by default) addToFormCollection: true // Refrains from adding a reference to FormCollection, (true by default);