useFormless

react-useformless is a simple library that allows you to control forms with react-hooks approach

Installing

how to install

$> yarn add react-useformless

$> npm install react-useformless

Getting Started

Step 1 Import it 📦

import useFormless from 'react-useformless';

Step 2 State and Options

useFormless hook receives:

1. options(optional)

{
  initialValues: {
    name: '',
    email: '',
  },
  validate: (name, value) => {
    // This function receives name and value as parameters and will return a string given name
    // You can do your valdiations as follow

    // 1.- Define a object with function validations for each name in the form
    // functions receives the value and return a error for it
    const validators = {
      name: validateNameFunction,
      email: validateEmailFuntion
      // ... else function validations for each field
    }

    // 2.- get the function for given `name` and then is called with tha value
    const errorFn = validators[name]
    return errorFn(value)
  },
  onError: (ev: DOMEvent) => {
    ev.preventDefault()
    // if you decide using onSubmit function provided by formless, this function is fired after submit error
    // It receives DOMevent so you do whatever you want after it ends
  },
  onSuccess: (ev: DOMEvent) => {
    ev.preventDefault()
    //same as error option but it is fired on success
  }
}

Step 3 Use it 💡

Create an instance of useFormless and render it, easy, isn't it? 💃🏻

const { values, errors, inputProps, onSubmit } = useFormeless({ initialValues }, { validate, onSuccess, onError });

return(
  <section>
    <h1>Basic example</h1>
    <form onSubmit={onSubmit}>
      <label htmlFor="name">Name</label>
      <input id="name" type="text" {...inputProps('name', 'armando')}/>
      <p style={{color: 'red', fontSize: 9}}>{errors.name}</p>
      <label htmlFor="email">email</label>
      <input id="email" type="password" {...inputProps('password')}/>
      <p style={{color: 'red', fontSize: 9}}>{errors.email}</p>
      <input type="submit" value="Login"/>
    </form>
  </section>
)

if you prefer it, get started 🎮 with this snippet in CodeSandbox

Prerequisites

React hooks already are stables, so what are you waiting for? useFormless is now updated with React v16.8 and ready to use

API

useFormless provides you some methods so you can add them to your Component.

Notice: use react-hooks into functional components.

Objects returned

Name	Description
values: Object	an Object {} contains all values using the key as name, see example above
errors: Object	an Object {} contains all errors using the key as name
touched: Object	an Object {} contains all values have been touched/modified

common behavior for forms

Function	Description
setValue(name: string, value: any)	set a value and validates if it has error
getValue(name: string)	get a value given a name
setValues({}: values)	set all values also of party forms but it doesn't fire validations
touchValue(name)	mark the value passed as touched
reset()	set all values as initialValues Object
party(name: string, { validate: function}))	you can create nested forms, this function receives a name and validate option that allow you valdiate this party only, also it work like an object returned by useFormless and another party function to continue adding more nested forms
validateForm()	Run validations, set errors and mark all objects as touched
validateValue()	Run validations, set errors and mark all objects as touched
validateParty(	Run validations only for a nested form, set errors and mark all objects as touched
isValid: boolean	true: is for a valid form, false: is for a invalid form

Helpers

When we created useFormless, we thought about separating behavior and UI, because of it your components are more resuables.

Function	Description
inputProps(name: String): Object	This funtion will return custom props {name, value, onChange, onBlur}, pass this object to your input component directly, see example
inputCheckboxProps(name: String): Object	The same for inputProps but for checkbox inputs
onSubmit(SyntathicEvent): void	Handle submit event, this will trigger either onSuccess or onError functions

Examples

<form id="my-form" onSubmit={onSubmit}>

<input id="my-input" type="text" {...inputProps('email')}>

Running the tests

In order to run tests use jest and react-testing-library

Built With

• react16.8 - The web framework used
• yarn - For dependencies management

Authors

• Gibran Lopez gediez
• Crystal Stream CrystalStream

Acknowledgments

• Similar libraries; formik and redux-form

#License

useFormless is MIT licensed