diff --git a/README.md b/README.md index 8b299d1..81a8a5e 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,24 @@ - Tiny - React Hooks +###### Links + +- [__*Live Web*__](https://cupcakearmy.github.io/formhero/) +- [__*Live React-Native*__](https://snack.expo.io/@cupcakearmy/useform) +- [Examples](#-examples-more-here) +- [Docs](#-documentation) + - Contructor + - [Initial State](#initial) + - [Validators](#validators) + - [Options](#options) + - Returns + - [auto](#auto) + - [form](#form) + - [errors](#errors) + - [isValid](#isvalid) + - [update](#update) + + ###### Installation ``` @@ -52,71 +70,90 @@ const Form = () => { } ``` -## 🔥 Avanced Example +## 🔥 Examples [(More Here)](https://github.com/CupCakeArmy/formhero/tree/master/examples) + +### Validation ```typescript -import ReactDOM from 'react-dom' -import { useForm } from 'formhero' - const Form = () => { const { auto, form, errors } = useForm({ username: '', - password: '', - type: 'formhero', - awesome: true, + email: '', + password: '' }, { - username: /^test/, - password: { - validator: /^.{3,}$/, - message: 'To short', + username: value => value.length > 3, + email: { + validator: /@/, + message: 'Must contain an @', }, - awesome: (value) => !!value + password: [ + { + validator: /[A-Z]/, + message: 'Must contain an uppercase letter' + }, + { + validator: /[\d]/, + message: 'Must contain a digit' + }, + ] }) - const _submit = (e: React.FormEvent) => { - e.preventDefault() - console.log(form, errors) - } + return ( +
+ +

Errors & Validation

+ + + {errors.username && 'Must be longer than 3'} + + + {errors.email} + + + {errors.password} + +
+ ) +} +``` + +### 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 ( -
-
- -
Username
- - {errors.username && 'Something went wrong'} -
+ { + e.preventDefault() + console.log(form) + }}> -
Password
- -
+

Custom

-
Which one to choose?
- -
- -
Is it awesome?
+ - -
-
+ + + ) } ``` -## 📖 Docs +## 📖 Documentation ### `useForm` @@ -170,3 +207,176 @@ const validators = { } } ``` + +###### 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', + } + ] +} +``` + +### Options + +Sometimes it's practical to have some different default values when using for example react-native or some other framework where the default `value`, `onChange` and `(e)=> e.target.value` do not apply. + +###### Example: React Native (Method 1 - Global options) + +[Check the Expo Snack for a live preview](https://snack.expo.io/@cupcakearmy/useform) + +```javascript +import * as React from 'react'; +import { Text, SafeAreaView, TextInput } from 'react-native'; +import { useForm } from 'formhero'; + +const initial = { + username: 'i am all lowercase', +}; +const validators = {}; +const options = { + setter: 'value', // This is not stricly necessarry as 'value' would already be the default. + getter: 'onChangeText', + extractor: text => text.toLowerCase(), +}; + +export default () => { + const { form, auto } = useForm(initial, validators, options); + + return ( + + + {form.username} + + ); +}; +``` + +###### Example: React Native (Method 2 - Local overwrite) + +```javascript +// ... + +export default () => { + const { form, auto } = useForm({ + username: 'i am all lowercase', + }); + + return ( + + text.toLowerCase(), + })} + /> + {form.username} + + ); +}; + +``` + +### Auto + +The `auto` object is used to bind the form state to the input. + + +###### Example: Simple + +```javascript +const { auto } = useForm() + + +``` + + +###### Example: With custom options + +All are optional. + +```javascript +const { auto } = useForm() + + e.target.value +})} /> +``` + +## Form + +This is the form state that you can use when submitting the data + +###### Example + +```javascript + +const { form } = useForm(...); + +// ... + +
console.log(form)}> + // ... +
+``` + +## Errors + +This object contains the error messages if a field is not valid. +The error message can be specified by you, otherwise it will return `Error in ${field}` + +###### Example + +```javascript +const { errors } = useForm(...) + +//... + +{errors.username} +{errors.password} +``` + +## isValid + +`isValid` is a little simple helper that checks whether the `error` object is clear or if there are errors left. + +## Update + +The `update` function allows you to manually change and assign the state of the form. This can be usefull when you want to reset a field or the whole form. The input must have the same type as the initial state. + +###### Example + +```javascript +const { form, update } = useForm(...) + +const resetUsername = () => { + update({ + ...form, + username: '', + }) +} + +const resetForm = () => { + update({ + username: '', + password: '', + }) +} +```