react-use-form

React hook to handle controlled form change and validation.

Getting started

Compatibility

Your project needs to use React.js 16.8 or later.

Installation

$ npm i @knightburton/react-use-form

or

yarn add @knightburton/react-use-form

Usage

Here's an example of basic usage:

import React from 'react';
import useForm from '@knightburton/react-use-form';

const App = () => {
  const onSubmit = data => console.log(data);
  const { fields, handleChange, handleSubmit } = useForm({
    schema: [{ field: 'text', value: '' }],
    onSubmit,
  });

  return (
    <form onSubmit={handleSubmit}>
      <input type="text" id="text" name="text" value={fields.text.value} onChange={handleChange} />
      {fields.text.error && <p>{fields.text.error}</p>}
      <input type="submit" value="Submit" />
    </form>
  );
};

export default App;

For more detailed example check the example directory.

Output

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 the preventDefaultEventOnSubmit and stopPropagationEventOnSubmit option. | | updateSchema | function | The function is used to submit a new or updated fields state. |

Options

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 the schema prop definitions | | onSubmit | function | undefined | Function called when the validation was successful after handleSubmit triggered. The values from fields state will be the first argument. | | onError | function | undefined | Function called when the validation was unsuccessful after handleSubmit triggered. The validated fields state will be the first argument. | | resetOnSubmit | boolean | false | Whether the field values should be reset to the default value after successful onSubmit or not. | | preventDefaultEventOnSubmit | boolean | true | Whether the handleSubmit event default behavior should be prevented (if event provided) or not. | | stopPropagationEventOnSubmit | boolean | true | Whether the handleSubmit event propagation should be prevented (if event provided) or not. |

Schema Option

The option itself is an array 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 the error is optional and the fallback will be the requiredError 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 the error definitions. | | validators | array | No | [] | Defines the validation rules. Check the definitions. |

Validators

This is an array 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 return boolean 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 return string value. |

Development

Local development is broken into two parts (ideally using two terminal tabs).

First, run rollup to watch your src/ module and automatically recompile it into dist/ whenever you make changes.

# Assume that you are in the project main folder
$ npm i
$ npm start

The second part will be running the example/ 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

Contributing

First off all, thanks for taking the time to contribute! :muscle:

Before any action, please visit the Code of Conduct and Contributing guideline for more information.

License

react-use-form is Open Source software under the MIT license. Complete license and copyright information can be found within the license.