gem-hunter

react-controlled-form

Installation

# npm
npm i --save react-controlled-form
# yarn
yarn add react-controlled-form
# pnpm
pnpm add react-controlled-form

The Gist

import * as React from 'react'
import { useForm, FieldProps } from 'react-controlled-form'
import { z, ZodError } from 'zod'

// create our schema with validation included
const Z_RegisterInput = z.object({
  name: z.string().optional(),
  email: z.string().email(),
  // we can also pass custom messages as a second parameter
  password: z
    .string()
    .min(8, { message: 'Your password next to have at least 8 characters.' }),
})

type T_RegisterInput = z.infer<typeof Z_RegisterInput>

function Form() {
  // we create a form by passing the schema
  const { useField, handleSubmit, formProps, reset } = useForm(Z_RegisterInput)

  // now we can create our fields for each property
  // the field controls the state and validation per property
  const name = useField('name')
  const email = useField('email')
  const password = useField('password')

  function onSuccess(data: T_RegisterInput) {
    // do something with the safely parsed data
    console.log(data)
    // reset the form to its initial state
    reset()
  }

  function onFailure(error: ZodError) {
    console.error(error)
  }

  return (
    <form {...formProps} onSubmit={handleSubmit(onSuccess, onFailure)}>
      <label htmlFor="name">Full Name</label>
      <input id="name" {...name.inputProps} />

      <label htmlFor="email">E-Mail</label>
      <input id="email" type="email" {...email.inputProps} />
      <p style={{ color: 'red' }}>{email.errorMessage}</p>

      <label htmlFor="password">Password</label>
      <input id="password" type="password" {...password.inputProps} />
      <p style={{ color: 'red' }}>{password.errorMessage}</p>

      <button type="submit">Login</button>
    </form>
  )
}

API Reference

useForm

import { z } from 'zod'

const Z_Input = z.object({
  name: z.string().optional(),
  email: z.string().email(),
  // we can also pass custom messages as a second parameter
  password: z
    .string()
    .min(8, { message: 'Your password next to have at least 8 characters.' }),
})

type T_Input = z.infer<typeof Z_Input>

// usage inside react components
const { useField, handleSubmit, reset, formProps } = useForm(Z_Input)

formatErrorMessage

import { ZodIssue } from 'zod'

// Note: the type is ZodIssue and not ZodError since we always only show the first error
function formatErrorMessage(error: ZodIssue, name: string) {
  switch (error.code) {
    case 'too_small':
      return `This field ${name} requires at least ${error.minimum} characters.`
    default:
      return error.message
  }
}

useField

Config

const { inputProps, props, errorMessage, update, reset } = useField('email')

inputProps

type InputProps = {
  name: string
  value: any
  disabled: boolean
  'data-valid': boolean
  onChange: React.ChangeEventHandler<HTMLElement>
  onBlur?: React.KeyboardEventHandler<HTMLElement>
}

props

type Props = {
  value: any
  name: string
  valid: boolean
  required: boolean
  disabled: boolean
  errorMessage?: string
  onChange: React.ChangeEventHandler<HTMLElement>
  onBlur?: React.KeyboardEventHandler<HTMLElement>
}

errorMessage

update

update({
  value: 'Foo',
  touched: true,
})

reset

reset()

handleSubmit

import { ZodError } from 'zod'

function onSuccess(data: T_Input) {
  console.log(data)
}

function onFailure(error: ZodError) {
  console.error(error)
}

// <form> onSubmit handler
const onSubmit = handleSubmit(onSuccess, onFailure)

reset

reset()

isDirty

isDirty()

formProps

const formProps = {
  noValidate: true,
}

Recipes

Non-String Values

import { ChangeEvent } from 'react'

const acceptsTerms = useField<boolean, ChangeEvent<HTMLInputElement>>('terms', {
  // alter how the value is obtained if neccessary
  // e.g. for checkboxes or custom inputs
  parseValue: (e) => e.target.checked,
  // set an initial value overwritting the default empty string
  value: false,
})

// custom multi-select input that returns an array of values on change
type Tags = Array<string>
type TagsChangeEvent = (value: Tags) => void

const tags = useField<Tags, TagsChangeEvent>('tags', {
  parseValue: (value) => value,
  value: [],
})

License