@knightburton/react-use-form
TypeScript icon, indicating that this package has built-in type declarations

1.2.1 • Public • Published

react-use-form

Development Workflow npm npm

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! 💪

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.

Package Sidebar

Install

npm i @knightburton/react-use-form

Weekly Downloads

2

Version

1.2.1

License

MIT

Unpacked Size

73.2 kB

Total Files

13

Last publish

Collaborators

  • knightburton