Docs
Forms
TanStack Form

TanStack Form

Build forms with TanStack Form and Standard Schema validation.

This guide shows how to build forms using TanStack Form with Kanpeki's Field component and schema validation.

Approach

TanStack Form provides headless form state management. We combine it with:

Field components for layout and accessibility
TextField for automatic ID wiring between label, input, description, and error
Any Standard Schema library (Zod, Valibot, ArkType) for validation — no adapters needed
Real-time validation feedback

Anatomy

<form
  onSubmit={(e) => {
    e.preventDefault();
    e.stopPropagation();
    form.handleSubmit();
  }}
>
  <form.Field
    name="email"
    children={(field) => {
      const isInvalid =
        field.state.meta.isTouched && !field.state.meta.isValid;
      return (
        <Field.Root
          render={
            <TextField
              id={field.name}
              isInvalid={isInvalid}
              name={field.name}
              onBlur={field.handleBlur}
              onChange={field.handleChange}
              value={field.state.value}
            />
          }
        >
          <Field.Label>Email</Field.Label>
          <Input placeholder="name@example.com" />
          <Field.Description>Helper text</Field.Description>
          <Field.Error errors={field.state.meta.errors} />
        </Field.Root>
      );
    }}
  />
  <Button type="submit">Submit</Button>
</form>

TextField is Kanpeki's React Aria behavior adapter. It automatically wires Field.Label, Field.Description, and Field.Error via aria-labelledby and aria-describedby. See the forms architecture for more.

Setup

Install dependencies

npm install @tanstack/react-form zod

Replace zod with any Standard Schema-compliant library such as valibot or arktype — TanStack Form supports them all natively with no extra adapters.

Create a schema

Define your form shape with your schema library of choice. This example uses Zod:

import { z } from "zod";

const formSchema = z.object({
  title: z
    .string()
    .min(5, "Title must be at least 5 characters.")
    .max(32, "Title must be at most 32 characters."),
  description: z
    .string()
    .min(20, "Description must be at least 20 characters."),
});

Setup the form

Use useForm with your schema passed to validators:

import { useForm } from "@tanstack/react-form";

const form = useForm({
  defaultValues: {
    title: "",
    description: "",
  },
  validators: {
    onChange: formSchema,
  },
  onSubmit: ({ value }) => {
    console.log(value);
  },
});

Validation

Validation Modes

TanStack Form supports different validation strategies:

Mode	Description
`onSubmit`	Validate on form submission
`onChange`	Validate on every change
`onBlur`	Validate when field loses focus
`onMount`	Validate immediately when field mounts

const form = useForm({
  validators: {
    onSubmit: formSchema,
    onChange: formSchema,
    onBlur: formSchema,
  },
});

Displaying Errors

Use <Field.Error /> with the errors prop. It renders nothing when the array is empty, so no conditional render is needed:

<form.Field
  name="email"
  children={(field) => {
    const isInvalid = field.state.meta.isTouched && !field.state.meta.isValid;
    return (
      <Field.Root
        render={
          <TextField
            id={field.name}
            isInvalid={isInvalid}
            name={field.name}
            onBlur={field.handleBlur}
            onChange={field.handleChange}
            value={field.state.value}
          />
        }
      >
        <Field.Label>Email</Field.Label>
        <Input type="email" />
        <Field.Error errors={field.state.meta.errors} />
      </Field.Root>
    );
  }}
/>

Schema transforms (e.g. z.string().transform(Number)) are not applied to the value received in onSubmit. If you need the transformed output, call schema.parse(value) manually inside onSubmit.

Field Types

Input

Preview

Code

Textarea

Preview

Code

Select

Preview

Code

Pass <Select.Root /> as the render prop on <Field.Root />. Use value and onChange for TanStack Form wiring.

Checkbox

Preview

Code

For checkbox groups, use mode="array" and pass <Checkbox.Provider /> as the render prop on each <Field.Root />:

