useField

A React hook for managing a single form field.
It uses useState (new tab) under the hood and leverages Zod (new tab) for validation.

'use client'
import { z } from 'zod'
import { useField } from '@weser/forms'

const schema = z.string().min(3, 'Please enter at least 3 characters')

export default function NameField() {
  const field = useField(schema, { name: 'name', value: '' })

  function handleSubmit(e: React.FormEvent) {
    e.preventDefault()
    // mark as touched to show errors
    field.update({ touched: true })
    if (field.validate().success) {
      // submit
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      <input {...field.inputProps} placeholder="Your name" />
      {field.errorMessage && <p role="alert">{field.errorMessage}</p>}
      <button>Save</button>
    </form>
  )
}

By default, the error message from Zod is used. While those are better than nothing, we still often want to show custom error messages to the user. This is also helpful when supporting multiple languages and having to translate on the fly on when your schemas are shared between multiple applications.

import { ZodIssue } from 'zod'

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

(Object) An object with the following properties and methods:

The current value of the field.

Whether the field is disabled.

Whether the field is touched.

Whether the field is dirty.

Whether the field is valid.

A string containing the validation message.
Only returned if the field is invalid and touched.

A function that takes field input data and updates the field accordingly.
Useful e.g. when receiving data from an API.

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

A function that validates the field.

(ZodSafeParseResult) Returns an object with success and error properties.

A function that resets the field back to its initial state.

An object with properties that can be passed to native HTML input, select and textarea elements.
Use data-valid to style the element based on the validation state.

An alternative to inputProps, that can be used to create custom components that render label and input elements. Also includes errorMessage and valid for proper error-state handling.

By default, useField expects string values and defaults to an empty string if no initial value is provided.
In order to also support e.g. boolean values or arrays, we can customise the generic types and pass new values.

import { ChangeEvent } from 'react'

const acceptsTerms = useField<boolean, ChangeEvent<HTMLInputElement>>(
  z.boolean(),
  {
    parseValue: (e) => e.target.checked,
    value: false,
  }
)

type ArrayChangeEvent = (value: Array<string>) => void
const tags = useField<Array<string>, ArrayChangeEvent>(z.array(z.string()), {
  // overwrite the default that expects a native HTML event
  parseValue: (value) => value,
  value: [],
})

Passing a custom value type and change event will also change the type of field.value and the expected input for update.