# use-models
> advanced form model hooks for your functional react components. build huge, complex forms with validation using minimal boilerplate code.
[](https://www.npmjs.com/package/use-models) [](https://standardjs.com)
## Install
```bash
npm install --save use-models
```
## Features
- form helpers `input`, `checkbox`, and `radio` which wire up your form elements to state with path syntax, eg `book.author.firstname`. nesting supported for objects(and possibly arrays)
- form validation supporting built in validators, custom validators, async validators, and ability to extend built in validators for usage across project.
- simple `state` object representing your forms state, and an `errors` object which displays when a field has an error. state properties are mirrored on the errors object.
- ability to hydrate state using the `hydrate` function, useful for syncing from api or from localstorage, or whatever you need.
- ability to watch fields for changes with `watch` helper method, which receives `oldValue` and `newValue` as arguments.
- `submit` and `error` functions that create handlers for your form's `onSubmit` and `onError` events. submit receives a copy of `state` and `errors` receives a list of form errors.
- no dependencies (other than react ofc)
- highly configurable/composable.
- plugin friendly, offering plenty of ways to "hook" into the library for custom functionality.
## Tutorial
> this tutorial will teach you the concepts of how to use the features to build your application
1. setting up your state with `useModels` and wiring up an input to the state with `input` helper.
```jsx
import React from 'react';
import useModels from 'use-models';
export default function Example() {
// here you can see that useModels is called with an object defining our state(and optionally validation, which will be shown in a later step)
const {
input, // input ( path, type='text' )
checkbox, // checkbox( path, trueValue=true, falseValue=false )
radio // radio( path, value )
} = useModels({
email_address: '',
password:'',
remember_me: false,
newsletter_signup: 'no'
});
// this is example shows a login form
return (
);
}
```
2. adding validation
importing the model helper:
```jsx
import React from 'react';
import useModels,{model} from 'use-models';//we can add the model helper for ease in defining our models. this is optional, as options can be defined as a plain object as well
```
using model helper:
```jsx
const {
input, // input ( path, type='text' )
checkbox, // checkbox( path, trueValue=true, falseValue=false )
radio // radio( path, value )
} = useModels({
email_address: model('','email') // here we are declaring a field with default value of "" and a named validator called "email" which validates an email address.
});
```
using a plain object:
```jsx
const {
input, // input ( path, type='text' )
checkbox, // checkbox( path, trueValue=true, falseValue=false )
radio // radio( path, value )
} = useModels({
email_address: { value: '', validate:['email'] } // equivalent to model('','email');
});
```
custom validator functions:
```jsx
const {
input, // input ( path, type='text' )
checkbox, // checkbox( path, trueValue=true, falseValue=false )
radio // radio( path, value )
} = useModels({
username: model('',value=>{
// we are passing a custom validator
// you should return a string or Error( Custom error classes and Error Like objects are ok too) for failing validation, else return a falsy value or nothing at all
// you can also return a promise for async validation, which will be shown in next example
if(value.length<5){
return 'Username must be atleast 5 characters in length. Choose a longer name';// you can return a string error message
}
if(value.length>30){
return new Error('Username cannot be longer than 30 characters in length. Choose a shorter name.');//showing returning an Error object
}
})
});
```
async validator example:
```jsx
export default function Example() {
const {
input, // input ( path, type='text' )
checkbox, // checkbox( path, trueValue=true, falseValue=false )
radio // radio( path, value )
} = useModels({
username: model('',async value=>{
return await new Promise((resolve,reject)=>{
setTimeout(()=>{
reject(new Error('that username is taken. try a different name'))
},200);
});
})// simulating a network call to check if the username is available.
});
...
}
```
extending validators for shared re-use across your project:
```jsx
import useModels,{model,extendValidators} from 'use-models';
extendValidators('myCustomValidator',value=>{
// your validation logic here
});
function Example() {
const {
input, // input ( path, type='text' )
checkbox, // checkbox( path, trueValue=true, falseValue=false )
radio // radio( path, value )
} = useModels({
username: model('','myCustomValidator')// tell useModels() to use `myCustomValidator` for this field
});
...
}
```
you can use as many validator functions as you want. the additional arguments to `model()` will accumulate:
```jsx
model('','email','myCustomValidator',value=>{}) // equivalent to { value:'', validate:['email','myCustomValidator', value=>{} ] }
```
3. handling form submit and form submit error
```jsx
export default function Example() {
const { submit, error } = useModels({
foo:''
});
const onSubmit = submit(state=>{
//the form has been submitted and there are no errors. the full state object is available here(though it is also returned from `useModels()` as well)
});
const onError = error((errors,state)=>{
//the form was submitted, but there is an error.
// NOTE: the arguments to this function may change, but currently the error and state objects are what is received.
});
return
}
```
4. displaying form errors by reading `error` object
> The state object is mirrored 1:1 to the errors object. all values in the errors object will be `false`, unless the field has an error.
> for example, if you have a field called `username`, you can check if there is an error in the field by reading `errors.username`, as shown below:
```jsx
export default function Example() {
const { input, submit, error, state, errors } = useModels({
username: model('','not_empty')
});
const onSubmit = submit(()=>{});
const onError = error(()=>{});
return (
)
}
```
5. executing code when the value of a field changes using the `watch()` api
```jsx
export default function Example() {
const { input, watch } = useModels({
username: model('','not_empty')
});
// you can watch a field for changes, very simply
// the returned function can be used to deregister the watcher
const unwatch = watch('username',(newValue,oldValue)=>{
console.log('username changed from %s to %s',oldValue,newValue);
});
return (
)
}
```
6. reading the `state` object
> sometimes you want to read the form state and use it to render some component in your ui with the form state. you can do that with the `state` variable.
```jsx
export default function Example() {
const { input, state } = useModels({
age: ''
});
return (
);
}
```
7. populating the state with data using `hydrate()`
> you will probably face a situation where you need to load some data, whether from the network or from localstorage or even a cookie. you can do so very easily using `hydrate()`
> below example shows hydrating state on componentMount, which is probably the most common use case.
> NOTE: in addition to hydrating the `state`, you can also hydrate the `errors` object if desired, by passing a second argument.
> NOTE: partial updating is supported, but only for top level keys. no diffing is done at a nested level. this behavior may change in the future.
```jsx
import React,{useEffect} from 'react'
import useModels from 'use-models'
export default function Example() {
const { hydrate, state } = useModels({
firstname:'',
lastname:'',
email:''
});
useEffect(()=>{
hydrate({
firstname:'Garrett',
lastname:'Morris',
email:'test@test.com'
});
},[hydrate]);// note: if you don't pass hydrate in as a dependency to useEffect(), the linter complains.
console.log(state);// on second render you will see state populated with the values passed to hydrate.
return (
...
);
}
```
8. using `get()` and `set()` for custom input methods or for other state features, like a loading indicator
```jsx
import React from 'react'
import useModels from 'use-models'
function registerUser( name ) {
...
}
export default function Example() {
const { state, input, get, set, submit } = useModels({
loading: false,
name:'',
user_type:'user',
submit_error:null
});
const onSubmit = submit(()=>{
set('loading',true);
registerUser(state.name).then(()=>{
set('loading',false);
set('submit_error',null);
})
.catch(err=>{
console.log('err',err);
set('loading',false);
set('submit_error',err.message);
})
})
return (
state.loading ?