TanStack · HM-23-HM · Apr 8, 2026 · Apr 8, 2026
diff --git a/docs/config.json b/docs/config.json
@@ -580,6 +580,10 @@
             {
               "label": "Devtools",
               "to": "framework/react/examples/devtools"
+            },
+            {
+              "label": "Multistep Form",
+              "to": "framework/react/examples/multistep"
             }
           ]
         },

diff --git a/examples/react/multistep/.eslintrc.cjs b/examples/react/multistep/.eslintrc.cjs
@@ -0,0 +1,11 @@
+// @ts-check
+
+/** @type {import('eslint').Linter.Config} */
+const config = {
+  extends: ['plugin:react/recommended', 'plugin:react-hooks/recommended'],
+  rules: {
+    'react/no-children-prop': 'off',
+  },
+}
+
+module.exports = config
diff --git a/examples/react/multistep/.gitignore b/examples/react/multistep/.gitignore
@@ -0,0 +1,27 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# production
+/build
+
+pnpm-lock.yaml
+yarn.lock
+package-lock.json
+
+# misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
diff --git a/examples/react/multistep/README.md b/examples/react/multistep/README.md
@@ -0,0 +1,6 @@
+# Example
+
+To run this example:
+
+- `npm install`
+- `npm run dev`
diff --git a/examples/react/multistep/index.html b/examples/react/multistep/index.html
@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <link rel="icon" type="image/svg+xml" href="/emblem-light.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="theme-color" content="#000000" />
+
+    <title>TanStack Form React Multistep Form Example App</title>
+  </head>
+  <body>
+    <noscript>You need to enable JavaScript to run this app.</noscript>
+    <div id="root"></div>
+    <script type="module" src="/src/index.tsx"></script>
+  </body>
+</html>
diff --git a/examples/react/multistep/package.json b/examples/react/multistep/package.json
@@ -0,0 +1,37 @@
+{
+  "name": "@tanstack/form-example-react-multistep",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite --port=3001",
+    "build": "vite build",
+    "preview": "vite preview",
+    "test:types": "tsc"
+  },
+  "dependencies": {
+    "@tanstack/react-form": "^1.28.5",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@tanstack/react-devtools": "^0.9.7",
+    "@tanstack/react-form-devtools": "^0.2.19",
+    "@types/react": "^19.0.7",
+    "@types/react-dom": "^19.0.3",
+    "@vitejs/plugin-react": "^5.1.1",
+    "vite": "^7.2.2"
+  },
+  "browserslist": {
+    "production": [
+      ">0.2%",
+      "not dead",
+      "not op_mini all"
+    ],
+    "development": [
+      "last 1 chrome version",
+      "last 1 firefox version",
+      "last 1 safari version"
+    ]
+  }
+}
diff --git a/examples/react/multistep/public/emblem-light.svg b/examples/react/multistep/public/emblem-light.svg
diff --git a/examples/react/multistep/src/index.tsx b/examples/react/multistep/src/index.tsx
@@ -0,0 +1,133 @@
+import * as React from 'react'
+import { createRoot } from 'react-dom/client'
+import { TanStackDevtools } from '@tanstack/react-devtools'
+import { formDevtoolsPlugin } from '@tanstack/react-form-devtools'
+import { useForm } from '@tanstack/react-form';
+import { z } from 'zod';
+import type { AnyFieldApi, DeepKeys } from '@tanstack/react-form';
+
+const userSchema = z.object({
+  firstName: z.string().min(2, 'Too short'),
+  email: z.string().email('Invalid email'),
+});
+
+type FormData = z.infer<typeof userSchema>;
+
+function FieldUI({ field, label }: { field: AnyFieldApi; label: string }) {
+  return (
+    <div>
+      <input
+        key={label}
+        value={field.state.value}
+        onBlur={field.handleBlur}
+        onChange={(e) => field.handleChange(e.target.value)}
+        placeholder={label}
+      />
+      {field.state.meta.errors.length > 0 && (
+        <em style={{ color: 'red' }}>
+          {field.state.meta.errors
+            .map((e) => (typeof e === 'string' ? e : e.message))
+            .join(', ')}
+        </em>
+      )}
+    </div>
+  );
+}
+
+export default function App() {
+  const [step, setStep] = React.useState(0);
+
+  const form = useForm({
+    defaultValues: {
+      firstName: '',
+      email: '',
+    } as FormData,
+    validators: { onSubmit: userSchema },
+    onSubmit: async ({ value }) => console.log('Final submit:', value),
+  });
+
+  const steps = [
+    {
+      fields: ['firstName'] as const,
+      component: () => (
+        <form.Field
+          name="firstName"
+          validators={{ onBlur: userSchema.shape.firstName }}
+          children={(f) => <FieldUI field={f} label="First Name" />}
+        />
+      ),
+    },
+    {
+      fields: ['email'] as const,
+      component: () => (
+        <form.Field
+          name="email"
+          validators={{ onBlur: userSchema.shape.email }}
+          children={(f) => <FieldUI field={f} label="Email" />}
+        />
+      ),
+    },
+  ];
+
+  type FormFieldName = DeepKeys<FormData>;
+
+  const validateFieldGroup = async (fields: readonly FormFieldName[]) => {
+    await Promise.all(fields.map((field) => form.validateField(field, 'blur')));
+    return fields.every(
+      (field) => (form.getFieldMeta(field)?.errors.length ?? 0) === 0
+    );
+  };
+
+  const next = async () => {
+    const result = await validateFieldGroup(steps[step].fields);
+    if (result) {
+      setStep((s) => s + 1);
+    }
+  };
+
+  return (
+    <form
+      onSubmit={(e) => {
+        e.preventDefault();
+        form.handleSubmit();
+      }}
+    >
+      {steps[step].component()}
+      <div style={{ marginTop: 20 }}>
+        {step > 0 && (
+          <button
+            key="back"
+            type="button"
+            onClick={() => setStep((s) => s - 1)}
+          >
+            Back
+          </button>
+        )}
+        {step < steps.length - 1 ? (
+          <button key="next" type="button" onClick={next}>
+            Next
+          </button>
+        ) : (
+          <button style={{ marginLeft: 20 }} type="submit">
+            Submit
+          </button>
+        )}
+      </div>
+    </form>
+  );
+}
+
+
+
+const rootElement = document.getElementById('root')!
+
+createRoot(rootElement).render(
+  <React.StrictMode>
+    <App />
+
+    <TanStackDevtools
+      config={{ hideUntilHover: true }}
+      plugins={[formDevtoolsPlugin()]}
+    />
+  </React.StrictMode>,
+)
diff --git a/examples/react/multistep/tsconfig.json b/examples/react/multistep/tsconfig.json
@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "lib": ["DOM", "DOM.Iterable", "ESNext"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src"]
+}