useFormless

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

Why useFormless?

Works with nested forms 🎉
Zero dependencies 🆓
Includes helpers for field and form tags, it makes a easy for use

Getting Started

Step 1: Install it

$ yarn add react-useformless

$ npm install react-useformless

Step 2: Import it 📦

import useFormless from 'react-useformless';

Step 3: Set state and options

useFormless accepts an optional object that lets you add validations handlers

Options(optional)

{
 initialValues: {
   name: '',
   email: '',
 },
 validate: (name, value) => {
   // This function receives [name and value] as parameters and will return either a string with the error or an empty string.
   // You can do your validations as follow

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

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

Step 4: Use it! 💡

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

const { values, errors, inputProps, onSubmit } = useFormless({ 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 are live now, so what are you waiting for? useFormless is now updated with React v16.8 and ready to use

API

useFormless provides you a clean and easy-to-use API that you can attach to any component.

Notice: Use react-hooks into functional components.

Objects returned:

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

Common behavior for forms:

Function	Description
setValue(name: string, value: any)	set a value and validate it
getValue(name: string)	get a value given a name
setValues({}: values)	set all values (including party forms) but it doesn't trogger validations
touchFieldname)	mark the passed value as touched
reset()	set all values as initialValues Object
party.create(name: string, { validate: function}))	you can create nested forms, this function receives a name and validates option that allows you to validate this party only, also it works 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 an invalid form

Helpers

useFormless splits the behavior and the UI, so your components become more reusables.

Function	Description
inputProps(name: String): Object	This function will return custom props `{name, value, onChange, onBlur}`, pass this object to your input component directly, see example
inputCheckboxProps(name: String): Object	Same as inputProps but for checkbox inputs
onSubmit(SyntacticEvent): void	Handle submit event, this will trigger either onSuccess or onError functions
field	an object with functions for fields
party	an object with functions for party forms
form	an object with functions for forms

See more about it in the documentation official DOCS

Examples

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

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

Contribute

Running the tests

useFormless uses 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

GeDiez/react-use-formless