react-formable
The goal of react-formable
is to provide a simple API to serialize and validate forms. Out of the box, it is compatible with vanilla HTML inputs along with a wide variety of custom inputs.
We do this by passing a name
to each input element within our Form
. The form then tracks all these named inputs, whenever one of them changes or the form is submitted, it optionally serializes and validates them and sends them to the onChange
and onSubmit
callbacks.
For validation, the Form
component looks for any validators
array which is a prop or static member of a component. This array can have functions which accept the input's current value and the entire form's current value, and returns any value. If the result is truthy, it is considered an error. If a promise is returned, any resolved or rejected truthy value is considered an error.
That covers the basics of using react-formable
. There are plenty of props to customize the default behavior of the form including:
- Validating the form: We provide three options for validating the form. By default we validate the form fully when the form is submitted. You can also optionally validate the entire form form, or just the dirty fields, when an input changes.
- Rendering error messages: There are two primary ways you can communicate errors to the user. We provide an
<Errors />
that when placed inside the form, it will automatically display any errors within the form. If you want to display errors on the field level, we provide amapFieldErrorsToProps
function which takes the field errors of the individual component, the props of that component, and the resulting object is merged into the props of the component. The default for this function appends anerror
class to every input with an associated error. - Debouncing validation: A common use case is to show errors on an individual component level after the user has stopped typing in that field. Between validating only the dirty fields, mapping field errors to props, and debouncing validation, we get this out of the box for free.
- Inline hits: Sometimes you may want to display hints to the user as they are typing in a field. Validators can return anything, including an object with extra information. Furthermore, validators get a third parameter which is the source of the event, either
onChange
,onSubmit
, oronSerialize
. We can attach this tag to the return value of the validators and use this additional information to render hints or errors.
API
Basic Usage
Lets start things off with a simple example, a login form.
// Our hypothetical login action render, document.getElementById'example'
Nothing terribly exciting, let's break it down and see what is going on. First, we have the Form
component exposed by react-formable
. This wraps all of our inputs and other markup. It exposes two callbacks which we can tap into to grab the state of the form, onSubmit
and onChange
.
Moving along, we have a few vanilla DOM nodes, two input
s and a button
. The Form
component tracks all components with a name
property. The name
value is then used as the serialized key for the field value. Clicking on the button
submits the form just as it would a normal form
tag.
Let's add a few some validation!
// Our hypothetical login action // Simulate a network request to check if the username is taken render, document.getElementById'example'
We added a few things to our login form! Form
scans all named components for a prop called validators
which is an array of functions. These functions are called with the value of the of the input along with all values of the form. If you return a truthy value, it is considered an error. If you return a promise, any truthy value either resolved or rejected from the promise is considered an error. Lastly, Form
strips validators
from the component by default letting you have validation with any input.
Back to our example, the username field has two validators. One which just checks if the username has length. The second simulates a network request to see if the username provided is "taken"
, if so, it returns and error message.
We also provide an Errors
component which renders any errors in the form. We can optionally choose when to show errors, either onChange
or onSubmit
(by default).
Dev
yarn start