use-form

useForm

Manage Preact, React, and React Native forms with a simple hook.

Installation

npm install --save @app-elements/use-form

Usage

Setting the action prop to a URL will tell useForm to submit the formData to that URL (if validations pass):

import { useForm } from '@app-elements/use-form'

const MyComponent = (props) => {
  const { clear, field, submit, isSubmitting } = useForm({
    action: 'auth/login',
    validations: {
      email: s => !s && 'Please provide your email address.',
      password: s => (!s || s.length < 6) && 'Password must be at least 6 characters'
    },
    onSuccess: ({ response }) => {
      console.log('onSuccess', response)
      clear(true)
    },
    onFailure: (errors) => console.log('onFailure', errors)
  })
  return (
    <div>
      <h1>useForm</h1>
      <form onSubmit={submit}>
        <input
          label='Email Address'
          placeholder='Your Email'
          required
          {...field('email')}
        />
        <input
          type='password'
          label='Password'
          placeholder='Your Password'
          required
          {...field('password')}
        />
        <button type='submit' className='btn' disabled={isSubmitting }>Login</button>
      </form>
    </div>
  )
}

If you need to make multiple requests on form submit, or want more control for some other reason, you can omit the action prop:

const { clear, field, submit, isSubmitting } = useForm({
  validations: {
    email: s => !s && 'Please provide your email address.',
    password: s => (!s || s.length < 6) && 'Password must be at least 6 characters'
  },
  onSuccess: ({ formData }) => {
    console.log('validated', formData)
    // Here you can do whatever you need with the validated formData
  },
  onFailure: (errors) => console.log('onFailure', errors)
})

If you solely want to alter the formData before it's sent to the server, you can also specify the preProcess function in conjunction with action. See the props table below for more details.

Props

Prop	Type	Default	Description
action	String	None	A URL to send form data to on submit.
opts	Object	{ method: 'POST' }	init object to pass to fetch.
initialData	Object	{}	Initial values for any fields.
validations	Object	None	Each key should match a field name, and the value is a function that accepts the field value and returns falsey or a string describing the validation error.
preProcess	Function	x => x	A function to process the form data before it's sent to the action URL.
onSuccess	Function	None	Function called when the form is submitted and validations pass. If action is set, called with { response } from the server, otherwise called with { formData }.
onFailure	Function	None	Function called when validations fail, or if action is set and the server response was unsuccessful.

Return Values

---

field

field(fieldName: String, opts?: { handlerName = 'onChange', errorClass = 'error', hintProp = 'title'}): Object

Return props to assign to a form input:

{
  name,
  value,
  [handlerName],
  [hintProp?],
  [className?]
}

Usage:

<input
  label='Email Address'
  placeholder='Your Email'
  required
  {...field('email')}
/>

---

submit

submit(ev?: SubmitEvent): None

Submits the form. Can also be called manually without an event.

<form onSubmit={submit}>

---

clear

clear(clearErrors = true): None

Clears the form data, defaulting to the InitialData provided. Optionally clears form errors as well.

clear(true)

---

formData

Object

The current form data represented as an object. Could be referenced to sync data outside of the form.

---

isSubmitting

Boolean

Boolean representing if the form is currently submitting. Can be used to display a loading indicator, or disable the submit button.