Forms
/ API Reference
Forms
/ API Reference

useForm

A React hook for managing forms with Zod (new tab) validation.

The Gist

'use client'
import { z, ZodError } from 'zod'
import { useForm } from '@weser/forms'

const Z_RegisterInput = z.object({
  name: z.string().optional(),
  email: z.string().email(),
  password: z
    .string()
    // custom error messages to be shown to the user
    .min(8, { message: 'Your password next to have at least 8 characters.' }),
})

type T_RegisterInput = z.infer<typeof Z_RegisterInput>

function Form() {
  const { useFormField, handleSubmit, reset } = useForm(Z_RegisterInput)

  const name = useFormField('name')
  const email = useFormField('email')
  const password = useFormField('password')

  function onSuccess(data: T_RegisterInput) {
    // do something with the data
    console.log(data)
    reset()
  }

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

  return (
    <form 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} />
      {email.errorMessage && <p role="alert">{email.errorMessage}</p>}

      <label htmlFor="password">Password</label>
      <input id="password" type="password" {...password.inputProps} />
      {password.errorMessage && <p role="alert">{password.errorMessage}</p>}

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

Parameters

ParameterTypeDefaultDescription
schemaZodObjectThe Zod schema used to validate the data.
formatErrorMessage(error: ZodIssue, value: any, name: string) => string(error) => error.messageA function to overwrite the default error message from Zod. Receives the Zod issue, the current value and the name of the field.
See useField – formatErrorMessage for more details and examples.

Returns

(Object) An object with the following methods:

useFormField

A react hook to create form fields based on the schema properties.
It uses useField under the hood.

Parameters

ParameterTypeDescription
namekeyof z.infer<typeof schema>The name of the schema property that's connected to this field.
optionsOptionsInitial field data and additional configuration options.
See useField for more details. Takes all options except for name and formatErrorMessage.

Returns

(Object) See useField for the return type.

handleSubmit

A function used to handle the form submission.

It validates the form data and either calls onSubmit on success or onError on failure.

Useful Tip

Submitting a form will automatically touch all fields, making error messages visible.

Parameters

ParameterTypeDescription
onSubmit(data: z.infer<typeof schema>) => voidA function that receives the validated form data.
onError(error: ZodError) => voidA function that receives the Zod validation error.

Returns

(React.FormEventHandler) A form event handler. This must be passed to the onSubmit prop of a <form> element.

checkDirty

A function to check if the form is dirty.
Useful e.g. when conditionally showing a save button or when you want to inform a user about unsafed changes when leaving a page or closing a modal.

Returns

(boolean) Returns true if the form is dirty, false otherwise.

reset

A function to reset the form to its initial state.

On this page