<form.Field
  name="notifications"
  mode="array"
  children={(field) => {
    const isInvalid = field.state.meta.isTouched && !field.state.meta.isValid;
    return (
      <Field.Set>
        <Field.Legend variant="label">Notifications</Field.Legend>
        <Field.Group data-slot="checkbox-group">
          {options.map((option) => (
            <Field.Root
              key={option.id}
              orientation="horizontal"
              render={
                <Checkbox.Provider
                  isSelected={field.state.value.includes(option.id)}
                  onChange={(checked) => {
                    if (checked) {
                      field.pushValue(option.id);
                    } else {
                      const index = field.state.value.indexOf(option.id);
                      if (index > -1) field.removeValue(index);
                    }
                  }}
                />
              }
            >
              <Checkbox.Root>
                <Checkbox.Indicator />
              </Checkbox.Root>
              <Field.Label>{option.label}</Field.Label>
            </Field.Root>
          ))}
        </Field.Group>
        <Field.Error errors={isInvalid ? field.state.meta.errors : []} />
      </Field.Set>
    );
  }}
/>

Switch

Preview

Code

<form.Field
  name="marketing"
  children={(field) => (
    <Field.Root orientation="horizontal">
      <Field.Content>
        <Field.Title>
          <Field.Label htmlFor={id}>Marketing emails</Field.Label>
        </Field.Title>
        <Field.Description>
          Receive emails about new products and features.
        </Field.Description>
      </Field.Content>
      <Switch.Root
        id={id}
        isSelected={field.state.value}
        onChange={field.handleChange}
      >
        <Switch.Track>
          <Switch.Thumb />
        </Switch.Track>
      </Switch.Root>
    </Field.Root>
  )}
/>

Submit Button State

Use <form.Subscribe /> to disable the submit button while submitting or when the form is invalid:

Always pass selector before children on <form.Subscribe />. Swapping the order causes TypeScript to lose inference on the selector's return type, resulting in type errors throughout the render function.

<form.Subscribe
  selector={(state) => [state.canSubmit, state.isSubmitting]}
  children={([canSubmit, isSubmitting]) => (
    <Button type="submit" isDisabled={!canSubmit}>
      {isSubmitting ? "Submitting..." : "Submit"}
    </Button>
  )}
/>

canSubmit is false when validation fails or a submission is already in flight. isSubmitting is true while onSubmit is pending.

Resetting the Form

Use form.reset() to reset to default values:

<Button onPress={() => form.reset()} type="reset">
  Reset
</Button>

Array Fields

TanStack Form supports dynamic array fields with mode="array":

Preview

Code

const formSchema = z.object({
  emails: z
    .array(z.object({ address: z.string().email() }))
    .min(1, "Add at least one email."),
});

<form.Field
  name="emails"
  mode="array"
  children={(field) => (
    <Field.Set>
      <Field.Legend variant="label">Email Addresses</Field.Legend>
      <Field.Group>
        {field.state.value.map((_, index) => (
          <form.Field
            key={index}
            name={`emails[${index}].address`}
            children={(subField) => {
              const isInvalid =
                subField.state.meta.isTouched && !subField.state.meta.isValid;
              return (
                <Field.Root
                  render={
                    <TextField
                      id={subField.name}
                      isInvalid={isInvalid}
                      name={subField.name}
                      onBlur={subField.handleBlur}
                      onChange={subField.handleChange}
                      type="email"
                      value={subField.state.value}
                    />
                  }
                >
                  <Input placeholder="name@example.com" />
                  <Field.Error errors={subField.state.meta.errors} />
                </Field.Root>
              );
            }}
          />
        ))}
      </Field.Group>
      <Button
        type="button"
        variant="outline"
        size="sm"
        onPress={() => field.pushValue({ address: "" })}
      >
        Add Email
      </Button>
    </Field.Set>
  )}
/>;

Array Helpers

Method	Description
`field.pushValue(item)`	Add item to end of array
`field.removeValue(i)`	Remove item at index
`field.insertValue(i)`	Insert item at index
`field.swapValues(a,b)`	Swap items at indices
`field.moveValue(from,to)`	Move item to new index
`field.replaceValue(i,item)`	Replace item at index
`field.clearValues()`	Remove all items

Linked Fields

When one field's validation depends on another (e.g. confirm password), use onChangeListenTo to re-run validation when the watched field changes:

Preview

Code

<form.Field
  children={(field) => ...}
  name="password"
/>
<form.Field
  children={(field) => ...}
  name="confirmPassword"
  validators={{
    onChangeListenTo: ["password"],
    onChange: ({ value, fieldApi }) => {
      if (value !== fieldApi.form.getFieldValue("password")) {
        return {
          message: "Passwords do not match.",
        };
      }
    },
  }}
/>

React Hook Form