react-cool-forms
Powerful and flexible forms for React
Features
🌟 Real flexible API🙈 UI library agnostic💫 Conditional fields🎯 Array fields🍓 Form-level validation🍉 Field-level validation🔗 Dependent validation🙃 Custom validators💞 onChange validation support🎀 Async validators support⚡️ Output formatters support🚀 Extremal performance🦥 Small size (6 Kb gzipped)✔️ No dependencies
Demo
Motivation
I have been looking for a form validation library for React in the npm repository for a long time, but all of them did not suit me for one reason or another. First of all, I lacked the flexibility of the API of these libraries. Most of them are based on the use of simple HTML inputs and the like. But writing complex forms is not limited to HTML inputs or checkboxes or something else. Having a lot of experience with forms at my former company, I decided to write this library. The main message: any arbitrarily complex component that implements the value / onChange interface can be a full member of the form and pass the required validation. I also combined the classic Observer pattern along with the React Context and React memoization to get the best input performance without debounce technique (tested 3000 inputs in one form).
Installation
npm:
npm install react-cool-forms
yarn:
yarn add react-cool-forms
Usage
API
import {
Form,
Field,
Repeater,
Debugger,
useFormState,
type Validator,
type Formatter,
} from 'react-cool-forms';
Form
This is the root component that contains the root react context. Forms can be nested inside each other if you need it for some reason. The main properties that a Form takes are the initialization object and the onSubmit callback.
import { Form } from 'react-cool-forms';
FormProps
prop | required | description |
---|---|---|
initialFormValue | Initialization object. | |
connectedRef | Ref for imperative access to main methods. | |
interrupt | Indicates whether to stop validation on the first error or not. | |
validators | Array of root validators. | |
onValidate | Called every time during validation. | |
onChange | Called every time formValue changes. | |
onSubmit | Called after successful validation of the entire form. | |
children | Render function that takes options (FormChildrenOptions). |
FormChildrenOptions
prop | description |
---|---|
formValue | Actual value of form. |
errors | Object with all validation errors. |
inProcess | Shows if we are in the process of validation. |
validate | Manual validation start if you need it. For example, validation before moving to the next step of the wizard. |
submit | Call it for validation and submit form. |
reset | Reset formValue to initialFormValue. |
Field
This is a component that renders a single form element, such as input. Since the component does not impose any restrictions on how the form element should look, it expects to receive a render function as children that will display it.
import { Field } from 'react-cool-forms';
FieldProps
prop | required | description |
---|---|---|
name | Label for correctly adding an error message to the error object. It should be unique within the form. | |
getValue | Value access function inside formValue. | |
setValue | Function to set a new value. | |
formatter | Function that formats value. | |
validators | Array of validators that will participate in the validation process of this component. | |
updatingKey | By default, the rendering of a child component in a Field is memoized for performance reasons. You can add this key to let the component know when you still want to update it. | |
enableOnChangeValidation | Enables validation on the onChange event. | |
onValidate | Fires every time a field is validated. | |
children | Render function that takes options. (FieldChildrenOptions). |
FieldChildrenOptions
prop | required | description |
---|---|---|
name | Label that was passed to the Field. | |
value | Field value. Must be passed to the component that will trigger the value update, such as an input. | |
error | optional | Text error if field validation fails. |
nodeRef | You can pass a nodeRef to your input if you want to implement something like scrolling to an element that didn’t pass validation. This ref will later be passed to the onValidate callback for this Field. | |
validate | Allows you to call the validation of this field, for example, on the onBlur event. | |
notify | Allows you to manually cause a new value to be set in a field. For example, inside the onBlur event to return an unformatted value to the form. Suppose the value of a field is ‘$1,000’ after formatting, even though the field is of type number. In this case, it is convenient to call the function of transforming a string into a number inside onBlur so that the correct data is sent to the server. | |
onChange | Must be passed to the component that will trigger the value update, such as an input. |
Validator
A validator is a simple object that contains three fields: a method, a message and an innerrupt. If you want to implement asynchronous validation, for example for a request to the server, then in the validation method, you must return a promise. You can also make validation dependent on other fields, due to the fact that the validation method accepts not only the value of one validated field, but also the value of the entire form.
import { type Validator, type ValidatorMethodOptions } from 'react-cool-forms';
Formatter
import { type Formatter, type FormatterOptions } from 'react-cool-forms';
A formatter is a function that formats value. Allows you to implement input masks or otherwise transform the output. It takes options with previous value, next value and node.
Repeater
In order to work with array-based forms, there is a Repeater component. It renders a list of nested Fields that, behind the scenes, work as a separate form with its own context, but in the end, thanks to the Repeater magic, arrays of forms can be treated as one. You can also nest Repeaters within each other if your data structure requires it. For example, you have an array of companies in your structure, and each of those companies has an array of accounts, and so on.
import { Repeater } from 'react-cool-forms';
RepeaterProps
prop | required | description |
---|---|---|
name | Label for correctly adding an error message to the error object. It should be unique within the form. | |
connectedRef | Ref for imperative access to list modification methods (append, prepend, insert, swap, remove). | |
getValue | Value access function inside formValue. | |
setValue | Function to set a new value. | |
getKey | Function to return the unique ID of an object. Needed so that React knows when it should unmount the node completely. | |
interrupt | Indicates whether to stop validation on the first error or not. | |
triggerPosition | Specifies where to render form control buttons: before or after the list. | |
renderTrigger | Function that takes options (RenderTriggerOptions) and should render buttons for adding elements to an array. | |
children | Render function that takes options (RepeaterChildrenOptions). |
RenderTriggerOptions
prop | description |
---|---|
inProcess | Shows if we are in the process of validation. |
size | Number of elements in the current array. |
append | Allows you to add an element to the end of the list. |
prepend | Allows you to add an element to the beginning of the list. |
insert | Allows you to add an element at the specified index. |
swap | Allows swapping 2 list items. |
remove | Allows you to remove an element from the list at the specified index or array of indices. |
Note that some list management methods take a shouldFocus parameter. If this parameter is true, then when rendering the list, you will need to pass it as an input to the autoFocus property.
Debugger
This is the component you need to view the formatted formValue and errors while using the form. To use it, you just need to put it inside a Form.
import { Debugger } from 'react-cool-forms';
// Example of output
{
"errors": {
"name": "It is required field"
},
"formValue": {
"name": "",
"companies": [
{
"ID": 1,
"name": "Company #1"
},
{
"ID": 2,
"name": "Company #2"
}
]
}
}
useFormState
A hook that you can use to access the form value and some of its useful methods while inside child components.
const {
formValue,
errors,
inProcess,
addValidator,
removeValidator,
modify,
validate,
submit,
reset,
} = useFormState();
You can use this hook to detect changes in the entire form or in part of it by setting the detectChanges function. Now your component will only render when that piece of data in the form changes.
Be sure to look at examples of using various APIs in the examples folder.
LICENSE
MIT © Alex Plex