Skip to content
Source
Sign inSign up
TanStack/form
Open History to see the last commit

SKILL.md

228 lines5.2 KB

TanStack React Form - Error Visibility Workflows

Use errorVisibility to define when validation errors become visible. It is a callback, not a string preset.

Setup

import { createErrorVisibility, useForm } from '@tanstack/react-form'

const showAfterBlurOrSubmit = createErrorVisibility(
  ({ fieldState, state }) =>
    fieldState.meta.isBlurred || state.submissionAttempts > 0,
)

export function LoginForm() {
  const form = useForm({
    defaultValues: {
      email: '',
    },
    errorVisibility: showAfterBlurOrSubmit,
  })

  return (
    <form.Field
      name="email"
      validators={[
        {
          run: ({ value }) =>
            value.length === 0 ? 'Email is required' : undefined,
          triggers: ['change', 'blur'],
        },
      ]}
    >
      {(field) => (
        <label>
          <input
            value={field.value}
            onBlur={field.handleBlur}
            onChange={(event) => field.handleChange(event.target.value)}
          />
          <small>{field.errors.map((error) => error.message).join('\n')}</small>
        </label>
      )}
    </form.Field>
  )
}

Hooks And Components

Show after blur or submit

const showAfterBlurOrSubmit = createErrorVisibility(
  ({ fieldState, state }) =>
    fieldState.meta.isBlurred || state.submissionAttempts > 0,
)

Use this for workflows that avoid showing errors before the user interacts or submits.

Keep form-specific logic inline

const form = useForm({
  defaultValues: {
    mode: 'business',
    companyName: '',
  },
  errorVisibility: ({ state, fieldState }) =>
    state.values.mode === 'business' && fieldState.meta.isBlurred,
})

Inline callbacks can use the consuming form's typed values.

Use trigger policies with visibility policies

import { createValidator } from '@tanstack/react-form'

const rewardEarlyPunishLate = createValidator({
  triggers: [
    'blur',
    {
      trigger: 'change',
      when: ({ triggerFieldApi }) =>
        triggerFieldApi !== undefined && triggerFieldApi.meta.isInvalid,
    },
  ],
})

Visibility controls display. Validator config controls when validation runs.

Common Mistakes

HIGH Writing string visibility presets

Wrong:

const form = useForm({
  defaultValues: { email: '' },
  errorVisibility: 'touched',
})

Correct:

const form = useForm({
  defaultValues: { email: '' },
  errorVisibility: ({ fieldState }) => fieldState.meta.isTouched,
})

errorVisibility is callback-based.

Source: TanStack/form-v2:packages/form-core/src/validation.public.ts

HIGH Checking visible errors inside visibility

Wrong:

errorVisibility: ({ fieldState }) => fieldState.meta.errors.length > 0

Correct:

errorVisibility: ({ fieldState }) => fieldState.meta.isBlurred

Visibility receives pre-filter meta; visible errors are the result of the callback.

Source: TanStack/form-v2:packages/form-core/src/FieldApi/fieldState.lib.ts

HIGH Repeating local showErrors conditions

Wrong:

const showErrors = field.meta.isTouched && field.meta.isInvalid

return showErrors ? <small>{field.errors[0]?.message}</small> : null

Correct:

const form = useForm({
  defaultValues: { email: '' },
  errorVisibility: ({ fieldState }) => fieldState.meta.isTouched,
})

Use form-level policy when the same display workflow applies across fields.

Source: maintainer interview

MEDIUM Reusable policy expects typed values

Wrong:

const showBusinessErrors = createErrorVisibility(
  ({ state }) => state.values.mode === 'business',
)

Correct:

const form = useForm({
  defaultValues: { mode: 'business', companyName: '' },
  errorVisibility: ({ state }) => state.values.mode === 'business',
})

Reusable visibility policies are form-agnostic and receive values: unknown.

Source: TanStack/form-v2:packages/form-core/src/validation.public.ts

MEDIUM Ignoring group-scoped submissions

Wrong:

errorVisibility: ({ state }) => state.submissionAttempts > 0

Correct:

errorVisibility: ({ state, fieldState }) =>
  fieldState.meta.isBlurred || state.submissionAttempts > 0

Inside a registered form group, scalar state reads are scoped to the nearest group.

Source: TanStack/form-v2:packages/form-core/src/validation.public.ts

References