Validation

Crustack form uses field-level validation instead of form-level schemas. This approach prevents duplicating validation logic and keeps validation rules close to their respective fields.

Field-level validation simplifies complex scenarios like multi-step forms and conditional fields by only validating mounted fields. This makes the form more maintainable and performant.

Can I use a validation library?

Yes, you can use any validation library that is compliant with the Standard Schema Specification.

When is validation performed?

Validation occurs:

whenever form values change
when a submit attempt is made
when onSubmit resolves/rejects

This ensures that dependent fields are updated based on the new values, maintaining form consistency.

When is the error message displayed?

Error messages appear when a field is touched and the validate function returns an error string. A field becomes touched either through the setFieldTouched function or when submitting the form.

Sync Validation

Basic validation

Simple field validation:

function MyTodoForm() {
  return (
    <form.Root
      initialValues={{ title: '', description: '' }}
      onSubmit={postTodo}
    >
      <form.Form>
        <form.Field
          name="title"
          validate={(title) => title.length < 5 && 'Too short'}
        >
          <Input label="Title" />
          <form.ErrorMessage />
        </form.Field>

        <form.Field
          name="description"
          validate={(description) => description.length < 20 && 'Too short'}
        >
          <Input label="Description" />
          <form.ErrorMessage />
        </form.Field>

        <button children="Submit" />
      </form.Form>
    </form.Root>
  )
}

Dependent fields

Validate a field based on the value of another field:

function MyTodoForm() {
  return (
    <form.Root
      initialValues={{ title: '', description: '' }}
      onSubmit={postTodo}
    >
      <form.Form>
        <form.Field
          name="title"
          validate={(title, formValues) => {
            if (title.length < 5) {
              return 'The title is too short'
            }
            if (title.length > formValues.description.length) {
              return 'The title should not be longer than the description'
            }
          }}
        >
          <Input label="Title" />
          <form.ErrorMessage />
        </form.Field>

        <form.Field
          name="description"
          validate={(description, formValues) => {
            if (description.length < 20) {
              return 'The description is too short'
            }
            if (description.length < formValues.title.length) {
              return 'The description should be longer than the title'
            }
          }}
        >
          <Input label="Description" />
          <form.ErrorMessage />
        </form.Field>

        <button children="Submit" />
      </form.Form>
    </form.Root>
  )
}

Field Arrays

Validation can also be applied to field arrays to have one error message for all fields in the array.

const fruits = ['apple', 'banana', 'orange', 'pear', 'pineapple', 'strawberry']

function FruitsForm() {
  return (
    <form.Root initialValues={{ fruits: [] }} onSubmit={postFruits}>
      <form.Form>
        <form.FieldArray
          name="fruits"
          validate={(fruits) =>
            fruits.length < 3 && 'You must choose at least 3 fruits'
          }
        >
          {fruits.map((fruit, index) => (
            <form.Field key={`fruits.${fruit}`} name={`fruits.${index}`}>
              <FruitCheckbox fruit={fruit} />
            </form.Field>
          ))}
          {/* Display the field array error message */}
          <form.ErrorMessage />
        </form.FieldArray>

        <button children="Submit" />
      </form.Form>
    </form.Root>
  )
}

function FruitCheckbox({ fruit }: { fruit: string }) {
  const ctx = form.useFieldArrayCtx()
  return (
    <div>
      <form.Control>
        <input
          type="checkbox"
          checked={ctx.value.includes(fruit)}
          onChange={(e) => {
            if (e.target.checked) {
              ctx.setValue(({ fruits }) => [...fruits, fruit])
            } else {
              ctx.setValue(({ fruits }) => fruits.filter((f) => f !== fruit))
            }
          }}
        />
      </form.Control>
      <form.Label>{fruit}</form.Label>
    </div>
  )
}

Async Validation

Submission based async validation

Validate fields based on the submission state.

import { defineForm } from '@crustack/form'

type FormValues = { email: string }
type SubmissionError = { email?: string }

const form = defineForm<FormValues, SubmissionError>()

// Fake API call that rejects with a SubmissionError
async function submitForm() {
  return Promise.reject({ email: 'invalid email' })
}

export function SubscriptionForm() {
  return (
    <form.Root initialValues={{ email: '' }} onSubmit={submitForm}>
      {(ctx) => (
        <form.Form>
          <form.Field
            name="email"
            validate={(email) => {
              // if this field's value is the same as the submission's values, return the submission error
              if (email === ctx.submission.values?.email) {
                return ctx.submission.error?.email
              }
              // otherwise, validate the email on the client
              return validateEmail(email)
            }}
          >
            <Input label="Email Address" />
            <form.ErrorMessage />
          </form.Field>

          <button children="Submit" />
        </form.Form>
      )}
    </form.Root>
  )
}

Field-level async validation

Check if an email is already used before subscribing.

import { useQuery } from '@tanstack/react-query'
import { useEffect } from 'react'
import { defineForm } from '@crustack/form'
import { timeout } from '@crustack/utils'
import { useDebounceValue } from '@1hook/use-debounce-value'

// define the form
const form = defineForm<{ email: string; password: string }>()

export function SignupForm() {
  return (
    <form.Root
      initialValues={{ email: '', password: '' }}
      onSubmit={() => 'success'}
    >
      <form.Form>
        <EmailField />
        <PasswordField />
        <button>Submit</button>
      </form.Form>
    </form.Root>
  )
}

function EmailField() {
  const { validateForm, ...ctx } = form.useFormCtx()
  const email = ctx.getFieldValue('email')
  const debouncedEmail = useDebounceValue(email, 500)
  const isDebouncing = email !== debouncedEmail
  /**
   * Using the synchronous email value instead of the debounced value
   * in order to avoid using stale cached results.
   * Using debouncedEmail in the queryKey will output the cached result
   * of the previous debouncedEmail while isDebouncing.
   */
  const validateEmailQuery = useQuery({
    queryKey: ['email', email],
    // disable the query if there is a sync error, or the email is being debounced
    enabled: !isDebouncing && !validateEmail(email),
    // Avoid throwing the validation response: tanstack-query doesn't cache errors
    queryFn: async () => {
      // touch the field to show the validation result
      ctx.setFieldTouched('email', true)
      await timeout(1000)
      if (email === 'valid@email.com') return ''
      return 'Email already exists'
    },
  })

  /**
   * Revalidate the form when the async validation is completed.
   * This will update all displayed error messages
   */
  useEffect(validateForm, [
    validateEmailQuery.data,
    validateEmailQuery.error,
    validateForm,
  ])

  const showPendingState =
    // no pending state when the sync validation fails
    !validateEmail(email) &&
    // otherwise show pending state
    (isDebouncing || validateEmailQuery.isLoading)

  function getEmailErrorMessage(value: string) {
    return (
      // sync validation
      validateEmail(value) ||
      // async validation, since we don't throw the validation result
      // to best use the cache, we use the `data` property
      validateEmailQuery.data ||
      // async validation failed (eg. "Failed to fetch")
      (validateEmailQuery.isError &&
        'An unexpected error has occurred, please try again later.')
    )
  }

  return (
    <form.Field name="email" validate={getEmailErrorMessage}>
      <Input label="Email Address" />

      {!!showPendingState && (
        // Prevent the form submission when the pending state is displayed
        <form.PreventSubmit>
          <Spinner />
        </form.PreventSubmit>
      )}

      <form.ErrorMessage />
    </form.Field>
  )
}

Validation

On this page