yarfl v0.1.1
Yet Another Redux Forms Library
Manage form state in React/Redux applications with reactive updates and field level validation. Heavily inspired by MobX React Form
Warning: experimental, not ready for production
Features
- Easy and JSON-serializable configuration.
- Reactive updates with input binding.
- Reactive validation with error messages.
- Supports both sync and async validation.
- Array fields.
- Nested fields.
- Easily integrated with component libraries (Material Ui, React Widgets, React Select, etc).
- Adheres to functional and immutable design principles.
- Written in Typescript.
Documentation
See the complete documentation here
Demo
There is a working live demo of this library's implementation here with accompanying source code.
Why?
Neither Redux Form nor React Redux Form (the two most popular React/Redux form libraries) provide an easy way of creating serializable form configurations. Furthermore, both libraries require the use of their own form and/or input components leading to unnecessary complexity. This library attempts to solve the first issue by dynamically creating a reducer function from serializable configurations and the second by exposing an API that does not require the need for special React components. The benefit is that more of the forms' functionality can be abstracted to the configuration rather than having to create individual form/field components.
Getting started
From the getting started section of the documentation.
Install dependencies (
redux
,react
,react-redux
,redux-thunk
are peer dependencies):yarn add redux react react-redux redux-thunk yarfl
Define a config object with a
fields
property describing what fields should be part of the Redux state and how they should be validated. Therules
string describes which rules from validatorjs the field should be validated against (optional).//config.js export const myFormConfig = { name: 'myForm', fields: { name: { rules: 'required' }, email: { rules: 'required|email' }, age: { rules: 'required|min:18' } } }
Create a reducer, initial state and a connector by passing the
config
object to theinit
function and then simply create the Redux store as you normally would:// store.js import { init } from 'yarfl'; import { createStore, applyMiddleware } from 'redux'; import thunk from 'redux-thunk'; import { myFormConfig } from './config' // create a reducer, initial state and a connector const { reducer, initialState, connect } = init(myFormConfig); // redux-thunk is a peer dependency of yarfl const enhancers = applyMiddleware(thunk) const store = createStore(reducer, initialState, enhancers); export { store, connect }
Set up the
Provider
as you normally would with React Redux. To connect a React component with the store from the previous step use theconnect
method that we created withinit
in step three. Thisconnect
method doesn't requiremapStateToProps
ormapDispatchToProps
arguments, this is taken care of by Yarfl automatically. Just pass the React component as its first and only argument.// App.js import React from 'react'; import { Provider } from 'react-redux'; import { store } from './store.js' import MyFormComponent from './MyFormComponent.js'; class App extends React.Component { render() { return ( <Provider store={store}> <MyFormComponent /> </Provider> ) } }
// MyFormComponent.js import React from 'react'; import { connect } from './store.js'; class MyFormComponent extends React.Component { ... } export default connect(MyComponent)
When connected, a form prop of the name specified in the config object (in our case
myForm
) is passed to the React component. ThemyForm
prop is an object containing a handful of properties and methods to interact with the store.class MyComponent extends React.Component { render () { const { select, valid, errors } = this.props.myForm; /** * The 'select' function accepts a key string and * returns an object containing the name field * object from the store with a 'bind' function. */ const nameField = select('name'); return ( <form> <div> {/* The 'bind' function returns an object of properties that can be spread on an input element effectively binding that component to update and track the state. */} <label>{nameField.label}</label><br/> <input {...nameField.bind()} /> </div> {/* The 'valid' property describes if all fields registered in the Redux store pass their validation rules. */} <button type="submit" disabled={!valid} /> <div> {/* The 'errors' array contains the first error message (if any) for all registered fields. */} <label>All errors:</label> <ul> {errors.map(err => <li>{err}</li>)} </ul> </div> </form> ) } }
The
bind
method returns an object containing input attributes (with"value"
) from the store andonChange
,onBlur
andonFocus
handlers to dispatch update actions.const bindProps = select('name').bind(); /* bindProps = { value: '', default: '', id: 'name', name: 'name', type: 'text', label: 'Name', className: '', placeholder: 'Name', disabled: false, autoFocus: false, onChange: (e: InputEvent, value?: any) => void, onBlur: () => void, onFocus: () => void, } */
Using the spread syntax will attach all the props to the input element, but you are free to choose which properties you want to use or create new ones from
bind
's return values:render() { const { select } = this.props; const { id, value, onChange } = select('email').bind(); return ( ... <input id={`${id}-is-the-id`} name="custom-email-name" value={value} onChange={(e, value) => { console.log('About to dispatch...') onChange(e); console.log('Dispatch complete!') }} /> ... ) }
To initiate more than one form just add more config objects as input parameters from the
init
function from step three.import { loginFormConfig, newUserConfig, ... } from './configs' // pass one or more config objects to init const { reducer, initialState, connect } = init(loginFormConfig, newUserConfig, ...);