- Notifications
You must be signed in to change notification settings - Fork0
React hook to handle controlled form change and validation.
License
knightburton/react-use-form
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
React hook to handle controlled form change and validation.
Your project needs to useReact.js 16.8 or later.
$ npm i @knightburton/react-use-form
or
yarn add @knightburton/react-use-form
Here's an example of basic usage:
importReactfrom'react';importuseFormfrom'@knightburton/react-use-form';constApp=()=>{constonSubmit=data=>console.log(data);const{ fields, handleChange, handleSubmit}=useForm({schema:[{field:'text',value:''}], onSubmit,});return(<formonSubmit={handleSubmit}><inputtype="text"id="text"name="text"value={fields.text.value}onChange={handleChange}/>{fields.text.error&&<p>{fields.text.error}</p>}<inputtype="submit"value="Submit"/></form>);};exportdefaultApp;
For more detailed example check theexample directory.
The hook returns an object with the following props.
| Prop name | Type | Description |
|---|---|---|
| fields | object | Generated fields state with values and errors. |
| handleChange | function | The function is used to update a value inside the fields state. It accepts an input change event. |
| handleSubmit | function | The function is used to submit the fields state for validation. It can accept an event, the behavior of that can be prevented with thepreventDefaultEventOnSubmit andstopPropagationEventOnSubmit option. |
| updateSchema | function | The function is used to submit a new or updated fields state. |
The hook behavior can be modified with the following props.
| Prop name | Type | Default Value | Description |
|---|---|---|---|
| schema | object[] | [] | Defines the initial fields state and provides the validation rules for later. Check theschemaprop definitions |
| onSubmit | function | undefined | Function called when the validation was successful afterhandleSubmit triggered. The values fromfields state will be the first argument. |
| onError | function | undefined | Function called when the validation was unsuccessful afterhandleSubmit triggered. The validatedfields state will be the first argument. |
| resetOnSubmit | boolean | false | Whether the field values should be reset to the default value after successfulonSubmit or not. |
| preventDefaultEventOnSubmit | boolean | true | Whether thehandleSubmit event default behavior should be prevented (if event provided) or not. |
| stopPropagationEventOnSubmit | boolean | true | Whether thehandleSubmit event propagation should be prevented (if event provided) or not. |
The option itself is anarray of objects and each object should look like this:
| Prop name | Type | Mandatory | Default Value | Description |
|---|---|---|---|---|
| field | string | Yes | - | Identifier of the field. |
| value | generic | Yes | - | Defines the initial value of the field. |
| required | boolean /Validator /function | No | false | Defines whether the field is required or not during the validation. It can be a special validator where theerror is optional and the fallback will be therequiredError or the default builtin error. It can be a function where you can decide whether the field should be required or not based on other field values or the actual field value. |
| requiredError | function /string | No | This field is required. | Defines the returned error when a field marked as required. Check theerror definitions. |
| validators | array | No | [] | Defines the validation rules. Check thedefinitions. |
This is anarray of objects where each item defines rules and error messages:
| Prop name | Type | Mandatory | Description |
|---|---|---|---|
| rule | function /RegExp | Yes | Defines the rule for field validation. It can be a function where the first arg is the corresponding field value and the second arg is the field values for complex rules. The function must returnboolean value. |
| error | function /string | Yes (No, if used for required.) | Defines the error message for invalid field. It can be a function where the first arg is the corresponding field value and the second arg is the field values for complex message. The function must returnstring value. |
Local development is broken into two parts (ideally using two terminal tabs).
First, run rollup to watch yoursrc/ module and automatically recompile it intodist/ whenever you make changes.
# Assume that you are in the project main folder$ npm i$ npm startThe second part will be running theexample/ create-react-app that's linked to the local version of your module.
# Assume that you are in the project main folder$cd example$ npm i$ npm start
First off all, thanks for taking the time to contribute! 💪
Before any action, please visit theCode of Conduct andContributing guideline for more information.
react-use-form is Open Source software under the MIT license. Complete license and copyright information can be found within thelicense.
About
React hook to handle controlled form change and validation.