useForm

useForm is a simple react hook that allows you to build forms quickly.

Arguments

useForm accepts an object with initialValues, validate, submitting, and onSubmit properties as its only argument.

initialValues

It's the only required property. It's an object consisting of field names and its corresponding values.

validate

It's a function that returns errors object where the keys are the field names and the values - the corresponding errors.

onSubmit

It's a function called with form values.

submitting

It's a boolean passed down to getFieldProps and returned from the hook to facilitate usage with context. It's set to false by default

submissionErrors

It's an object of errors that you can feed into the hook to handle showing submission errors.

Returned object

useForm returns an object with the following properties, getFieldProps, invalid, pristine, handleSubmitand resetForm.

getFieldProps

It's a function that takes in a field's name, and returns all the handlers and flags needed to to create a form field. Here is the list of returned handlers/flags:

• error
• submissionError
• touched
• submitting
• value
• onChange
• onBlur

invalid

It's a boolean that signals whether the form is invalid.

pristine

It's a boolean that signals whether the form values are equal to its initial values.

submitting

It's a boolean with the same value as the submitting property of the hook argument. Just a convenience flag.

handleSubmit

It's a wrapper function around the given onSubmit that normally should be applied to form's onSubmit.

resetForm

It's a function that resets the form to its initialState;.

Example

() => {
  const Input = ({
    error,
    submissionError,
    touched,
    value,
    onChange,
    onBlur,
  }) => (
    <div>
      <input onChange={onChange} onBlur={onBlur} value={value} />
      <div>
        {touched && error && <span style={{ color: 'red' }}>{error}</span>}
        {submissionError && (
          <span style={{ color: 'red' }}>{submissionError}</span>
        )}
      </div>
    </div>
  )
  const validate = values => {
    let errors = {}
    if (values.name === '') {
      errors.name = 'required'
    }
    return errors
  }
  const initialValues = {
    name: '',
  }
  const Example = () => {
    const [submissionErrors, setSubmissionErrors] = useState()
    const onSubmit = useCallback(values => {
      setTimeout(() => {
        if (Math.floor(Math.random() * 2) == 0) {
          alert(JSON.stringify(values))
        } else {
          setSubmissionErrors({ name: 'already exists' })
        }
      }, 1000)
    }, [])
    const { pristine, invalid, getFieldProps, handleSubmit } = useForm({
      initialValues,
      validate,
      onSubmit,
      submissionErrors,
    })
    const fieldProps = getFieldProps('name')
    return (
      <form onSubmit={handleSubmit}>
        <Input {...fieldProps} />
        <div>
          <button disabled={pristine || invalid}>submit</button>
        </div>
      </form>
    )
  }
  return <Example />
}