![Logo](./.github/Logo.svg)
![Version](https://badgen.net/npm/v/formhero)
![Dependencies](https://badgen.net/david/dep/cupcakearmy/formhero)
![Size Badge](https://badgen.net/bundlephobia/minzip/formhero)
**Fully customisable react form utility.**
## 🌈 Features
- Typescript compatible
- Customizable extractor, validator, getter and setters. (More in the docs)
- **0** Dependencies
- Tiny
- React Hooks
###### Installation
```
npm i formhero
```
## 🚀 Quickstart
```typescript
import ReactDOM from 'react-dom'
import { useForm } from 'formhero'
const Form = () => {
const { auto, form } = useForm({
username: '',
password: '',
})
const _submit = (e: React.FormEvent) => {
e.preventDefault()
console.log(form)
}
return (
)
}
```
## 🔥 Examples
### Validation
```typescript
const Form = () => {
const { auto, form, errors } = useForm({
username: '',
email: '',
password: ''
}, {
username: value => value.length > 3,
email: {
validator: /@/,
message: 'Must contain an @',
},
password: [
{
validator: /[A-Z]/,
message: 'Must contain an uppercase letter'
},
{
validator: /[\d]/,
message: 'Must contain a digit'
},
]
})
return (
)
}
```
### Easy Customization
Often it happens that you use a specific input or framework, so the default getter, setter and extractor for the event won't cut it. No worries: formhero got you covered!
```typescript
const Form = () => {
const { auto, form, errors } = useForm({
awesome: true,
})
return (
)
}
```
## 📖 Docs
### `useForm`
```typescript
const {auto, errors, update, form, isValid} = useForm(initial, validators, options)
```
### Initial
This is the base state of the form. Also the typescript types are inhered by this.
###### Example
```javascript
const initial = {
username: 'defaultValue',
password: '',
rememberMe: true,
}
```
### Validators
A validator is an object that taked in either a `RegExp` or a `Function` (can be async). Optionally you can pass a message string that will be displayed instead of the default one.
###### Example: Regular Expression
```javascript
const validators = {
// Only contains letters.
// This could also be a (also async) function that returns a boolean.
username: /^[A-z]*$/,
}
```
###### Example: Function
```typescript
const validators = {
username: (value: string) => value.lenght > 3,
}
```
###### Example: With Object
```javascript
const validators = {
username: {
validator: /^[A-z]*$/,
message: 'My custom error message',
}
}
```
###### Example: Multiple Validators
```javascript
const validators = {
username: [
{
validator: /^[A-z]*$/,
message: 'My custom error message',
},
/[\d]/,
async (value) => value.length > 0,
{
validator: (value) => true,
message: 'Some other error',
}
]
}
```