Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/enterwell/react-form-validation
Simple React form validation package.
https://github.com/enterwell/react-form-validation
form-validation forms hooks react reactjs
Last synced: about 2 months ago
JSON representation
Simple React form validation package.
- Host: GitHub
- URL: https://github.com/enterwell/react-form-validation
- Owner: Enterwell
- License: mit
- Created: 2020-06-04T12:23:36.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2024-11-18T23:19:50.000Z (2 months ago)
- Last Synced: 2024-11-21T13:37:24.018Z (2 months ago)
- Topics: form-validation, forms, hooks, react, reactjs
- Language: JavaScript
- Homepage:
- Size: 3.28 MB
- Stars: 10
- Watchers: 4
- Forks: 3
- Open Issues: 18
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: license
Awesome Lists containing this project
README
Enterwell's React form validation
Keeps and validates your form's data. Doesn't mess with your components. Simple and straight to the point.
[](https://www.npmjs.com/package/@enterwell/react-form-validation)
[](https://github.com/Enterwell/react-form-validation/actions/workflows/npm-publish.yml)
## Features
* Keeps form's state and validation results
* Supports any kind of validation functions
* Dirty checking
* Separates data from view
* Relies on hooks, but can easily be used with class components
## Installation
Package can be installed with one of the following commands (depending on whether you prefer `npm`, `yarn` or `pnpm`)
```bash
npm install @enterwell/react-form-validation
```
```bash
yarn add @enterwell/react-form-validation
```
```bash
pnpm add @enterwell/react-form-validation
```
## Usage
Two quick steps to validate any kind of input.
Step 1:
* Define custom validation (or use some of predefined) and use it to initialize validation hook
```jsx
import { isValidEmail, useValidation } from '@enterwell/react-form-validation';
const email = useValidation('[email protected]', isValidEmail);
```
Step 2:
* Pass the email data to your input
```jsx
{email.error && (
Incorrect email!
)}
```
And thats all!
## API
### `useValidation(initialValue, validationFn, config?)`
Hook that keeps on form field's data.
#### Params
| Name | Type
| Required | Description |
| ---- | ---- | ---- | ----------- |
| initialValue | _any_ | yes | Field's initial value |
| validationFn | _(any) => boolean or Promise<boolean>_ | yes | Function for validating the field's value |
| config | _{
receiveEvent?: boolean,
reversed?: boolean
ignoreDirtiness?: boolean
}_ | no | Additional hook configuration.
- `receiveEvent` inidicates whether `onChange` callback will receive whole event or just target's value
- `reversed` indicates whether reversed error logic should be applied (error being `false` when present, instead of `true`)
- `ignoreDirtiness` indicating whether field's dirtiness should be ignored (by default, field is validate on blur, but only if field is dirty ie. if its value has been changed)
#### Returns
| Type
| Description ||---- | ----------- |
| _{
value: any,
error: boolean
onChange: (any, config?) => void
onBlur: (event, config?) => void
setValue: (value: any) => void
validate: (any, config?) => boolean or Promise<boolean>
reset: () => void,
props: {
value: any,
onChange: (any, config?) => void
onBlur: (event, config?) => void
}
}_ | Object with field's data and callbacks.
- `value` - field's current value
- `error` - is error present flag (`true` if value was validated and didn't pass validation, `false` otherwise)
- `onChange` - callback for change event (changes the value and validates it if previous value wasn't correct)
- `onBlur` - callback for blur event (validates the value)
- `setValue` - function for setting the internal value (does not validate the input, enabling support for async data loading)
- `validate` - function for validating field's value
- `reset` - function for resetting field's data
- `props` - set of props that can be spread on standard input elements (same as props in root object, just grouped for better DX)
`onChange`, `onBlur` and `validate` functions accept config as last parameter - this will override config from `useValidation` if provided. |
#### Usage example
```jsx
import { useValidation, isNonEmptyString } from '@enterwell/react-form-validation';
/* Some code... */
const userFormData = {
name: useValidation(name, isNonEmptyString),
age: useValidation(age, () => true)
};
console.log(userFormData.name) // {value: "Matej", error: false, onChange: ƒ, onBlur: ƒ, validate: ƒ, reset: f}"
```
___
### `extractValues(fields)`
Util function for extracting values from fields' data objects.
#### Params
| Name | Type
| Required | Description || ---- | ---- | ---- | ----------- |
| fields | _{
key: { value: any },
...
}_ | yes | Form field's data (each field must have `value` property - other properties are not important) |
#### Returns
| Type
| Description ||---- | ----------- |
| _Object_ | Object with fields' names as keys, and their values as values |
#### Usage example
```jsx
import { ..., extractValues } from '@enterwell/react-form-validation';
/* useValidation example's code... */
const data = extractValues(userFormData);
// ^ { name: "Matej", age: 10 }
```
### `setValues(fields, values)`
Util function for setting field's values from provided data objects.
#### Params
| Name | Type
| Required | Description || ---- | ---- | ---- | ----------- |
| fields | _{
key: { value: any },
...
}_ | yes | Form field's data. |
| values | _{
key: any,
...
}_ | yes | Form field's values to be set to fields. |
#### Usage example
```jsx
import { ..., setValues } from '@enterwell/react-form-validation';
const formData = {
name: useValidation('', isNonEmptyString)
};
const item = useItem();
useEffect(() => {
if (item) {
setValues(formData, {
name: item.name
});
}
}, [item]);
```
### `validateFields(fields)`
Util function for validating values of all fields
#### Params
| Name | Type
| Required | Description || ---- | ---- | ---- | ----------- |
| fields | _{
key: {
value: any
validate: (any) => boolean
},
...
]_ | yes | Form field's data (each field must have `value` and `validate` properties - other properties are not important) |
#### Returns
| Type
| Description ||---- | ----------- |
| _boolean_ or _Promise<boolean>_ | `false` if form data is correct, `true` otherwise. Promise with same result when at least one validation function resolved to Promise. |
#### Usage example
```jsx
import { ..., validateFields } from '@enterwell/react-form-validation';
/* useValidation example's code... */
const hasError = validateFields(userFormData);
console.log(hasError) // false
```
### `resetFields(fields)`
Util function for resetting all fields' data.
#### Params
| Name | Type
| Required | Description || ---- | ---- | ---- | ----------- |
| fields | _{
key: { reset: () => void },
...
}_ | yes | Form field's data (each field must have `reset` property - other properties are not important) |
#### Usage example
```jsx
import { ..., resetFields } from '@enterwell/react-form-validation';
/* useValidation example's code... */
resetFields(userFormData);
```
### `submitForm(fields, onSubmit)`
Util function for handling the form submit. Form's fields are first validated. If all values are correct, they are extracted to data object and passed to `onSubmit` callback. Returns value of `onSubmit` callback.
#### Params
| Name | Type
| Required | Description || ---- | ---- | ---- | ----------- |
| fields | _{
key: {
value: any
validate: (any) => boolean
},
...
}_ | yes | Form field's data (each field must have `value` and `validate` properties - other properties are not important) |
| onSubmit | _(any) => object or void_ | yes | On submit callback |
#### Returns
| Type
| Description ||---- | ----------- |
| _object_ or _Promise<object>_ or _undefined_ | Return value of `onSubmit` callback, wrapped in promise with same result when at least one validation function resolved to Promise. Returns `undefined` if validation fails or `onSubmit` is of return type _void_. |
#### Usage example
```jsx
import { ..., submitForm } from '@enterwell/react-form-validation';
/* useValidation example's code... */
const onSubmit = (data) => fetch("www.some-url.com/post", {
method: 'POST',
data: JSON.stringify(data)
});
submitForm(userFormData, onSubmit);
```
### `cancelForm(fields, onCancel)`
Util function for handling the form cancel. Form's fields are reset and `onCancel` callback is called.
#### Params
| Name | Type
| Required | Description || ---- | ---- | ---- | ----------- |
| fields | _{
key: { reset: () => void },
...
}_ | yes | Form field's data (each field must have `reset` property - other properties are not important) |
| onCancel | _(any) => void_ | yes | On cancel callback |
#### Usage example
```jsx
import { ..., cancelForm } from '@enterwell/react-form-validation';
/* useValidation example's code... */
const onCancel = (data) => alert("Form has been reset");
cancelForm(userFormData, onCancel);
```
___
_Unless otherwise stated, each validation function will have the following #### Params and #### Returns._
#### Params
| Name | Type
| Required | Description || ---- | ---- | ---- | ----------- |
| value | _any_ | no | Form field's value |
#### Returns
| Type
| Description ||---- | ----------- |
| _boolean_ | `true` if field's value is correct, `false` otherwise |
### `noError()`
No error validation. Value of the field with this validation function will always be correct.
### `areEqual(value, other)`
Are values equal validation. Value of the field with this validation function will be correct if it is equal to some other value (e.g. some other field's value).
#### Params
| Name | Type
| Required | Description || ---- | ---- | ---- | ----------- |
| value | _any_ | no | Form field's value |
| other | _any_ | no | Some other value |
#### Returns
| Type
| Description ||---- | ----------- |
| _boolean_ | `true` if field's value is correct, `false` otherwise |
### `isTrue(value)`
Is true validation. Value of the field with this validation function will be correct only if it is `true`.
### `isNotNull(value)`
Is not null validation. Value of the field with this validation function will be correct only if it is not `null`.
### `isNonEmptyString(value)`
Is non-empty string validation. Value of the field with this validation function will be correct if it is not an empty string.
### `isValidNumber(value)`
Is valid number validation. Value of the field with this validation function will be correct if it represents the valid number (as number or as string).
### `isPositiveNumber(value)`
Is positive number validation. Value of the field with this validation function will be correct if it is the positive number.
### `isNegativeNumber(value)`
Is negative number validation. Value of the field with this validation function will be correct if it is the negative number.
### `isNonEmptyArray(value)`
Is non-empty array validation. Value of the field with this validation function will be correct if it is the non-empty array.
### `isValidEmail(value)`
Is valid email validation. Value od the field with this validation function will be correct if it is non-empty string with valid email address.
### `isValidIpAddress(value)`
Is valid IP address validation. Value od the field with this validation function will be correct if it is a non-empty string with valid IPv4 or IPv6 address.
## Future plans
We noticed that there are few things which could be added to our package in order to make it more flexible and easy to use. Here is what you can expect in the future:
* additional config which will enable to change when value is validate (e.g. only in `onChange`, in `onBlur` but only if current value is not valid and so on)
* more validation functions