react-controlled-form

Flexible, Modular & Controlled Forms for React and Redux
GitHub
118
Created 7 years ago, last commit 4 months ago
5 contributors
110 commits
Stars added on GitHub, month by month
0
0
0
0
0
0
0
0
0
10
11
12
1
2
3
4
5
6
7
8
9
2023
2024
Stars added on GitHub, per day, on average
Yesterday
=
Last week
0.0
/day
Last month
0.0
/day
Last 12 months
0.0
/day
Package on NPM
Monthly downloads on NPM
10
11
12
1
2
3
4
5
6
7
8
9
2023
2024
No dependencies
README

react-controlled-form

A package for creating controlled forms in React with baked in zod validation.
You own and control the rendered markup and the hook takes care of the state and validation.

npm version npm downloads Bundlephobia

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>
  )
}

Note: This is, of course, a simplified version and you most likely render custom components to handle labelling, error messages and validation styling.
For such cases, each field also exposes a props property that extends the inputProps with non-standard HTML attributes.

API Reference

useForm

The core API that connects the form with a zod schema and returns a set of helpers to manage the state and render the actual markup.

Parameter  Type Default  Description
schema ZodObject   A valid zod object schema
formatErrorMessage  (error: ZodIssue, name: string) => string (error) => error.message A custom formatter that receives the raw zod issue
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

The preferred way to handle custom error messages would be to add them to the schema directly.
In some cases e.g. when receiving the schema from an API or when having to localise the error, we can leverage this helper.

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

A hook that manages the field state and returns the relevant HTML attributes to render our inputs.
Also returns a set of helpers to manually update and reset the field.

Parameter  Type Default  Description
name keyof z.infer<typeof schema> The name of the schema property that this field connects to
config Config See Config Initial field data and additional config options

Config

Property Type Default  Description
value any '' Initial value
disabled boolean false Initial disabled state
touched boolean false Initial touched state that indicates whether validation errors are shown or not
showValidationOn "change" | "blur" | "submit" "submit" Which event is used to trigger the touched state
parseValue (Event) => any (e) => e.target.value How the value is received from the input element.
Use e.target.checked when working with <input type="checkbox" />
const { inputProps, props, errorMessage, update, reset } = useField('email')

inputProps

Pass these to native HTML input, select and textarea elements.
Use data-valid to style the element based on the validation state.

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

props

Pass these to custom components that render label and input elements.
Also includes information such as errorMessage or valid that's non standard HTML attributes and thus can't be passed to native HTML input elements directly.

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

errorMessage

Note: If you're using props, you already get the errorMessage!

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

update

Programmatically change the data of a field. Useful e.g. when receiving data from an API.
If value is changed, it will automatically trigger re-validation.

Note: If you know the initial data upfront, prefer to pass it to the useField hook directly though.

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

reset

Resets the field back to its initial field data.

reset()

handleSubmit

Helper that wraps the native onSubmit event on <form> elements.
It prevents default action execution and parses the form data using the zod schema.

Parameter  Type  Description
onSuccess (data: z.infer<typeof schema>) Callback on successful safe parse of the form data
onFailure (error: ZodError) Callback on failed safe parse
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

Resets the form fields back to their initial field data. Helpful when trying to clear a form after a successful submit.

Note: This API is similar to the reset helper that the useField hook returns. The only difference is that it resets all fields.

reset()

isDirty

Returns whether the form is dirty, meaning that any of the fields was altered compared to their initial state.
Useful e.g. when conditionally showing a save button or when you want to inform a user that he's closing a modal with unsafed changes.

isDirty()

formProps

An object that contains props that are passed to the native <form> element. Currently only consists of a single prop:

const formProps = {
  noValidate: true,
}

Recipes

Non-String Values

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 types and pass new 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: [],
})

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

License

react-controlled-form is licensed under the MIT License.
Documentation is licensed under Creative Common License.
Created with ♥ by @robinweser and all the great contributors.