[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6E23WQX767TDMF01EV2YFD3":3,"skill-same:01M6E23WQX767TDMF01EV2YFD3":155},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":44,"linkOnly":45,"markdownContent":46,"markdownBody":47,"frontMatter":48,"refName":50,"commitSha":51,"skillDirectory":52,"forksCount":53,"repositoryHtmlUrl":54,"repositoryHomepageUrl":55,"ownerHtmlUrl":56,"ownerBlogUrl":57,"ownerDescription":6,"updatedAt":58,"install":59,"resources":72},"01M6E23WQX767TDMF01EV2YFD3","react-hook-form-zod",null,"Build type-safe validated forms in React using React Hook Form and Zod schema validation. Single schema works on both client and server for DRY validation with full TypeScript type inference via z.infer.\n\nUse when: building forms with validation, integrating shadcn\u002Fui Form components, implementing multi-step wizards, handling dynamic field arrays with useFieldArray, or fixing uncontrolled to controlled warnings, resolver errors, async validation issues.","ByeongminLee\u002Fnextjs-claude-code","ByeongminLee","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F71276006?v=4","01M6E1S467E7GC0NE144SWHC0V","Byeongmin Lee","01M6E1S4AV3W0B08Z2YBK26VG9",3,"MIT","https:\u002F\u002Fgithub.com\u002FByeongminLee\u002Fnextjs-claude-code\u002Fblob\u002Fmain\u002Ftemplate\u002Fskills-archive\u002Freact-hook-form-zod\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000009","前端开发","SCENARIO","使用场景",[24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43],"react hook form zod","react","zod","schema","via","infer","dry","type","full","forms","arrays","async","safe","use","server","ui","shadcn","issues","components","typescript","2026-11-10 10:12:30",false,"---\nname: react-hook-form-zod\ndescription: |\n  Build type-safe validated forms in React using React Hook Form and Zod schema validation. Single schema works on both client and server for DRY validation with full TypeScript type inference via z.infer.\n\n  Use when: building forms with validation, integrating shadcn\u002Fui Form components, implementing multi-step wizards, handling dynamic field arrays with useFieldArray, or fixing uncontrolled to controlled warnings, resolver errors, async validation issues.\n\nlicense: MIT\n---\n\n# React Hook Form + Zod Validation\n\n**Status**: Production Ready ✅\n**Last Updated**: 2025-11-20\n**Dependencies**: None (standalone)\n**Latest Versions**: react-hook-form@7.66.1, zod@4.1.12, @hookform\u002Fresolvers@5.2.2\n\n---\n\n## Quick Start (10 Minutes)\n\n### 1. Install Packages\n\n```bash\nnpm install react-hook-form@7.66.1 zod@4.1.12 @hookform\u002Fresolvers@5.2.2\n```\n\n**Why These Packages**:\n- **react-hook-form**: Performant, flexible form library with minimal re-renders\n- **zod**: TypeScript-first schema validation with type inference\n- **@hookform\u002Fresolvers**: Adapter to connect Zod (and other validators) to React Hook Form\n\n### 2. Create Your First Form\n\n```typescript\nimport { useForm } from 'react-hook-form'\nimport { zodResolver } from '@hookform\u002Fresolvers\u002Fzod'\nimport { z } from 'zod'\n\n\u002F\u002F 1. Define validation schema\nconst loginSchema = z.object({\n  email: z.string().email('Invalid email address'),\n  password: z.string().min(8, 'Password must be at least 8 characters'),\n})\n\n\u002F\u002F 2. Infer TypeScript type from schema\ntype LoginFormData = z.infer\u003Ctypeof loginSchema>\n\nfunction LoginForm() {\n  \u002F\u002F 3. Initialize form with zodResolver\n  const {\n    register,\n    handleSubmit,\n    formState: { errors, isSubmitting },\n  } = useForm\u003CLoginFormData>({\n    resolver: zodResolver(loginSchema),\n    defaultValues: {\n      email: '',\n      password: '',\n    },\n  })\n\n  \u002F\u002F 4. Handle form submission\n  const onSubmit = async (data: LoginFormData) => {\n    \u002F\u002F Data is guaranteed to be valid here\n    console.log('Valid data:', data)\n    \u002F\u002F Make API call, etc.\n  }\n\n  return (\n    \u003Cform onSubmit={handleSubmit(onSubmit)}>\n      \u003Cdiv>\n        \u003Clabel htmlFor=\"email\">Email\u003C\u002Flabel>\n        \u003Cinput id=\"email\" type=\"email\" {...register('email')} \u002F>\n        {errors.email && (\n          \u003Cspan role=\"alert\" className=\"error\">\n            {errors.email.message}\n          \u003C\u002Fspan>\n        )}\n      \u003C\u002Fdiv>\n\n      \u003Cdiv>\n        \u003Clabel htmlFor=\"password\">Password\u003C\u002Flabel>\n        \u003Cinput id=\"password\" type=\"password\" {...register('password')} \u002F>\n        {errors.password && (\n          \u003Cspan role=\"alert\" className=\"error\">\n            {errors.password.message}\n          \u003C\u002Fspan>\n        )}\n      \u003C\u002Fdiv>\n\n      \u003Cbutton type=\"submit\" disabled={isSubmitting}>\n        {isSubmitting ? 'Logging in...' : 'Login'}\n      \u003C\u002Fbutton>\n    \u003C\u002Fform>\n  )\n}\n```\n\n**CRITICAL**:\n- Always set `defaultValues` to prevent \"uncontrolled to controlled\" warnings\n- Use `zodResolver(schema)` to connect Zod validation\n- Type form with `z.infer\u003Ctypeof schema>` for full type safety\n- Validate on both client AND server (never trust client validation alone)\n\n### 3. Add Server-Side Validation\n\n```typescript\n\u002F\u002F server\u002Fapi\u002Flogin.ts\nimport { z } from 'zod'\n\n\u002F\u002F SAME schema on server\nconst loginSchema = z.object({\n  email: z.string().email('Invalid email address'),\n  password: z.string().min(8, 'Password must be at least 8 characters'),\n})\n\nexport async function loginHandler(req: Request) {\n  try {\n    \u002F\u002F Parse and validate request body\n    const data = loginSchema.parse(await req.json())\n\n    \u002F\u002F Data is type-safe and validated\n    \u002F\u002F Proceed with authentication logic\n    return { success: true }\n  } catch (error) {\n    if (error instanceof z.ZodError) {\n      \u002F\u002F Return validation errors to client\n      return { success: false, errors: error.flatten().fieldErrors }\n    }\n    throw error\n  }\n}\n```\n\n**Why Server Validation**:\n- Client validation can be bypassed (inspect element, Postman, curl)\n- Server validation is your security layer\n- Same Zod schema = single source of truth\n- Type safety across frontend and backend\n\n---\n\n## Core Concepts\n\n### useForm Hook Anatomy\n\n```typescript\nconst {\n  register,           \u002F\u002F Register input fields\n  handleSubmit,       \u002F\u002F Wrap onSubmit handler\n  watch,              \u002F\u002F Watch field values\n  formState,          \u002F\u002F Form state (errors, isValid, isDirty, etc.)\n  setValue,           \u002F\u002F Set field value programmatically\n  getValues,          \u002F\u002F Get current form values\n  reset,              \u002F\u002F Reset form to defaults\n  trigger,            \u002F\u002F Trigger validation manually\n  control,            \u002F\u002F Control object for Controller\u002FuseController\n} = useForm\u003CFormData>({\n  resolver: zodResolver(schema),  \u002F\u002F Validation resolver\n  mode: 'onSubmit',               \u002F\u002F When to validate (onSubmit, onChange, onBlur, all)\n  defaultValues: {},              \u002F\u002F Initial values (REQUIRED for controlled inputs)\n})\n```\n\n**useForm Options**:\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `resolver` | Validation resolver (e.g., zodResolver) | undefined |\n| `mode` | When to validate ('onSubmit', 'onChange', 'onBlur', 'all') | 'onSubmit' |\n| `reValidateMode` | When to re-validate after error | 'onChange' |\n| `defaultValues` | Initial form values | {} |\n| `shouldUnregister` | Unregister inputs when unmounted | false |\n| `criteriaMode` | Return all errors or first error only | 'firstError' |\n\n**Form Validation Modes**:\n- `onSubmit` - Validate on submit (best performance, less responsive)\n- `onChange` - Validate on every change (live feedback, more re-renders)\n- `onBlur` - Validate when field loses focus (good balance)\n- `all` - Validate on submit, blur, and change (most responsive, highest cost)\n\n### Zod Schema Definition\n\n```typescript\nimport { z } from 'zod'\n\n\u002F\u002F Primitives\nconst stringSchema = z.string()\nconst numberSchema = z.number()\nconst booleanSchema = z.boolean()\nconst dateSchema = z.date()\n\n\u002F\u002F With validation\nconst emailSchema = z.string().email('Invalid email')\nconst ageSchema = z.number().min(18, 'Must be 18+').max(120, 'Invalid age')\nconst usernameSchema = z.string().min(3).max(20).regex(\u002F^[a-zA-Z0-9_]+$\u002F)\n\n\u002F\u002F Objects\nconst userSchema = z.object({\n  name: z.string(),\n  email: z.string().email(),\n  age: z.number().int().positive(),\n})\n\n\u002F\u002F Arrays\nconst tagsSchema = z.array(z.string())\nconst usersSchema = z.array(userSchema)\n\n\u002F\u002F Optional and Nullable\nconst optionalField = z.string().optional()       \u002F\u002F string | undefined\nconst nullableField = z.string().nullable()       \u002F\u002F string | null\nconst nullishField = z.string().nullish()         \u002F\u002F string | null | undefined\n\n\u002F\u002F Default values\nconst withDefault = z.string().default('default value')\n\n\u002F\u002F Unions\nconst statusSchema = z.union([\n  z.literal('active'),\n  z.literal('inactive'),\n  z.literal('pending'),\n])\n\u002F\u002F Shorthand for literals\nconst statusEnum = z.enum(['active', 'inactive', 'pending'])\n\n\u002F\u002F Nested objects\nconst addressSchema = z.object({\n  street: z.string(),\n  city: z.string(),\n  zipCode: z.string().regex(\u002F^\\d{5}$\u002F),\n})\n\nconst profileSchema = z.object({\n  name: z.string(),\n  address: addressSchema,  \u002F\u002F Nested object\n})\n\n\u002F\u002F Custom error messages\nconst passwordSchema = z.string()\n  .min(8, { message: 'Password must be at least 8 characters' })\n  .regex(\u002F[A-Z]\u002F, { message: 'Password must contain uppercase letter' })\n  .regex(\u002F[0-9]\u002F, { message: 'Password must contain number' })\n```\n\n**Type Inference**:\n```typescript\nconst userSchema = z.object({\n  name: z.string(),\n  age: z.number(),\n})\n\n\u002F\u002F Automatically infer TypeScript type\ntype User = z.infer\u003Ctypeof userSchema>\n\u002F\u002F Result: { name: string; age: number }\n```\n\n### Zod Refinements (Custom Validation)\n\n```typescript\n\u002F\u002F Simple refinement\nconst passwordConfirmSchema = z.object({\n  password: z.string().min(8),\n  confirmPassword: z.string(),\n}).refine((data) => data.password === data.confirmPassword, {\n  message: \"Passwords don't match\",\n  path: ['confirmPassword'], \u002F\u002F Error will appear on confirmPassword field\n})\n\n\u002F\u002F Multiple refinements\nconst signupSchema = z.object({\n  username: z.string(),\n  email: z.string().email(),\n  age: z.number(),\n})\n  .refine((data) => data.username !== data.email.split('@')[0], {\n    message: 'Username cannot be your email prefix',\n    path: ['username'],\n  })\n  .refine((data) => data.age >= 18, {\n    message: 'Must be 18 or older',\n    path: ['age'],\n  })\n\n\u002F\u002F Async refinement (for API checks)\nconst usernameSchema = z.string().refine(async (username) => {\n  \u002F\u002F Check if username is available via API\n  const response = await fetch(`\u002Fapi\u002Fcheck-username?username=${username}`)\n  const { available } = await response.json()\n  return available\n}, {\n  message: 'Username is already taken',\n})\n```\n\n### Zod Transforms (Data Manipulation)\n\n```typescript\n\u002F\u002F Transform string to number\nconst ageSchema = z.string().transform((val) => parseInt(val, 10))\n\n\u002F\u002F Transform to uppercase\nconst uppercaseSchema = z.string().transform((val) => val.toUpperCase())\n\n\u002F\u002F Transform date string to Date object\nconst dateSchema = z.string().transform((val) => new Date(val))\n\n\u002F\u002F Trim whitespace\nconst trimmedSchema = z.string().transform((val) => val.trim())\n\n\u002F\u002F Complex transform\nconst userInputSchema = z.object({\n  email: z.string().email().transform((val) => val.toLowerCase()),\n  tags: z.string().transform((val) => val.split(',').map(tag => tag.trim())),\n})\n\n\u002F\u002F Chain transform and refine\nconst positiveNumberSchema = z.string()\n  .transform((val) => parseFloat(val))\n  .refine((val) => !isNaN(val), { message: 'Must be a number' })\n  .refine((val) => val > 0, { message: 'Must be positive' })\n```\n\n### zodResolver Integration\n\n```typescript\nimport { zodResolver } from '@hookform\u002Fresolvers\u002Fzod'\n\nconst form = useForm\u003CFormData>({\n  resolver: zodResolver(schema),\n})\n```\n\n**What zodResolver Does**:\n1. Takes your Zod schema\n2. Converts it to a format React Hook Form understands\n3. Provides validation function that runs on form submission\n4. Maps Zod errors to React Hook Form error format\n5. Preserves type safety with TypeScript inference\n\n**zodResolver Options**:\n```typescript\nimport { zodResolver } from '@hookform\u002Fresolvers\u002Fzod'\n\n\u002F\u002F With options\nconst form = useForm({\n  resolver: zodResolver(schema, {\n    async: false,     \u002F\u002F Use async validation\n    raw: false,       \u002F\u002F Return raw Zod error\n  }),\n})\n```\n\n---\n\n## Form Registration Patterns\n\n### Pattern 1: Simple Input Registration\n\n```typescript\nfunction BasicForm() {\n  const { register, handleSubmit } = useForm\u003CFormData>({\n    resolver: zodResolver(schema),\n  })\n\n  return (\n    \u003Cform onSubmit={handleSubmit(onSubmit)}>\n      {\u002F* Spread register result to input *\u002F}\n      \u003Cinput {...register('email')} \u002F>\n      \u003Cinput {...register('password')} \u002F>\n\n      {\u002F* With custom props *\u002F}\n      \u003Cinput\n        {...register('username')}\n        placeholder=\"Enter username\"\n        className=\"input\"\n      \u002F>\n    \u003C\u002Fform>\n  )\n}\n```\n\n**What `register()` Returns**:\n```typescript\n{\n  onChange: (e) => void,\n  onBlur: (e) => void,\n  ref: (instance) => void,\n  name: string,\n}\n```\n\n### Pattern 2: Controller (for Custom Components)\n\nUse `Controller` when the input doesn't expose `ref` (like custom components, React Select, date pickers, etc.):\n\n```typescript\nimport { Controller } from 'react-hook-form'\n\nfunction FormWithCustomInput() {\n  const { control, handleSubmit } = useForm\u003CFormData>({\n    resolver: zodResolver(schema),\n  })\n\n  return (\n    \u003Cform onSubmit={handleSubmit(onSubmit)}>\n      \u003CController\n        name=\"category\"\n        control={control}\n        render={({ field }) => (\n          \u003CCustomSelect\n            {...field}                      \u002F\u002F value, onChange, onBlur, ref\n            options={categoryOptions}\n          \u002F>\n        )}\n      \u002F>\n\n      {\u002F* With more control *\u002F}\n      \u003CController\n        name=\"dateOfBirth\"\n        control={control}\n        render={({ field, fieldState }) => (\n          \u003Cdiv>\n            \u003CDatePicker\n              selected={field.value}\n              onChange={field.onChange}\n              onBlur={field.onBlur}\n            \u002F>\n            {fieldState.error && (\n              \u003Cspan>{fieldState.error.message}\u003C\u002Fspan>\n            )}\n          \u003C\u002Fdiv>\n        )}\n      \u002F>\n    \u003C\u002Fform>\n  )\n}\n```\n\n**When to Use Controller**:\n- ✅ Third-party UI libraries (React Select, Material-UI, Ant Design, etc.)\n- ✅ Custom components that don't expose ref\n- ✅ Components that don't use onChange (like checkboxes with custom handlers)\n- ✅ Need fine-grained control over field behavior\n\n**When NOT to Use Controller**:\n- ❌ Standard HTML inputs (use `register` instead - it's simpler and faster)\n- ❌ When performance is critical (Controller adds minimal overhead)\n\n### Pattern 3: useController (Reusable Controlled Inputs)\n\n```typescript\nimport { useController } from 'react-hook-form'\n\n\u002F\u002F Reusable custom input component\nfunction CustomInput({ name, control, label }) {\n  const {\n    field,\n    fieldState: { error },\n  } = useController({\n    name,\n    control,\n    defaultValue: '',\n  })\n\n  return (\n    \u003Cdiv>\n      \u003Clabel>{label}\u003C\u002Flabel>\n      \u003Cinput {...field} \u002F>\n      {error && \u003Cspan>{error.message}\u003C\u002Fspan>}\n    \u003C\u002Fdiv>\n  )\n}\n\n\u002F\u002F Usage\nfunction MyForm() {\n  const { control, handleSubmit } = useForm({\n    resolver: zodResolver(schema),\n  })\n\n  return (\n    \u003Cform onSubmit={handleSubmit(onSubmit)}>\n      \u003CCustomInput name=\"email\" control={control} label=\"Email\" \u002F>\n      \u003CCustomInput name=\"username\" control={control} label=\"Username\" \u002F>\n    \u003C\u002Fform>\n  )\n}\n```\n\n---\n\n## Error Handling\n\n### Displaying Errors\n\n```typescript\nfunction FormWithErrors() {\n  const { register, handleSubmit, formState: { errors } } = useForm\u003CFormData>({\n    resolver: zodResolver(schema),\n  })\n\n  return (\n    \u003Cform onSubmit={handleSubmit(onSubmit)}>\n      \u003Cdiv>\n        \u003Cinput {...register('email')} aria-invalid={errors.email ? 'true' : 'false'} \u002F>\n\n        {\u002F* Simple error display *\u002F}\n        {errors.email && \u003Cspan>{errors.email.message}\u003C\u002Fspan>}\n\n        {\u002F* Accessible error display *\u002F}\n        {errors.email && (\n          \u003Cspan role=\"alert\" className=\"error\">\n            {errors.email.message}\n          \u003C\u002Fspan>\n        )}\n\n        {\u002F* Error with icon *\u002F}\n        {errors.email && (\n          \u003Cdiv role=\"alert\" className=\"error\">\n            \u003CErrorIcon \u002F>\n            \u003Cspan>{errors.email.message}\u003C\u002Fspan>\n          \u003C\u002Fdiv>\n        )}\n      \u003C\u002Fdiv>\n    \u003C\u002Fform>\n  )\n}\n```\n\n### Error Object Structure\n\n```typescript\n\u002F\u002F errors object structure\n{\n  email: {\n    type: 'invalid_string',\n    message: 'Invalid email address',\n  },\n  password: {\n    type: 'too_small',\n    message: 'Password must be at least 8 characters',\n  },\n  \u002F\u002F Nested errors\n  address: {\n    street: {\n      type: 'invalid_type',\n      message: 'Expected string, received undefined',\n    },\n  },\n}\n```\n\n### Form-Level Validation Errors\n\n```typescript\nconst schema = z.object({\n  password: z.string().min(8),\n  confirmPassword: z.string(),\n}).refine((data) => data.password === data.confirmPassword, {\n  message: \"Passwords don't match\",\n  path: ['confirmPassword'], \u002F\u002F Attach error to confirmPassword field\n})\n\n\u002F\u002F Without path - creates root error\n.refine((data) => someCondition, {\n  message: 'Form validation failed',\n})\n\n\u002F\u002F Access root errors\nconst { formState: { errors } } = useForm()\nerrors.root?.message \u002F\u002F Root-level error\n```\n\n### Server Errors Integration\n\n```typescript\nfunction FormWithServerErrors() {\n  const { register, handleSubmit, setError, formState: { errors } } = useForm({\n    resolver: zodResolver(schema),\n  })\n\n  const onSubmit = async (data) => {\n    try {\n      const response = await fetch('\u002Fapi\u002Fsubmit', {\n        method: 'POST',\n        body: JSON.stringify(data),\n      })\n\n      if (!response.ok) {\n        const { errors: serverErrors } = await response.json()\n\n        \u002F\u002F Map server errors to form fields\n        Object.entries(serverErrors).forEach(([field, message]) => {\n          setError(field, {\n            type: 'server',\n            message,\n          })\n        })\n\n        return\n      }\n\n      \u002F\u002F Success!\n    } catch (error) {\n      \u002F\u002F Generic error\n      setError('root', {\n        type: 'server',\n        message: 'An error occurred. Please try again.',\n      })\n    }\n  }\n\n  return (\n    \u003Cform onSubmit={handleSubmit(onSubmit)}>\n      {errors.root && \u003Cdiv role=\"alert\">{errors.root.message}\u003C\u002Fdiv>}\n      {\u002F* ... *\u002F}\n    \u003C\u002Fform>\n  )\n}\n```\n\n---\n\n## Advanced Patterns\n\n### Dynamic Form Fields (useFieldArray)\n\n```typescript\nimport { useForm, useFieldArray } from 'react-hook-form'\nimport { zodResolver } from '@hookform\u002Fresolvers\u002Fzod'\nimport { z } from 'zod'\n\nconst contactSchema = z.object({\n  contacts: z.array(\n    z.object({\n      name: z.string().min(1, 'Name is required'),\n      email: z.string().email('Invalid email'),\n    })\n  ).min(1, 'At least one contact is required'),\n})\n\ntype ContactFormData = z.infer\u003Ctypeof contactSchema>\n\nfunction ContactListForm() {\n  const { register, control, handleSubmit, formState: { errors } } = useForm\u003CContactFormData>({\n    resolver: zodResolver(contactSchema),\n    defaultValues: {\n      contacts: [{ name: '', email: '' }],\n    },\n  })\n\n  const { fields, append, remove } = useFieldArray({\n    control,\n    name: 'contacts',\n  })\n\n  return (\n    \u003Cform onSubmit={handleSubmit(onSubmit)}>\n      {fields.map((field, index) => (\n        \u003Cdiv key={field.id}> {\u002F* IMPORTANT: Use field.id, not index *\u002F}\n          \u003Cinput\n            {...register(`contacts.${index}.name` as const)}\n            placeholder=\"Name\"\n          \u002F>\n          {errors.contacts?.[index]?.name && (\n            \u003Cspan>{errors.contacts[index].name.message}\u003C\u002Fspan>\n          )}\n\n          \u003Cinput\n            {...register(`contacts.${index}.email` as const)}\n            placeholder=\"Email\"\n          \u002F>\n          {errors.contacts?.[index]?.email && (\n            \u003Cspan>{errors.contacts[index].email.message}\u003C\u002Fspan>\n          )}\n\n          \u003Cbutton type=\"button\" onClick={() => remove(index)}>\n            Remove\n          \u003C\u002Fbutton>\n        \u003C\u002Fdiv>\n      ))}\n\n      \u003Cbutton\n        type=\"button\"\n        onClick={() => append({ name: '', email: '' })}\n      >\n        Add Contact\n      \u003C\u002Fbutton>\n\n      \u003Cbutton type=\"submit\">Submit\u003C\u002Fbutton>\n    \u003C\u002Fform>\n  )\n}\n```\n\n**useFieldArray API**:\n- `fields` - Array of field items with unique IDs\n- `append(value)` - Add new item to end\n- `prepend(value)` - Add new item to beginning\n- `insert(index, value)` - Insert item at index\n- `remove(index)` - Remove item at index\n- `update(index, value)` - Update item at index\n- `replace(values)` - Replace entire array\n\n### Async Validation with Debouncing\n\n```typescript\nimport { useForm } from 'react-hook-form'\nimport { zodResolver } from '@hookform\u002Fresolvers\u002Fzod'\nimport { z } from 'zod'\nimport { useDebouncedCallback } from 'use-debounce' \u002F\u002F npm install use-debounce\n\nconst usernameSchema = z.string().min(3).refine(async (username) => {\n  const response = await fetch(`\u002Fapi\u002Fcheck-username?username=${username}`)\n  const { available } = await response.json()\n  return available\n}, {\n  message: 'Username is already taken',\n})\n\nfunction AsyncValidationForm() {\n  const { register, handleSubmit, trigger, formState: { errors, isValidating } } = useForm({\n    resolver: zodResolver(z.object({ username: usernameSchema })),\n    mode: 'onChange', \u002F\u002F Validate on every change\n  })\n\n  \u002F\u002F Debounce validation to avoid too many API calls\n  const debouncedValidation = useDebouncedCallback(() => {\n    trigger('username')\n  }, 500) \u002F\u002F Wait 500ms after user stops typing\n\n  return (\n    \u003Cform onSubmit={handleSubmit(onSubmit)}>\n      \u003Cinput\n        {...register('username')}\n        onChange={(e) => {\n          register('username').onChange(e)\n          debouncedValidation()\n        }}\n      \u002F>\n      {isValidating && \u003Cspan>Checking availability...\u003C\u002Fspan>}\n      {errors.username && \u003Cspan>{errors.username.message}\u003C\u002Fspan>}\n    \u003C\u002Fform>\n  )\n}\n```\n\n### Multi-Step Form (Wizard)\n\n```typescript\nimport { useState } from 'react'\nimport { useForm } from 'react-hook-form'\nimport { zodResolver } from '@hookform\u002Fresolvers\u002Fzod'\nimport { z } from 'zod'\n\n\u002F\u002F Step schemas\nconst step1Schema = z.object({\n  name: z.string().min(1, 'Name is required'),\n  email: z.string().email('Invalid email'),\n})\n\nconst step2Schema = z.object({\n  address: z.string().min(1, 'Address is required'),\n  city: z.string().min(1, 'City is required'),\n})\n\nconst step3Schema = z.object({\n  cardNumber: z.string().regex(\u002F^\\d{16}$\u002F, 'Invalid card number'),\n  cvv: z.string().regex(\u002F^\\d{3,4}$\u002F, 'Invalid CVV'),\n})\n\n\u002F\u002F Combined schema for final validation\nconst fullSchema = step1Schema.merge(step2Schema).merge(step3Schema)\n\ntype FormData = z.infer\u003Ctypeof fullSchema>\n\nfunction MultiStepForm() {\n  const [step, setStep] = useState(1)\n\n  const { register, handleSubmit, trigger, formState: { errors } } = useForm\u003CFormData>({\n    resolver: zodResolver(fullSchema),\n    mode: 'onChange',\n  })\n\n  const nextStep = async () => {\n    let fieldsToValidate: (keyof FormData)[] = []\n\n    if (step === 1) {\n      fieldsToValidate = ['name', 'email']\n    } else if (step === 2) {\n      fieldsToValidate = ['address', 'city']\n    }\n\n    \u002F\u002F Validate current step fields\n    const isValid = await trigger(fieldsToValidate)\n\n    if (isValid) {\n      setStep(step + 1)\n    }\n  }\n\n  const prevStep = () => setStep(step - 1)\n\n  const onSubmit = (data: FormData) => {\n    console.log('Final data:', data)\n  }\n\n  return (\n    \u003Cform onSubmit={handleSubmit(onSubmit)}>\n      {\u002F* Progress indicator *\u002F}\n      \u003Cdiv className=\"progress\">\n        Step {step} of 3\n      \u003C\u002Fdiv>\n\n      {\u002F* Step 1 *\u002F}\n      {step === 1 && (\n        \u003Cdiv>\n          \u003Ch2>Personal Information\u003C\u002Fh2>\n          \u003Cinput {...register('name')} placeholder=\"Name\" \u002F>\n          {errors.name && \u003Cspan>{errors.name.message}\u003C\u002Fspan>}\n\n          \u003Cinput {...register('email')} placeholder=\"Email\" \u002F>\n          {errors.email && \u003Cspan>{errors.email.message}\u003C\u002Fspan>}\n        \u003C\u002Fdiv>\n      )}\n\n      {\u002F* Step 2 *\u002F}\n      {step === 2 && (\n        \u003Cdiv>\n          \u003Ch2>Address\u003C\u002Fh2>\n          \u003Cinput {...register('address')} placeholder=\"Address\" \u002F>\n          {errors.address && \u003Cspan>{errors.address.message}\u003C\u002Fspan>}\n\n          \u003Cinput {...register('city')} placeholder=\"City\" \u002F>\n          {errors.city && \u003Cspan>{errors.city.message}\u003C\u002Fspan>}\n        \u003C\u002Fdiv>\n      )}\n\n      {\u002F* Step 3 *\u002F}\n      {step === 3 && (\n        \u003Cdiv>\n          \u003Ch2>Payment\u003C\u002Fh2>\n          \u003Cinput {...register('cardNumber')} placeholder=\"Card Number\" \u002F>\n          {errors.cardNumber && \u003Cspan>{errors.cardNumber.message}\u003C\u002Fspan>}\n\n          \u003Cinput {...register('cvv')} placeholder=\"CVV\" \u002F>\n          {errors.cvv && \u003Cspan>{errors.cvv.message}\u003C\u002Fspan>}\n        \u003C\u002Fdiv>\n      )}\n\n      {\u002F* Navigation *\u002F}\n      \u003Cdiv>\n        {step > 1 && (\n          \u003Cbutton type=\"button\" onClick={prevStep}>\n            Previous\n          \u003C\u002Fbutton>\n        )}\n        {step \u003C 3 ? (\n          \u003Cbutton type=\"button\" onClick={nextStep}>\n            Next\n          \u003C\u002Fbutton>\n        ) : (\n          \u003Cbutton type=\"submit\">Submit\u003C\u002Fbutton>\n        )}\n      \u003C\u002Fdiv>\n    \u003C\u002Fform>\n  )\n}\n```\n\n### Conditional Validation\n\n```typescript\nimport { z } from 'zod'\n\n\u002F\u002F Schema with conditional validation\nconst formSchema = z.discriminatedUnion('accountType', [\n  z.object({\n    accountType: z.literal('personal'),\n    name: z.string().min(1),\n  }),\n  z.object({\n    accountType: z.literal('business'),\n    companyName: z.string().min(1),\n    taxId: z.string().regex(\u002F^\\d{9}$\u002F),\n  }),\n])\n\n\u002F\u002F Alternative: Using refine\nconst conditionalSchema = z.object({\n  hasDiscount: z.boolean(),\n  discountCode: z.string().optional(),\n}).refine((data) => {\n  \u002F\u002F If hasDiscount is true, discountCode is required\n  if (data.hasDiscount && !data.discountCode) {\n    return false\n  }\n  return true\n}, {\n  message: 'Discount code is required when discount is enabled',\n  path: ['discountCode'],\n})\n```\n\n---\n\n## shadcn\u002Fui Integration\n\n### Using Form Component (Legacy)\n\n```typescript\nimport { zodResolver } from '@hookform\u002Fresolvers\u002Fzod'\nimport { useForm } from 'react-hook-form'\nimport { z } from 'zod'\nimport {\n  Form,\n  FormControl,\n  FormDescription,\n  FormField,\n  FormItem,\n  FormLabel,\n  FormMessage,\n} from '@\u002Fcomponents\u002Fui\u002Fform'\nimport { Input } from '@\u002Fcomponents\u002Fui\u002Finput'\n\nconst formSchema = z.object({\n  username: z.string().min(2, 'Username must be at least 2 characters'),\n  email: z.string().email('Invalid email address'),\n})\n\nfunction ProfileForm() {\n  const form = useForm\u003Cz.infer\u003Ctypeof formSchema>>({\n    resolver: zodResolver(formSchema),\n    defaultValues: {\n      username: '',\n      email: '',\n    },\n  })\n\n  return (\n    \u003CForm {...form}>\n      \u003Cform onSubmit={form.handleSubmit(onSubmit)} className=\"space-y-8\">\n        \u003CFormField\n          control={form.control}\n          name=\"username\"\n          render={({ field }) => (\n            \u003CFormItem>\n              \u003CFormLabel>Username\u003C\u002FFormLabel>\n              \u003CFormControl>\n                \u003CInput placeholder=\"shadcn\" {...field} \u002F>\n              \u003C\u002FFormControl>\n              \u003CFormDescription>\n                This is your public display name.\n              \u003C\u002FFormDescription>\n              \u003CFormMessage \u002F>\n            \u003C\u002FFormItem>\n          )}\n        \u002F>\n\n        \u003CFormField\n          control={form.control}\n          name=\"email\"\n          render={({ field }) => (\n            \u003CFormItem>\n              \u003CFormLabel>Email\u003C\u002FFormLabel>\n              \u003CFormControl>\n                \u003CInput type=\"email\" placeholder=\"email@example.com\" {...field} \u002F>\n              \u003C\u002FFormControl>\n              \u003CFormMessage \u002F>\n            \u003C\u002FFormItem>\n          )}\n        \u002F>\n\n        \u003Cbutton type=\"submit\">Submit\u003C\u002Fbutton>\n      \u003C\u002Fform>\n    \u003C\u002FForm>\n  )\n}\n```\n\n**Note**: shadcn\u002Fui states \"We are not actively developing the Form component anymore.\" They recommend using the Field component for new implementations.\n\n### Using Field Component (Recommended)\n\nCheck shadcn\u002Fui documentation for the latest Field component API as it's the actively maintained approach.\n\n---\n\n## Performance Optimization\n\n### Form Mode Strategies\n\n```typescript\n\u002F\u002F Best performance - validate only on submit\nconst form = useForm({\n  mode: 'onSubmit',\n  resolver: zodResolver(schema),\n})\n\n\u002F\u002F Good balance - validate on blur\nconst form = useForm({\n  mode: 'onBlur',\n  resolver: zodResolver(schema),\n})\n\n\u002F\u002F Live feedback - validate on every change\nconst form = useForm({\n  mode: 'onChange',\n  resolver: zodResolver(schema),\n})\n\n\u002F\u002F Maximum validation - all events\nconst form = useForm({\n  mode: 'all',\n  resolver: zodResolver(schema),\n})\n```\n\n### Controlled vs Uncontrolled Inputs\n\n```typescript\n\u002F\u002F Uncontrolled (better performance) - use register\n\u003Cinput {...register('email')} \u002F>\n\n\u002F\u002F Controlled (more control) - use Controller\n\u003CController\n  name=\"email\"\n  control={control}\n  render={({ field }) => \u003CInput {...field} \u002F>}\n\u002F>\n```\n\n**Recommendation**: Use `register` for standard inputs, `Controller` only when necessary (third-party components, custom behavior).\n\n### Isolation with Controller\n\n```typescript\n\u002F\u002F BAD: Entire form re-renders when any field changes\nfunction BadForm() {\n  const { watch } = useForm()\n  const values = watch() \u002F\u002F Watches ALL fields\n\n  return \u003Cdiv>{JSON.stringify(values)}\u003C\u002Fdiv>\n}\n\n\u002F\u002F GOOD: Only re-render when specific field changes\nfunction GoodForm() {\n  const { watch } = useForm()\n  const email = watch('email') \u002F\u002F Watches only email field\n\n  return \u003Cdiv>{email}\u003C\u002Fdiv>\n}\n```\n\n### shouldUnregister Flag\n\n```typescript\nconst form = useForm({\n  resolver: zodResolver(schema),\n  shouldUnregister: true, \u002F\u002F Remove field data when unmounted\n})\n```\n\n**When to use**:\n- ✅ Multi-step forms where steps have different fields\n- ✅ Conditional fields that should not persist\n- ✅ Want to clear data when component unmounts\n\n**When NOT to use**:\n- ❌ Want to preserve form data when toggling visibility\n- ❌ Navigating between form sections (tabs, accordions)\n\n---\n\n## Accessibility Best Practices\n\n### ARIA Attributes\n\n```typescript\nfunction AccessibleForm() {\n  const { register, handleSubmit, formState: { errors } } = useForm({\n    resolver: zodResolver(schema),\n  })\n\n  return (\n    \u003Cform onSubmit={handleSubmit(onSubmit)}>\n      \u003Cdiv>\n        \u003Clabel htmlFor=\"email\">Email\u003C\u002Flabel>\n        \u003Cinput\n          id=\"email\"\n          {...register('email')}\n          aria-invalid={errors.email ? 'true' : 'false'}\n          aria-describedby={errors.email ? 'email-error' : undefined}\n        \u002F>\n        {errors.email && (\n          \u003Cspan id=\"email-error\" role=\"alert\">\n            {errors.email.message}\n          \u003C\u002Fspan>\n        )}\n      \u003C\u002Fdiv>\n    \u003C\u002Fform>\n  )\n}\n```\n\n### Error Announcements\n\n```typescript\nimport { useEffect } from 'react'\n\nfunction FormWithAnnouncements() {\n  const { formState: { errors, isSubmitted } } = useForm()\n\n  \u002F\u002F Announce errors to screen readers\n  useEffect(() => {\n    if (isSubmitted && Object.keys(errors).length > 0) {\n      const errorCount = Object.keys(errors).length\n      const announcement = `Form submission failed with ${errorCount} error${errorCount > 1 ? 's' : ''}`\n\n      \u002F\u002F Create live region for announcement\n      const liveRegion = document.createElement('div')\n      liveRegion.setAttribute('role', 'alert')\n      liveRegion.setAttribute('aria-live', 'assertive')\n      liveRegion.textContent = announcement\n      document.body.appendChild(liveRegion)\n\n      setTimeout(() => {\n        document.body.removeChild(liveRegion)\n      }, 1000)\n    }\n  }, [errors, isSubmitted])\n\n  return (\n    \u003Cform>\n      {\u002F* ... *\u002F}\n    \u003C\u002Fform>\n  )\n}\n```\n\n### Focus Management\n\n```typescript\nimport { useRef, useEffect } from 'react'\n\nfunction FormWithFocus() {\n  const { handleSubmit, formState: { errors } } = useForm()\n  const firstErrorRef = useRef\u003CHTMLInputElement>(null)\n\n  \u002F\u002F Focus first error field on validation failure\n  useEffect(() => {\n    if (Object.keys(errors).length > 0) {\n      firstErrorRef.current?.focus()\n    }\n  }, [errors])\n\n  return (\n    \u003Cform onSubmit={handleSubmit(onSubmit)}>\n      \u003Cinput\n        {...register('email')}\n        ref={errors.email ? firstErrorRef : undefined}\n      \u002F>\n    \u003C\u002Fform>\n  )\n}\n```\n\n---\n\n## Critical Rules\n\n### Always Do\n\n✅ **Set defaultValues** to prevent \"uncontrolled to controlled\" warnings\n```typescript\nconst form = useForm({\n  defaultValues: { email: '', password: '' }, \u002F\u002F ALWAYS set defaults\n})\n```\n\n✅ **Use zodResolver** for Zod integration\n```typescript\nconst form = useForm({\n  resolver: zodResolver(schema), \u002F\u002F Required for Zod validation\n})\n```\n\n✅ **Type forms with z.infer**\n```typescript\ntype FormData = z.infer\u003Ctypeof schema> \u002F\u002F Automatic type inference\n```\n\n✅ **Validate on both client AND server**\n```typescript\n\u002F\u002F Client\nconst form = useForm({ resolver: zodResolver(schema) })\n\n\u002F\u002F Server\nconst data = schema.parse(await req.json()) \u002F\u002F SAME schema\n```\n\n✅ **Use formState.errors for error display**\n```typescript\n{errors.email && \u003Cspan role=\"alert\">{errors.email.message}\u003C\u002Fspan>}\n```\n\n✅ **Add ARIA attributes for accessibility**\n```typescript\n\u003Cinput\n  {...register('email')}\n  aria-invalid={errors.email ? 'true' : 'false'}\n  aria-describedby=\"email-error\"\n\u002F>\n```\n\n✅ **Use field.id for useFieldArray keys**\n```typescript\n{fields.map((field) => \u003Cdiv key={field.id}>{\u002F* ... *\u002F}\u003C\u002Fdiv>)}\n```\n\n✅ **Debounce async validation**\n```typescript\nconst debouncedValidation = useDebouncedCallback(() => trigger('username'), 500)\n```\n\n### Never Do\n\n❌ **Skip server-side validation** (security vulnerability!)\n```typescript\n\u002F\u002F BAD: Only client validation\nconst form = useForm({ resolver: zodResolver(schema) })\n\u002F\u002F API endpoint has no validation\n\n\u002F\u002F GOOD: Validate on both client and server\nconst form = useForm({ resolver: zodResolver(schema) })\n\u002F\u002F API: schema.parse(data) on server too\n```\n\n❌ **Use Zod v4 without checking type inference**\n```typescript\n\u002F\u002F Issue #13109: Zod v4 has type inference changes\n\u002F\u002F Test your types carefully when upgrading\n```\n\n❌ **Forget to spread {...field} in Controller**\n```typescript\n\u002F\u002F BAD\n\u003CController render={({ field }) => \u003CInput value={field.value} \u002F>} \u002F>\n\n\u002F\u002F GOOD\n\u003CController render={({ field }) => \u003CInput {...field} \u002F>} \u002F>\n```\n\n❌ **Mutate form values directly**\n```typescript\n\u002F\u002F BAD\nconst values = getValues()\nvalues.email = 'new@email.com' \u002F\u002F Direct mutation\n\n\u002F\u002F GOOD\nsetValue('email', 'new@email.com') \u002F\u002F Use setValue\n```\n\n❌ **Use inline validation without debouncing**\n```typescript\n\u002F\u002F BAD: Validates on every keystroke\nconst form = useForm({ mode: 'onChange' })\n\n\u002F\u002F GOOD: Debounce async validation\nconst debouncedTrigger = useDebouncedCallback(() => trigger(), 500)\n```\n\n❌ **Mix controlled and uncontrolled inputs**\n```typescript\n\u002F\u002F BAD: Mixing patterns\n\u003Cinput {...register('email')} value={email} onChange={setEmail} \u002F>\n\n\u002F\u002F GOOD: Choose one pattern\n\u003Cinput {...register('email')} \u002F> \u002F\u002F Uncontrolled\n\u002F\u002F OR\n\u003CController render={({ field }) => \u003CInput {...field} \u002F>} \u002F> \u002F\u002F Controlled\n```\n\n❌ **Use index as key in useFieldArray**\n```typescript\n\u002F\u002F BAD\n{fields.map((field, index) => \u003Cdiv key={index}>{\u002F* ... *\u002F}\u003C\u002Fdiv>)}\n\n\u002F\u002F GOOD\n{fields.map((field) => \u003Cdiv key={field.id}>{\u002F* ... *\u002F}\u003C\u002Fdiv>)}\n```\n\n❌ **Forget defaultValues for all fields**\n```typescript\n\u002F\u002F BAD: Missing defaults causes warnings\nconst form = useForm({\n  resolver: zodResolver(schema),\n})\n\n\u002F\u002F GOOD: Set defaults for all fields\nconst form = useForm({\n  resolver: zodResolver(schema),\n  defaultValues: { email: '', password: '', remember: false },\n})\n```\n\n---\n\n## Known Issues Prevention\n\nThis skill prevents **12** documented issues:\n\n### Issue #1: Zod v4 Type Inference Errors\n**Error**: Type inference doesn't work correctly with Zod v4\n**Source**: [GitHub Issue #13109](https:\u002F\u002Fgithub.com\u002Freact-hook-form\u002Freact-hook-form\u002Fissues\u002F13109) (Closed 2025-11-01)\n**Why It Happens**: Zod v4 changed how types are inferred\n**Prevention**: Use correct type patterns: `type FormData = z.infer\u003Ctypeof schema>`\n**Note**: Resolved in react-hook-form v7.66.x+. Upgrade to latest version to avoid this issue.\n\n### Issue #2: Uncontrolled to Controlled Warning\n**Error**: \"A component is changing an uncontrolled input to be controlled\"\n**Source**: React documentation\n**Why It Happens**: Not setting defaultValues causes undefined -> value transition\n**Prevention**: Always set defaultValues for all fields\n\n### Issue #3: Nested Object Validation Errors\n**Error**: Errors for nested fields don't display correctly\n**Source**: Common React Hook Form issue\n**Why It Happens**: Accessing nested errors incorrectly\n**Prevention**: Use optional chaining: `errors.address?.street?.message`\n\n### Issue #4: Array Field Re-renders\n**Error**: Form re-renders excessively with array fields\n**Source**: Performance issue\n**Why It Happens**: Not using field.id as key\n**Prevention**: Use `key={field.id}` in useFieldArray map\n\n### Issue #5: Async Validation Race Conditions\n**Error**: Multiple validation requests cause conflicting results\n**Source**: Common async pattern issue\n**Why It Happens**: No debouncing or request cancellation\n**Prevention**: Debounce validation and cancel pending requests\n\n### Issue #6: Server Error Mapping\n**Error**: Server validation errors don't map to form fields\n**Source**: Integration issue\n**Why It Happens**: Server error format doesn't match React Hook Form format\n**Prevention**: Use setError() to map server errors to fields\n\n### Issue #7: Default Values Not Applied\n**Error**: Form fields don't show default values\n**Source**: Common mistake\n**Why It Happens**: defaultValues set after form initialization\n**Prevention**: Set defaultValues in useForm options, not useState\n\n### Issue #8: Controller Field Not Updating\n**Error**: Custom component doesn't update when value changes\n**Source**: Common Controller issue\n**Why It Happens**: Not spreading {...field} in render function\n**Prevention**: Always spread {...field} to custom component\n\n### Issue #9: useFieldArray Key Warnings\n**Error**: React warning about duplicate keys in list\n**Source**: React list rendering\n**Why It Happens**: Using array index as key instead of field.id\n**Prevention**: Use field.id: `key={field.id}`\n\n### Issue #10: Schema Refinement Error Paths\n**Error**: Custom validation errors appear at wrong field\n**Source**: Zod refinement behavior\n**Why It Happens**: Not specifying path in refinement options\n**Prevention**: Add path option: `refine(..., { message: '...', path: ['fieldName'] })`\n\n### Issue #11: Transform vs Preprocess Confusion\n**Error**: Data transformation doesn't work as expected\n**Source**: Zod API confusion\n**Why It Happens**: Using wrong method for use case\n**Prevention**: Use transform for output transformation, preprocess for input transformation\n\n### Issue #12: Multiple Resolver Conflicts\n**Error**: Form validation doesn't work with multiple resolvers\n**Source**: Configuration error\n**Why It Happens**: Trying to use multiple validation libraries\n**Prevention**: Use single resolver (zodResolver), combine schemas if needed\n\n---\n\n## Templates\n\nSee the `templates\u002F` directory for working examples:\n\n1. **basic-form.tsx** - Simple login\u002Fsignup form\n2. **advanced-form.tsx** - Nested objects, arrays, conditional fields\n3. **shadcn-form.tsx** - shadcn\u002Fui Form component integration\n4. **server-validation.ts** - Server-side validation with same schema\n5. **async-validation.tsx** - Async validation with debouncing\n6. **dynamic-fields.tsx** - useFieldArray for adding\u002Fremoving items\n7. **multi-step-form.tsx** - Wizard with per-step validation\n8. **custom-error-display.tsx** - Custom error formatting\n9. **package.json** - Complete dependencies\n\n---\n\n## References\n\nSee the `references\u002F` directory for deep-dive documentation:\n\n1. **zod-schemas-guide.md** - Comprehensive Zod schema patterns\n2. **rhf-api-reference.md** - Complete React Hook Form API\n3. **error-handling.md** - Error messages, formatting, accessibility\n4. **accessibility.md** - WCAG compliance, ARIA attributes\n5. **performance-optimization.md** - Form modes, validation strategies\n6. **shadcn-integration.md** - shadcn\u002Fui Form vs Field components\n7. **top-errors.md** - 12 common errors with solutions\n8. **links-to-official-docs.md** - Organized documentation links\n\n---\n\n## Official Documentation\n\n- **React Hook Form**: https:\u002F\u002Freact-hook-form.com\u002F\n- **Zod**: https:\u002F\u002Fzod.dev\u002F\n- **@hookform\u002Fresolvers**: https:\u002F\u002Fgithub.com\u002Freact-hook-form\u002Fresolvers\n- **shadcn\u002Fui Form**: https:\u002F\u002Fui.shadcn.com\u002Fdocs\u002Fcomponents\u002Fform\n\n---\n\n**License**: MIT\n**Last Verified**: 2025-11-20\n**Maintainer**: Jeremy Dawes (jeremy@jezweb.net)\n","# React Hook Form + Zod Validation\n\n**Status**: Production Ready ✅\n**Last Updated**: 2025-11-20\n**Dependencies**: None (standalone)\n**Latest Versions**: react-hook-form@7.66.1, zod@4.1.12, @hookform\u002Fresolvers@5.2.2\n\n---\n\n## Quick Start (10 Minutes)\n\n### 1. Install Packages\n\n```bash\nnpm install react-hook-form@7.66.1 zod@4.1.12 @hookform\u002Fresolvers@5.2.2\n```\n\n**Why These Packages**:\n- **react-hook-form**: Performant, flexible form library with minimal re-renders\n- **zod**: TypeScript-first schema validation with type inference\n- **@hookform\u002Fresolvers**: Adapter to connect Zod (and other validators) to React Hook Form\n\n### 2. Create Your First Form\n\n```typescript\nimport { useForm } from 'react-hook-form'\nimport { zodResolver } from '@hookform\u002Fresolvers\u002Fzod'\nimport { z } from 'zod'\n\n\u002F\u002F 1. Define validation schema\nconst loginSchema = z.object({\n  email: z.string().email('Invalid email address'),\n  password: z.string().min(8, 'Password must be at least 8 characters'),\n})\n\n\u002F\u002F 2. Infer TypeScript type from schema\ntype LoginFormData = z.infer\u003Ctypeof loginSchema>\n\nfunction LoginForm() {\n  \u002F\u002F 3. Initialize form with zodResolver\n  const {\n    register,\n    handleSubmit,\n    formState: { errors, isSubmitting },\n  } = useForm\u003CLoginFormData>({\n    resolver: zodResolver(loginSchema),\n    defaultValues: {\n      email: '',\n      password: '',\n    },\n  })\n\n  \u002F\u002F 4. Handle form submission\n  const onSubmit = async (data: LoginFormData) => {\n    \u002F\u002F Data is guaranteed to be valid here\n    console.log('Valid data:', data)\n    \u002F\u002F Make API call, etc.\n  }\n\n  return (\n    \u003Cform onSubmit={handleSubmit(onSubmit)}>\n      \u003Cdiv>\n        \u003Clabel htmlFor=\"email\">Email\u003C\u002Flabel>\n        \u003Cinput id=\"email\" type=\"email\" {...register('email')} \u002F>\n        {errors.email && (\n          \u003Cspan role=\"alert\" className=\"error\">\n            {errors.email.message}\n          \u003C\u002Fspan>\n        )}\n      \u003C\u002Fdiv>\n\n      \u003Cdiv>\n        \u003Clabel htmlFor=\"password\">Password\u003C\u002Flabel>\n        \u003Cinput id=\"password\" type=\"password\" {...register('password')} \u002F>\n        {errors.password && (\n          \u003Cspan role=\"alert\" className=\"error\">\n            {errors.password.message}\n          \u003C\u002Fspan>\n        )}\n      \u003C\u002Fdiv>\n\n      \u003Cbutton type=\"submit\" disabled={isSubmitting}>\n        {isSubmitting ? 'Logging in...' : 'Login'}\n      \u003C\u002Fbutton>\n    \u003C\u002Fform>\n  )\n}\n```\n\n**CRITICAL**:\n- Always set `defaultValues` to prevent \"uncontrolled to controlled\" warnings\n- Use `zodResolver(schema)` to connect Zod validation\n- Type form with `z.infer\u003Ctypeof schema>` for full type safety\n- Validate on both client AND server (never trust client validation alone)\n\n### 3. Add Server-Side Validation\n\n```typescript\n\u002F\u002F server\u002Fapi\u002Flogin.ts\nimport { z } from 'zod'\n\n\u002F\u002F SAME schema on server\nconst loginSchema = z.object({\n  email: z.string().email('Invalid email address'),\n  password: z.string().min(8, 'Password must be at least 8 characters'),\n})\n\nexport async function loginHandler(req: Request) {\n  try {\n    \u002F\u002F Parse and validate request body\n    const data = loginSchema.parse(await req.json())\n\n    \u002F\u002F Data is type-safe and validated\n    \u002F\u002F Proceed with authentication logic\n    return { success: true }\n  } catch (error) {\n    if (error instanceof z.ZodError) {\n      \u002F\u002F Return validation errors to client\n      return { success: false, errors: error.flatten().fieldErrors }\n    }\n    throw error\n  }\n}\n```\n\n**Why Server Validation**:\n- Client validation can be bypassed (inspect element, Postman, curl)\n- Server validation is your security layer\n- Same Zod schema = single source of truth\n- Type safety across frontend and backend\n\n---\n\n## Core Concepts\n\n### useForm Hook Anatomy\n\n```typescript\nconst {\n  register,           \u002F\u002F Register input fields\n  handleSubmit,       \u002F\u002F Wrap onSubmit handler\n  watch,              \u002F\u002F Watch field values\n  formState,          \u002F\u002F Form state (errors, isValid, isDirty, etc.)\n  setValue,           \u002F\u002F Set field value programmatically\n  getValues,          \u002F\u002F Get current form values\n  reset,              \u002F\u002F Reset form to defaults\n  trigger,            \u002F\u002F Trigger validation manually\n  control,            \u002F\u002F Control object for Controller\u002FuseController\n} = useForm\u003CFormData>({\n  resolver: zodResolver(schema),  \u002F\u002F Validation resolver\n  mode: 'onSubmit',               \u002F\u002F When to validate (onSubmit, onChange, onBlur, all)\n  defaultValues: {},              \u002F\u002F Initial values (REQUIRED for controlled inputs)\n})\n```\n\n**useForm Options**:\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `resolver` | Validation resolver (e.g., zodResolver) | undefined |\n| `mode` | When to validate ('onSubmit', 'onChange', 'onBlur', 'all') | 'onSubmit' |\n| `reValidateMode` | When to re-validate after error | 'onChange' |\n| `defaultValues` | Initial form values | {} |\n| `shouldUnregister` | Unregister inputs when unmounted | false |\n| `criteriaMode` | Return all errors or first error only | 'firstError' |\n\n**Form Validation Modes**:\n- `onSubmit` - Validate on submit (best performance, less responsive)\n- `onChange` - Validate on every change (live feedback, more re-renders)\n- `onBlur` - Validate when field loses focus (good balance)\n- `all` - Validate on submit, blur, and change (most responsive, highest cost)\n\n### Zod Schema Definition\n\n```typescript\nimport { z } from 'zod'\n\n\u002F\u002F Primitives\nconst stringSchema = z.string()\nconst numberSchema = z.number()\nconst booleanSchema = z.boolean()\nconst dateSchema = z.date()\n\n\u002F\u002F With validation\nconst emailSchema = z.string().email('Invalid email')\nconst ageSchema = z.number().min(18, 'Must be 18+').max(120, 'Invalid age')\nconst usernameSchema = z.string().min(3).max(20).regex(\u002F^[a-zA-Z0-9_]+$\u002F)\n\n\u002F\u002F Objects\nconst userSchema = z.object({\n  name: z.string(),\n  email: z.string().email(),\n  age: z.number().int().positive(),\n})\n\n\u002F\u002F Arrays\nconst tagsSchema = z.array(z.string())\nconst usersSchema = z.array(userSchema)\n\n\u002F\u002F Optional and Nullable\nconst optionalField = z.string().optional()       \u002F\u002F string | undefined\nconst nullableField = z.string().nullable()       \u002F\u002F string | null\nconst nullishField = z.string().nullish()         \u002F\u002F string | null | undefined\n\n\u002F\u002F Default values\nconst withDefault = z.string().default('default value')\n\n\u002F\u002F Unions\nconst statusSchema = z.union([\n  z.literal('active'),\n  z.literal('inactive'),\n  z.literal('pending'),\n])\n\u002F\u002F Shorthand for literals\nconst statusEnum = z.enum(['active', 'inactive', 'pending'])\n\n\u002F\u002F Nested objects\nconst addressSchema = z.object({\n  street: z.string(),\n  city: z.string(),\n  zipCode: z.string().regex(\u002F^\\d{5}$\u002F),\n})\n\nconst profileSchema = z.object({\n  name: z.string(),\n  address: addressSchema,  \u002F\u002F Nested object\n})\n\n\u002F\u002F Custom error messages\nconst passwordSchema = z.string()\n  .min(8, { message: 'Password must be at least 8 characters' })\n  .regex(\u002F[A-Z]\u002F, { message: 'Password must contain uppercase letter' })\n  .regex(\u002F[0-9]\u002F, { message: 'Password must contain number' })\n```\n\n**Type Inference**:\n```typescript\nconst userSchema = z.object({\n  name: z.string(),\n  age: z.number(),\n})\n\n\u002F\u002F Automatically infer TypeScript type\ntype User = z.infer\u003Ctypeof userSchema>\n\u002F\u002F Result: { name: string; age: number }\n```\n\n### Zod Refinements (Custom Validation)\n\n```typescript\n\u002F\u002F Simple refinement\nconst passwordConfirmSchema = z.object({\n  password: z.string().min(8),\n  confirmPassword: z.string(),\n}).refine((data) => data.password === data.confirmPassword, {\n  message: \"Passwords don't match\",\n  path: ['confirmPassword'], \u002F\u002F Error will appear on confirmPassword field\n})\n\n\u002F\u002F Multiple refinements\nconst signupSchema = z.object({\n  username: z.string(),\n  email: z.string().email(),\n  age: z.number(),\n})\n  .refine((data) => data.username !== data.email.split('@')[0], {\n    message: 'Username cannot be your email prefix',\n    path: ['username'],\n  })\n  .refine((data) => data.age >= 18, {\n    message: 'Must be 18 or older',\n    path: ['age'],\n  })\n\n\u002F\u002F Async refinement (for API checks)\nconst usernameSchema = z.string().refine(async (username) => {\n  \u002F\u002F Check if username is available via API\n  const response = await fetch(`\u002Fapi\u002Fcheck-username?username=${username}`)\n  const { available } = await response.json()\n  return available\n}, {\n  message: 'Username is already taken',\n})\n```\n\n### Zod Transforms (Data Manipulation)\n\n```typescript\n\u002F\u002F Transform string to number\nconst ageSchema = z.string().transform((val) => parseInt(val, 10))\n\n\u002F\u002F Transform to uppercase\nconst uppercaseSchema = z.string().transform((val) => val.toUpperCase())\n\n\u002F\u002F Transform date string to Date object\nconst dateSchema = z.string().transform((val) => new Date(val))\n\n\u002F\u002F Trim whitespace\nconst trimmedSchema = z.string().transform((val) => val.trim())\n\n\u002F\u002F Complex transform\nconst userInputSchema = z.object({\n  email: z.string().email().transform((val) => val.toLowerCase()),\n  tags: z.string().transform((val) => val.split(',').map(tag => tag.trim())),\n})\n\n\u002F\u002F Chain transform and refine\nconst positiveNumberSchema = z.string()\n  .transform((val) => parseFloat(val))\n  .refine((val) => !isNaN(val), { message: 'Must be a number' })\n  .refine((val) => val > 0, { message: 'Must be positive' })\n```\n\n### zodResolver Integration\n\n```typescript\nimport { zodResolver } from '@hookform\u002Fresolvers\u002Fzod'\n\nconst form = useForm\u003CFormData>({\n  resolver: zodResolver(schema),\n})\n```\n\n**What zodResolver Does**:\n1. Takes your Zod schema\n2. Converts it to a format React Hook Form understands\n3. Provides validation function that runs on form submission\n4. Maps Zod errors to React Hook Form error format\n5. Preserves type safety with TypeScript inference\n\n**zodResolver Options**:\n```typescript\nimport { zodResolver } from '@hookform\u002Fresolvers\u002Fzod'\n\n\u002F\u002F With options\nconst form = useForm({\n  resolver: zodResolver(schema, {\n    async: false,     \u002F\u002F Use async validation\n    raw: false,       \u002F\u002F Return raw Zod error\n  }),\n})\n```\n\n---\n\n## Form Registration Patterns\n\n### Pattern 1: Simple Input Registration\n\n```typescript\nfunction BasicForm() {\n  const { register, handleSubmit } = useForm\u003CFormData>({\n    resolver: zodResolver(schema),\n  })\n\n  return (\n    \u003Cform onSubmit={handleSubmit(onSubmit)}>\n      {\u002F* Spread register result to input *\u002F}\n      \u003Cinput {...register('email')} \u002F>\n      \u003Cinput {...register('password')} \u002F>\n\n      {\u002F* With custom props *\u002F}\n      \u003Cinput\n        {...register('username')}\n        placeholder=\"Enter username\"\n        className=\"input\"\n      \u002F>\n    \u003C\u002Fform>\n  )\n}\n```\n\n**What `register()` Returns**:\n```typescript\n{\n  onChange: (e) => void,\n  onBlur: (e) => void,\n  ref: (instance) => void,\n  name: string,\n}\n```\n\n### Pattern 2: Controller (for Custom Components)\n\nUse `Controller` when the input doesn't expose `ref` (like custom components, React Select, date pickers, etc.):\n\n```typescript\nimport { Controller } from 'react-hook-form'\n\nfunction FormWithCustomInput() {\n  const { control, handleSubmit } = useForm\u003CFormData>({\n    resolver: zodResolver(schema),\n  })\n\n  return (\n    \u003Cform onSubmit={handleSubmit(onSubmit)}>\n      \u003CController\n        name=\"category\"\n        control={control}\n        render={({ field }) => (\n          \u003CCustomSelect\n            {...field}                      \u002F\u002F value, onChange, onBlur, ref\n            options={categoryOptions}\n          \u002F>\n        )}\n      \u002F>\n\n      {\u002F* With more control *\u002F}\n      \u003CController\n        name=\"dateOfBirth\"\n        control={control}\n        render={({ field, fieldState }) => (\n          \u003Cdiv>\n            \u003CDatePicker\n              selected={field.value}\n              onChange={field.onChange}\n              onBlur={field.onBlur}\n            \u002F>\n            {fieldState.error && (\n              \u003Cspan>{fieldState.error.message}\u003C\u002Fspan>\n            )}\n          \u003C\u002Fdiv>\n        )}\n      \u002F>\n    \u003C\u002Fform>\n  )\n}\n```\n\n**When to Use Controller**:\n- ✅ Third-party UI libraries (React Select, Material-UI, Ant Design, etc.)\n- ✅ Custom components that don't expose ref\n- ✅ Components that don't use onChange (like checkboxes with custom handlers)\n- ✅ Need fine-grained control over field behavior\n\n**When NOT to Use Controller**:\n- ❌ Standard HTML inputs (use `register` instead - it's simpler and faster)\n- ❌ When performance is critical (Controller adds minimal overhead)\n\n### Pattern 3: useController (Reusable Controlled Inputs)\n\n```typescript\nimport { useController } from 'react-hook-form'\n\n\u002F\u002F Reusable custom input component\nfunction CustomInput({ name, control, label }) {\n  const {\n    field,\n    fieldState: { error },\n  } = useController({\n    name,\n    control,\n    defaultValue: '',\n  })\n\n  return (\n    \u003Cdiv>\n      \u003Clabel>{label}\u003C\u002Flabel>\n      \u003Cinput {...field} \u002F>\n      {error && \u003Cspan>{error.message}\u003C\u002Fspan>}\n    \u003C\u002Fdiv>\n  )\n}\n\n\u002F\u002F Usage\nfunction MyForm() {\n  const { control, handleSubmit } = useForm({\n    resolver: zodResolver(schema),\n  })\n\n  return (\n    \u003Cform onSubmit={handleSubmit(onSubmit)}>\n      \u003CCustomInput name=\"email\" control={control} label=\"Email\" \u002F>\n      \u003CCustomInput name=\"username\" control={control} label=\"Username\" \u002F>\n    \u003C\u002Fform>\n  )\n}\n```\n\n---\n\n## Error Handling\n\n### Displaying Errors\n\n```typescript\nfunction FormWithErrors() {\n  const { register, handleSubmit, formState: { errors } } = useForm\u003CFormData>({\n    resolver: zodResolver(schema),\n  })\n\n  return (\n    \u003Cform onSubmit={handleSubmit(onSubmit)}>\n      \u003Cdiv>\n        \u003Cinput {...register('email')} aria-invalid={errors.email ? 'true' : 'false'} \u002F>\n\n        {\u002F* Simple error display *\u002F}\n        {errors.email && \u003Cspan>{errors.email.message}\u003C\u002Fspan>}\n\n        {\u002F* Accessible error display *\u002F}\n        {errors.email && (\n          \u003Cspan role=\"alert\" className=\"error\">\n            {errors.email.message}\n          \u003C\u002Fspan>\n        )}\n\n        {\u002F* Error with icon *\u002F}\n        {errors.email && (\n          \u003Cdiv role=\"alert\" className=\"error\">\n            \u003CErrorIcon \u002F>\n            \u003Cspan>{errors.email.message}\u003C\u002Fspan>\n          \u003C\u002Fdiv>\n        )}\n      \u003C\u002Fdiv>\n    \u003C\u002Fform>\n  )\n}\n```\n\n### Error Object Structure\n\n```typescript\n\u002F\u002F errors object structure\n{\n  email: {\n    type: 'invalid_string',\n    message: 'Invalid email address',\n  },\n  password: {\n    type: 'too_small',\n    message: 'Password must be at least 8 characters',\n  },\n  \u002F\u002F Nested errors\n  address: {\n    street: {\n      type: 'invalid_type',\n      message: 'Expected string, received undefined',\n    },\n  },\n}\n```\n\n### Form-Level Validation Errors\n\n```typescript\nconst schema = z.object({\n  password: z.string().min(8),\n  confirmPassword: z.string(),\n}).refine((data) => data.password === data.confirmPassword, {\n  message: \"Passwords don't match\",\n  path: ['confirmPassword'], \u002F\u002F Attach error to confirmPassword field\n})\n\n\u002F\u002F Without path - creates root error\n.refine((data) => someCondition, {\n  message: 'Form validation failed',\n})\n\n\u002F\u002F Access root errors\nconst { formState: { errors } } = useForm()\nerrors.root?.message \u002F\u002F Root-level error\n```\n\n### Server Errors Integration\n\n```typescript\nfunction FormWithServerErrors() {\n  const { register, handleSubmit, setError, formState: { errors } } = useForm({\n    resolver: zodResolver(schema),\n  })\n\n  const onSubmit = async (data) => {\n    try {\n      const response = await fetch('\u002Fapi\u002Fsubmit', {\n        method: 'POST',\n        body: JSON.stringify(data),\n      })\n\n      if (!response.ok) {\n        const { errors: serverErrors } = await response.json()\n\n        \u002F\u002F Map server errors to form fields\n        Object.entries(serverErrors).forEach(([field, message]) => {\n          setError(field, {\n            type: 'server',\n            message,\n          })\n        })\n\n        return\n      }\n\n      \u002F\u002F Success!\n    } catch (error) {\n      \u002F\u002F Generic error\n      setError('root', {\n        type: 'server',\n        message: 'An error occurred. Please try again.',\n      })\n    }\n  }\n\n  return (\n    \u003Cform onSubmit={handleSubmit(onSubmit)}>\n      {errors.root && \u003Cdiv role=\"alert\">{errors.root.message}\u003C\u002Fdiv>}\n      {\u002F* ... *\u002F}\n    \u003C\u002Fform>\n  )\n}\n```\n\n---\n\n## Advanced Patterns\n\n### Dynamic Form Fields (useFieldArray)\n\n```typescript\nimport { useForm, useFieldArray } from 'react-hook-form'\nimport { zodResolver } from '@hookform\u002Fresolvers\u002Fzod'\nimport { z } from 'zod'\n\nconst contactSchema = z.object({\n  contacts: z.array(\n    z.object({\n      name: z.string().min(1, 'Name is required'),\n      email: z.string().email('Invalid email'),\n    })\n  ).min(1, 'At least one contact is required'),\n})\n\ntype ContactFormData = z.infer\u003Ctypeof contactSchema>\n\nfunction ContactListForm() {\n  const { register, control, handleSubmit, formState: { errors } } = useForm\u003CContactFormData>({\n    resolver: zodResolver(contactSchema),\n    defaultValues: {\n      contacts: [{ name: '', email: '' }],\n    },\n  })\n\n  const { fields, append, remove } = useFieldArray({\n    control,\n    name: 'contacts',\n  })\n\n  return (\n    \u003Cform onSubmit={handleSubmit(onSubmit)}>\n      {fields.map((field, index) => (\n        \u003Cdiv key={field.id}> {\u002F* IMPORTANT: Use field.id, not index *\u002F}\n          \u003Cinput\n            {...register(`contacts.${index}.name` as const)}\n            placeholder=\"Name\"\n          \u002F>\n          {errors.contacts?.[index]?.name && (\n            \u003Cspan>{errors.contacts[index].name.message}\u003C\u002Fspan>\n          )}\n\n          \u003Cinput\n            {...register(`contacts.${index}.email` as const)}\n            placeholder=\"Email\"\n          \u002F>\n          {errors.contacts?.[index]?.email && (\n            \u003Cspan>{errors.contacts[index].email.message}\u003C\u002Fspan>\n          )}\n\n          \u003Cbutton type=\"button\" onClick={() => remove(index)}>\n            Remove\n          \u003C\u002Fbutton>\n        \u003C\u002Fdiv>\n      ))}\n\n      \u003Cbutton\n        type=\"button\"\n        onClick={() => append({ name: '', email: '' })}\n      >\n        Add Contact\n      \u003C\u002Fbutton>\n\n      \u003Cbutton type=\"submit\">Submit\u003C\u002Fbutton>\n    \u003C\u002Fform>\n  )\n}\n```\n\n**useFieldArray API**:\n- `fields` - Array of field items with unique IDs\n- `append(value)` - Add new item to end\n- `prepend(value)` - Add new item to beginning\n- `insert(index, value)` - Insert item at index\n- `remove(index)` - Remove item at index\n- `update(index, value)` - Update item at index\n- `replace(values)` - Replace entire array\n\n### Async Validation with Debouncing\n\n```typescript\nimport { useForm } from 'react-hook-form'\nimport { zodResolver } from '@hookform\u002Fresolvers\u002Fzod'\nimport { z } from 'zod'\nimport { useDebouncedCallback } from 'use-debounce' \u002F\u002F npm install use-debounce\n\nconst usernameSchema = z.string().min(3).refine(async (username) => {\n  const response = await fetch(`\u002Fapi\u002Fcheck-username?username=${username}`)\n  const { available } = await response.json()\n  return available\n}, {\n  message: 'Username is already taken',\n})\n\nfunction AsyncValidationForm() {\n  const { register, handleSubmit, trigger, formState: { errors, isValidating } } = useForm({\n    resolver: zodResolver(z.object({ username: usernameSchema })),\n    mode: 'onChange', \u002F\u002F Validate on every change\n  })\n\n  \u002F\u002F Debounce validation to avoid too many API calls\n  const debouncedValidation = useDebouncedCallback(() => {\n    trigger('username')\n  }, 500) \u002F\u002F Wait 500ms after user stops typing\n\n  return (\n    \u003Cform onSubmit={handleSubmit(onSubmit)}>\n      \u003Cinput\n        {...register('username')}\n        onChange={(e) => {\n          register('username').onChange(e)\n          debouncedValidation()\n        }}\n      \u002F>\n      {isValidating && \u003Cspan>Checking availability...\u003C\u002Fspan>}\n      {errors.username && \u003Cspan>{errors.username.message}\u003C\u002Fspan>}\n    \u003C\u002Fform>\n  )\n}\n```\n\n### Multi-Step Form (Wizard)\n\n```typescript\nimport { useState } from 'react'\nimport { useForm } from 'react-hook-form'\nimport { zodResolver } from '@hookform\u002Fresolvers\u002Fzod'\nimport { z } from 'zod'\n\n\u002F\u002F Step schemas\nconst step1Schema = z.object({\n  name: z.string().min(1, 'Name is required'),\n  email: z.string().email('Invalid email'),\n})\n\nconst step2Schema = z.object({\n  address: z.string().min(1, 'Address is required'),\n  city: z.string().min(1, 'City is required'),\n})\n\nconst step3Schema = z.object({\n  cardNumber: z.string().regex(\u002F^\\d{16}$\u002F, 'Invalid card number'),\n  cvv: z.string().regex(\u002F^\\d{3,4}$\u002F, 'Invalid CVV'),\n})\n\n\u002F\u002F Combined schema for final validation\nconst fullSchema = step1Schema.merge(step2Schema).merge(step3Schema)\n\ntype FormData = z.infer\u003Ctypeof fullSchema>\n\nfunction MultiStepForm() {\n  const [step, setStep] = useState(1)\n\n  const { register, handleSubmit, trigger, formState: { errors } } = useForm\u003CFormData>({\n    resolver: zodResolver(fullSchema),\n    mode: 'onChange',\n  })\n\n  const nextStep = async () => {\n    let fieldsToValidate: (keyof FormData)[] = []\n\n    if (step === 1) {\n      fieldsToValidate = ['name', 'email']\n    } else if (step === 2) {\n      fieldsToValidate = ['address', 'city']\n    }\n\n    \u002F\u002F Validate current step fields\n    const isValid = await trigger(fieldsToValidate)\n\n    if (isValid) {\n      setStep(step + 1)\n    }\n  }\n\n  const prevStep = () => setStep(step - 1)\n\n  const onSubmit = (data: FormData) => {\n    console.log('Final data:', data)\n  }\n\n  return (\n    \u003Cform onSubmit={handleSubmit(onSubmit)}>\n      {\u002F* Progress indicator *\u002F}\n      \u003Cdiv className=\"progress\">\n        Step {step} of 3\n      \u003C\u002Fdiv>\n\n      {\u002F* Step 1 *\u002F}\n      {step === 1 && (\n        \u003Cdiv>\n          \u003Ch2>Personal Information\u003C\u002Fh2>\n          \u003Cinput {...register('name')} placeholder=\"Name\" \u002F>\n          {errors.name && \u003Cspan>{errors.name.message}\u003C\u002Fspan>}\n\n          \u003Cinput {...register('email')} placeholder=\"Email\" \u002F>\n          {errors.email && \u003Cspan>{errors.email.message}\u003C\u002Fspan>}\n        \u003C\u002Fdiv>\n      )}\n\n      {\u002F* Step 2 *\u002F}\n      {step === 2 && (\n        \u003Cdiv>\n          \u003Ch2>Address\u003C\u002Fh2>\n          \u003Cinput {...register('address')} placeholder=\"Address\" \u002F>\n          {errors.address && \u003Cspan>{errors.address.message}\u003C\u002Fspan>}\n\n          \u003Cinput {...register('city')} placeholder=\"City\" \u002F>\n          {errors.city && \u003Cspan>{errors.city.message}\u003C\u002Fspan>}\n        \u003C\u002Fdiv>\n      )}\n\n      {\u002F* Step 3 *\u002F}\n      {step === 3 && (\n        \u003Cdiv>\n          \u003Ch2>Payment\u003C\u002Fh2>\n          \u003Cinput {...register('cardNumber')} placeholder=\"Card Number\" \u002F>\n          {errors.cardNumber && \u003Cspan>{errors.cardNumber.message}\u003C\u002Fspan>}\n\n          \u003Cinput {...register('cvv')} placeholder=\"CVV\" \u002F>\n          {errors.cvv && \u003Cspan>{errors.cvv.message}\u003C\u002Fspan>}\n        \u003C\u002Fdiv>\n      )}\n\n      {\u002F* Navigation *\u002F}\n      \u003Cdiv>\n        {step > 1 && (\n          \u003Cbutton type=\"button\" onClick={prevStep}>\n            Previous\n          \u003C\u002Fbutton>\n        )}\n        {step \u003C 3 ? (\n          \u003Cbutton type=\"button\" onClick={nextStep}>\n            Next\n          \u003C\u002Fbutton>\n        ) : (\n          \u003Cbutton type=\"submit\">Submit\u003C\u002Fbutton>\n        )}\n      \u003C\u002Fdiv>\n    \u003C\u002Fform>\n  )\n}\n```\n\n### Conditional Validation\n\n```typescript\nimport { z } from 'zod'\n\n\u002F\u002F Schema with conditional validation\nconst formSchema = z.discriminatedUnion('accountType', [\n  z.object({\n    accountType: z.literal('personal'),\n    name: z.string().min(1),\n  }),\n  z.object({\n    accountType: z.literal('business'),\n    companyName: z.string().min(1),\n    taxId: z.string().regex(\u002F^\\d{9}$\u002F),\n  }),\n])\n\n\u002F\u002F Alternative: Using refine\nconst conditionalSchema = z.object({\n  hasDiscount: z.boolean(),\n  discountCode: z.string().optional(),\n}).refine((data) => {\n  \u002F\u002F If hasDiscount is true, discountCode is required\n  if (data.hasDiscount && !data.discountCode) {\n    return false\n  }\n  return true\n}, {\n  message: 'Discount code is required when discount is enabled',\n  path: ['discountCode'],\n})\n```\n\n---\n\n## shadcn\u002Fui Integration\n\n### Using Form Component (Legacy)\n\n```typescript\nimport { zodResolver } from '@hookform\u002Fresolvers\u002Fzod'\nimport { useForm } from 'react-hook-form'\nimport { z } from 'zod'\nimport {\n  Form,\n  FormControl,\n  FormDescription,\n  FormField,\n  FormItem,\n  FormLabel,\n  FormMessage,\n} from '@\u002Fcomponents\u002Fui\u002Fform'\nimport { Input } from '@\u002Fcomponents\u002Fui\u002Finput'\n\nconst formSchema = z.object({\n  username: z.string().min(2, 'Username must be at least 2 characters'),\n  email: z.string().email('Invalid email address'),\n})\n\nfunction ProfileForm() {\n  const form = useForm\u003Cz.infer\u003Ctypeof formSchema>>({\n    resolver: zodResolver(formSchema),\n    defaultValues: {\n      username: '',\n      email: '',\n    },\n  })\n\n  return (\n    \u003CForm {...form}>\n      \u003Cform onSubmit={form.handleSubmit(onSubmit)} className=\"space-y-8\">\n        \u003CFormField\n          control={form.control}\n          name=\"username\"\n          render={({ field }) => (\n            \u003CFormItem>\n              \u003CFormLabel>Username\u003C\u002FFormLabel>\n              \u003CFormControl>\n                \u003CInput placeholder=\"shadcn\" {...field} \u002F>\n              \u003C\u002FFormControl>\n              \u003CFormDescription>\n                This is your public display name.\n              \u003C\u002FFormDescription>\n              \u003CFormMessage \u002F>\n            \u003C\u002FFormItem>\n          )}\n        \u002F>\n\n        \u003CFormField\n          control={form.control}\n          name=\"email\"\n          render={({ field }) => (\n            \u003CFormItem>\n              \u003CFormLabel>Email\u003C\u002FFormLabel>\n              \u003CFormControl>\n                \u003CInput type=\"email\" placeholder=\"email@example.com\" {...field} \u002F>\n              \u003C\u002FFormControl>\n              \u003CFormMessage \u002F>\n            \u003C\u002FFormItem>\n          )}\n        \u002F>\n\n        \u003Cbutton type=\"submit\">Submit\u003C\u002Fbutton>\n      \u003C\u002Fform>\n    \u003C\u002FForm>\n  )\n}\n```\n\n**Note**: shadcn\u002Fui states \"We are not actively developing the Form component anymore.\" They recommend using the Field component for new implementations.\n\n### Using Field Component (Recommended)\n\nCheck shadcn\u002Fui documentation for the latest Field component API as it's the actively maintained approach.\n\n---\n\n## Performance Optimization\n\n### Form Mode Strategies\n\n```typescript\n\u002F\u002F Best performance - validate only on submit\nconst form = useForm({\n  mode: 'onSubmit',\n  resolver: zodResolver(schema),\n})\n\n\u002F\u002F Good balance - validate on blur\nconst form = useForm({\n  mode: 'onBlur',\n  resolver: zodResolver(schema),\n})\n\n\u002F\u002F Live feedback - validate on every change\nconst form = useForm({\n  mode: 'onChange',\n  resolver: zodResolver(schema),\n})\n\n\u002F\u002F Maximum validation - all events\nconst form = useForm({\n  mode: 'all',\n  resolver: zodResolver(schema),\n})\n```\n\n### Controlled vs Uncontrolled Inputs\n\n```typescript\n\u002F\u002F Uncontrolled (better performance) - use register\n\u003Cinput {...register('email')} \u002F>\n\n\u002F\u002F Controlled (more control) - use Controller\n\u003CController\n  name=\"email\"\n  control={control}\n  render={({ field }) => \u003CInput {...field} \u002F>}\n\u002F>\n```\n\n**Recommendation**: Use `register` for standard inputs, `Controller` only when necessary (third-party components, custom behavior).\n\n### Isolation with Controller\n\n```typescript\n\u002F\u002F BAD: Entire form re-renders when any field changes\nfunction BadForm() {\n  const { watch } = useForm()\n  const values = watch() \u002F\u002F Watches ALL fields\n\n  return \u003Cdiv>{JSON.stringify(values)}\u003C\u002Fdiv>\n}\n\n\u002F\u002F GOOD: Only re-render when specific field changes\nfunction GoodForm() {\n  const { watch } = useForm()\n  const email = watch('email') \u002F\u002F Watches only email field\n\n  return \u003Cdiv>{email}\u003C\u002Fdiv>\n}\n```\n\n### shouldUnregister Flag\n\n```typescript\nconst form = useForm({\n  resolver: zodResolver(schema),\n  shouldUnregister: true, \u002F\u002F Remove field data when unmounted\n})\n```\n\n**When to use**:\n- ✅ Multi-step forms where steps have different fields\n- ✅ Conditional fields that should not persist\n- ✅ Want to clear data when component unmounts\n\n**When NOT to use**:\n- ❌ Want to preserve form data when toggling visibility\n- ❌ Navigating between form sections (tabs, accordions)\n\n---\n\n## Accessibility Best Practices\n\n### ARIA Attributes\n\n```typescript\nfunction AccessibleForm() {\n  const { register, handleSubmit, formState: { errors } } = useForm({\n    resolver: zodResolver(schema),\n  })\n\n  return (\n    \u003Cform onSubmit={handleSubmit(onSubmit)}>\n      \u003Cdiv>\n        \u003Clabel htmlFor=\"email\">Email\u003C\u002Flabel>\n        \u003Cinput\n          id=\"email\"\n          {...register('email')}\n          aria-invalid={errors.email ? 'true' : 'false'}\n          aria-describedby={errors.email ? 'email-error' : undefined}\n        \u002F>\n        {errors.email && (\n          \u003Cspan id=\"email-error\" role=\"alert\">\n            {errors.email.message}\n          \u003C\u002Fspan>\n        )}\n      \u003C\u002Fdiv>\n    \u003C\u002Fform>\n  )\n}\n```\n\n### Error Announcements\n\n```typescript\nimport { useEffect } from 'react'\n\nfunction FormWithAnnouncements() {\n  const { formState: { errors, isSubmitted } } = useForm()\n\n  \u002F\u002F Announce errors to screen readers\n  useEffect(() => {\n    if (isSubmitted && Object.keys(errors).length > 0) {\n      const errorCount = Object.keys(errors).length\n      const announcement = `Form submission failed with ${errorCount} error${errorCount > 1 ? 's' : ''}`\n\n      \u002F\u002F Create live region for announcement\n      const liveRegion = document.createElement('div')\n      liveRegion.setAttribute('role', 'alert')\n      liveRegion.setAttribute('aria-live', 'assertive')\n      liveRegion.textContent = announcement\n      document.body.appendChild(liveRegion)\n\n      setTimeout(() => {\n        document.body.removeChild(liveRegion)\n      }, 1000)\n    }\n  }, [errors, isSubmitted])\n\n  return (\n    \u003Cform>\n      {\u002F* ... *\u002F}\n    \u003C\u002Fform>\n  )\n}\n```\n\n### Focus Management\n\n```typescript\nimport { useRef, useEffect } from 'react'\n\nfunction FormWithFocus() {\n  const { handleSubmit, formState: { errors } } = useForm()\n  const firstErrorRef = useRef\u003CHTMLInputElement>(null)\n\n  \u002F\u002F Focus first error field on validation failure\n  useEffect(() => {\n    if (Object.keys(errors).length > 0) {\n      firstErrorRef.current?.focus()\n    }\n  }, [errors])\n\n  return (\n    \u003Cform onSubmit={handleSubmit(onSubmit)}>\n      \u003Cinput\n        {...register('email')}\n        ref={errors.email ? firstErrorRef : undefined}\n      \u002F>\n    \u003C\u002Fform>\n  )\n}\n```\n\n---\n\n## Critical Rules\n\n### Always Do\n\n✅ **Set defaultValues** to prevent \"uncontrolled to controlled\" warnings\n```typescript\nconst form = useForm({\n  defaultValues: { email: '', password: '' }, \u002F\u002F ALWAYS set defaults\n})\n```\n\n✅ **Use zodResolver** for Zod integration\n```typescript\nconst form = useForm({\n  resolver: zodResolver(schema), \u002F\u002F Required for Zod validation\n})\n```\n\n✅ **Type forms with z.infer**\n```typescript\ntype FormData = z.infer\u003Ctypeof schema> \u002F\u002F Automatic type inference\n```\n\n✅ **Validate on both client AND server**\n```typescript\n\u002F\u002F Client\nconst form = useForm({ resolver: zodResolver(schema) })\n\n\u002F\u002F Server\nconst data = schema.parse(await req.json()) \u002F\u002F SAME schema\n```\n\n✅ **Use formState.errors for error display**\n```typescript\n{errors.email && \u003Cspan role=\"alert\">{errors.email.message}\u003C\u002Fspan>}\n```\n\n✅ **Add ARIA attributes for accessibility**\n```typescript\n\u003Cinput\n  {...register('email')}\n  aria-invalid={errors.email ? 'true' : 'false'}\n  aria-describedby=\"email-error\"\n\u002F>\n```\n\n✅ **Use field.id for useFieldArray keys**\n```typescript\n{fields.map((field) => \u003Cdiv key={field.id}>{\u002F* ... *\u002F}\u003C\u002Fdiv>)}\n```\n\n✅ **Debounce async validation**\n```typescript\nconst debouncedValidation = useDebouncedCallback(() => trigger('username'), 500)\n```\n\n### Never Do\n\n❌ **Skip server-side validation** (security vulnerability!)\n```typescript\n\u002F\u002F BAD: Only client validation\nconst form = useForm({ resolver: zodResolver(schema) })\n\u002F\u002F API endpoint has no validation\n\n\u002F\u002F GOOD: Validate on both client and server\nconst form = useForm({ resolver: zodResolver(schema) })\n\u002F\u002F API: schema.parse(data) on server too\n```\n\n❌ **Use Zod v4 without checking type inference**\n```typescript\n\u002F\u002F Issue #13109: Zod v4 has type inference changes\n\u002F\u002F Test your types carefully when upgrading\n```\n\n❌ **Forget to spread {...field} in Controller**\n```typescript\n\u002F\u002F BAD\n\u003CController render={({ field }) => \u003CInput value={field.value} \u002F>} \u002F>\n\n\u002F\u002F GOOD\n\u003CController render={({ field }) => \u003CInput {...field} \u002F>} \u002F>\n```\n\n❌ **Mutate form values directly**\n```typescript\n\u002F\u002F BAD\nconst values = getValues()\nvalues.email = 'new@email.com' \u002F\u002F Direct mutation\n\n\u002F\u002F GOOD\nsetValue('email', 'new@email.com') \u002F\u002F Use setValue\n```\n\n❌ **Use inline validation without debouncing**\n```typescript\n\u002F\u002F BAD: Validates on every keystroke\nconst form = useForm({ mode: 'onChange' })\n\n\u002F\u002F GOOD: Debounce async validation\nconst debouncedTrigger = useDebouncedCallback(() => trigger(), 500)\n```\n\n❌ **Mix controlled and uncontrolled inputs**\n```typescript\n\u002F\u002F BAD: Mixing patterns\n\u003Cinput {...register('email')} value={email} onChange={setEmail} \u002F>\n\n\u002F\u002F GOOD: Choose one pattern\n\u003Cinput {...register('email')} \u002F> \u002F\u002F Uncontrolled\n\u002F\u002F OR\n\u003CController render={({ field }) => \u003CInput {...field} \u002F>} \u002F> \u002F\u002F Controlled\n```\n\n❌ **Use index as key in useFieldArray**\n```typescript\n\u002F\u002F BAD\n{fields.map((field, index) => \u003Cdiv key={index}>{\u002F* ... *\u002F}\u003C\u002Fdiv>)}\n\n\u002F\u002F GOOD\n{fields.map((field) => \u003Cdiv key={field.id}>{\u002F* ... *\u002F}\u003C\u002Fdiv>)}\n```\n\n❌ **Forget defaultValues for all fields**\n```typescript\n\u002F\u002F BAD: Missing defaults causes warnings\nconst form = useForm({\n  resolver: zodResolver(schema),\n})\n\n\u002F\u002F GOOD: Set defaults for all fields\nconst form = useForm({\n  resolver: zodResolver(schema),\n  defaultValues: { email: '', password: '', remember: false },\n})\n```\n\n---\n\n## Known Issues Prevention\n\nThis skill prevents **12** documented issues:\n\n### Issue #1: Zod v4 Type Inference Errors\n**Error**: Type inference doesn't work correctly with Zod v4\n**Source**: [GitHub Issue #13109](https:\u002F\u002Fgithub.com\u002Freact-hook-form\u002Freact-hook-form\u002Fissues\u002F13109) (Closed 2025-11-01)\n**Why It Happens**: Zod v4 changed how types are inferred\n**Prevention**: Use correct type patterns: `type FormData = z.infer\u003Ctypeof schema>`\n**Note**: Resolved in react-hook-form v7.66.x+. Upgrade to latest version to avoid this issue.\n\n### Issue #2: Uncontrolled to Controlled Warning\n**Error**: \"A component is changing an uncontrolled input to be controlled\"\n**Source**: React documentation\n**Why It Happens**: Not setting defaultValues causes undefined -> value transition\n**Prevention**: Always set defaultValues for all fields\n\n### Issue #3: Nested Object Validation Errors\n**Error**: Errors for nested fields don't display correctly\n**Source**: Common React Hook Form issue\n**Why It Happens**: Accessing nested errors incorrectly\n**Prevention**: Use optional chaining: `errors.address?.street?.message`\n\n### Issue #4: Array Field Re-renders\n**Error**: Form re-renders excessively with array fields\n**Source**: Performance issue\n**Why It Happens**: Not using field.id as key\n**Prevention**: Use `key={field.id}` in useFieldArray map\n\n### Issue #5: Async Validation Race Conditions\n**Error**: Multiple validation requests cause conflicting results\n**Source**: Common async pattern issue\n**Why It Happens**: No debouncing or request cancellation\n**Prevention**: Debounce validation and cancel pending requests\n\n### Issue #6: Server Error Mapping\n**Error**: Server validation errors don't map to form fields\n**Source**: Integration issue\n**Why It Happens**: Server error format doesn't match React Hook Form format\n**Prevention**: Use setError() to map server errors to fields\n\n### Issue #7: Default Values Not Applied\n**Error**: Form fields don't show default values\n**Source**: Common mistake\n**Why It Happens**: defaultValues set after form initialization\n**Prevention**: Set defaultValues in useForm options, not useState\n\n### Issue #8: Controller Field Not Updating\n**Error**: Custom component doesn't update when value changes\n**Source**: Common Controller issue\n**Why It Happens**: Not spreading {...field} in render function\n**Prevention**: Always spread {...field} to custom component\n\n### Issue #9: useFieldArray Key Warnings\n**Error**: React warning about duplicate keys in list\n**Source**: React list rendering\n**Why It Happens**: Using array index as key instead of field.id\n**Prevention**: Use field.id: `key={field.id}`\n\n### Issue #10: Schema Refinement Error Paths\n**Error**: Custom validation errors appear at wrong field\n**Source**: Zod refinement behavior\n**Why It Happens**: Not specifying path in refinement options\n**Prevention**: Add path option: `refine(..., { message: '...', path: ['fieldName'] })`\n\n### Issue #11: Transform vs Preprocess Confusion\n**Error**: Data transformation doesn't work as expected\n**Source**: Zod API confusion\n**Why It Happens**: Using wrong method for use case\n**Prevention**: Use transform for output transformation, preprocess for input transformation\n\n### Issue #12: Multiple Resolver Conflicts\n**Error**: Form validation doesn't work with multiple resolvers\n**Source**: Configuration error\n**Why It Happens**: Trying to use multiple validation libraries\n**Prevention**: Use single resolver (zodResolver), combine schemas if needed\n\n---\n\n## Templates\n\nSee the `templates\u002F` directory for working examples:\n\n1. **basic-form.tsx** - Simple login\u002Fsignup form\n2. **advanced-form.tsx** - Nested objects, arrays, conditional fields\n3. **shadcn-form.tsx** - shadcn\u002Fui Form component integration\n4. **server-validation.ts** - Server-side validation with same schema\n5. **async-validation.tsx** - Async validation with debouncing\n6. **dynamic-fields.tsx** - useFieldArray for adding\u002Fremoving items\n7. **multi-step-form.tsx** - Wizard with per-step validation\n8. **custom-error-display.tsx** - Custom error formatting\n9. **package.json** - Complete dependencies\n\n---\n\n## References\n\nSee the `references\u002F` directory for deep-dive documentation:\n\n1. **zod-schemas-guide.md** - Comprehensive Zod schema patterns\n2. **rhf-api-reference.md** - Complete React Hook Form API\n3. **error-handling.md** - Error messages, formatting, accessibility\n4. **accessibility.md** - WCAG compliance, ARIA attributes\n5. **performance-optimization.md** - Form modes, validation strategies\n6. **shadcn-integration.md** - shadcn\u002Fui Form vs Field components\n7. **top-errors.md** - 12 common errors with solutions\n8. **links-to-official-docs.md** - Organized documentation links\n\n---\n\n## Official Documentation\n\n- **React Hook Form**: https:\u002F\u002Freact-hook-form.com\u002F\n- **Zod**: https:\u002F\u002Fzod.dev\u002F\n- **@hookform\u002Fresolvers**: https:\u002F\u002Fgithub.com\u002Freact-hook-form\u002Fresolvers\n- **shadcn\u002Fui Form**: https:\u002F\u002Fui.shadcn.com\u002Fdocs\u002Fcomponents\u002Fform\n\n---\n\n**License**: MIT\n**Last Verified**: 2025-11-20\n**Maintainer**: Jeremy Dawes (jeremy@jezweb.net)\n",{"name":5,"license":15,"description":49},"Build type-safe validated forms in React using React Hook Form and Zod schema validation. Single schema works on both client and server for DRY validation with full TypeScript type inference via z.infer.\n\nUse when: building forms with validation, integrating shadcn\u002Fui Form components, implementing multi-step wizards, handling dynamic field arrays with useFieldArray, or fixing uncontrolled to controlled warnings, resolver errors, async validation issues.\n","main","330a71e3d12264515ce3477e446d29fd34a88a9d","template\u002Fskills-archive\u002Freact-hook-form-zod",1,"https:\u002F\u002Fgithub.com\u002FByeongminLee\u002Fnextjs-claude-code","https:\u002F\u002Fbyeongminlee.github.io\u002Fnextjs-claude-code\u002F","https:\u002F\u002Fgithub.com\u002FByeongminLee","byeongmin.dev","2026-03-27 12:45:44",{"source":8,"skillName":5,"commands":60,"prompt":70,"zipAvailable":71},[61,64,67],{"tool":62,"command":63},"npx","npx skills add ByeongminLee\u002Fnextjs-claude-code --skill react-hook-form-zod",{"tool":65,"command":66},"bunx","bunx skills add ByeongminLee\u002Fnextjs-claude-code --skill react-hook-form-zod",{"tool":68,"command":69},"pnpm","pnpm dlx skills add ByeongminLee\u002Fnextjs-claude-code --skill react-hook-form-zod","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FByeongminLee\u002Fnextjs-claude-code\u002Fblob\u002Fmain\u002Ftemplate\u002Fskills-archive\u002Freact-hook-form-zod\u002FSKILL.md",true,[73,79,83,87,91,95,99,103,107,111,117,123,127,131,135,139,143,147,151],{"path":74,"resourceType":75,"resourceTypeDesc":76,"sizeBytes":77,"sourceHtmlUrl":78},"README.md","REFERENCE","参考文档",7853,"https:\u002F\u002Fgithub.com\u002FByeongminLee\u002Fnextjs-claude-code\u002Fblob\u002Fmain\u002Ftemplate\u002Fskills-archive\u002Freact-hook-form-zod\u002FREADME.md",{"path":80,"resourceType":75,"resourceTypeDesc":76,"sizeBytes":81,"sourceHtmlUrl":82},"references\u002Faccessibility.md",6451,"https:\u002F\u002Fgithub.com\u002FByeongminLee\u002Fnextjs-claude-code\u002Fblob\u002Fmain\u002Ftemplate\u002Fskills-archive\u002Freact-hook-form-zod\u002Freferences\u002Faccessibility.md",{"path":84,"resourceType":75,"resourceTypeDesc":76,"sizeBytes":85,"sourceHtmlUrl":86},"references\u002Ferror-handling.md",4951,"https:\u002F\u002Fgithub.com\u002FByeongminLee\u002Fnextjs-claude-code\u002Fblob\u002Fmain\u002Ftemplate\u002Fskills-archive\u002Freact-hook-form-zod\u002Freferences\u002Ferror-handling.md",{"path":88,"resourceType":75,"resourceTypeDesc":76,"sizeBytes":89,"sourceHtmlUrl":90},"references\u002Flinks-to-official-docs.md",5690,"https:\u002F\u002Fgithub.com\u002FByeongminLee\u002Fnextjs-claude-code\u002Fblob\u002Fmain\u002Ftemplate\u002Fskills-archive\u002Freact-hook-form-zod\u002Freferences\u002Flinks-to-official-docs.md",{"path":92,"resourceType":75,"resourceTypeDesc":76,"sizeBytes":93,"sourceHtmlUrl":94},"references\u002Fperformance-optimization.md",6746,"https:\u002F\u002Fgithub.com\u002FByeongminLee\u002Fnextjs-claude-code\u002Fblob\u002Fmain\u002Ftemplate\u002Fskills-archive\u002Freact-hook-form-zod\u002Freferences\u002Fperformance-optimization.md",{"path":96,"resourceType":75,"resourceTypeDesc":76,"sizeBytes":97,"sourceHtmlUrl":98},"references\u002Frhf-api-reference.md",7799,"https:\u002F\u002Fgithub.com\u002FByeongminLee\u002Fnextjs-claude-code\u002Fblob\u002Fmain\u002Ftemplate\u002Fskills-archive\u002Freact-hook-form-zod\u002Freferences\u002Frhf-api-reference.md",{"path":100,"resourceType":75,"resourceTypeDesc":76,"sizeBytes":101,"sourceHtmlUrl":102},"references\u002Fshadcn-integration.md",7665,"https:\u002F\u002Fgithub.com\u002FByeongminLee\u002Fnextjs-claude-code\u002Fblob\u002Fmain\u002Ftemplate\u002Fskills-archive\u002Freact-hook-form-zod\u002Freferences\u002Fshadcn-integration.md",{"path":104,"resourceType":75,"resourceTypeDesc":76,"sizeBytes":105,"sourceHtmlUrl":106},"references\u002Ftop-errors.md",7861,"https:\u002F\u002Fgithub.com\u002FByeongminLee\u002Fnextjs-claude-code\u002Fblob\u002Fmain\u002Ftemplate\u002Fskills-archive\u002Freact-hook-form-zod\u002Freferences\u002Ftop-errors.md",{"path":108,"resourceType":75,"resourceTypeDesc":76,"sizeBytes":109,"sourceHtmlUrl":110},"references\u002Fzod-schemas-guide.md",7514,"https:\u002F\u002Fgithub.com\u002FByeongminLee\u002Fnextjs-claude-code\u002Fblob\u002Fmain\u002Ftemplate\u002Fskills-archive\u002Freact-hook-form-zod\u002Freferences\u002Fzod-schemas-guide.md",{"path":112,"resourceType":113,"resourceTypeDesc":114,"sizeBytes":115,"sourceHtmlUrl":116},"scripts\u002Fcheck-versions.sh","SCRIPT","脚本",1180,"https:\u002F\u002Fgithub.com\u002FByeongminLee\u002Fnextjs-claude-code\u002Fblob\u002Fmain\u002Ftemplate\u002Fskills-archive\u002Freact-hook-form-zod\u002Fscripts\u002Fcheck-versions.sh",{"path":118,"resourceType":119,"resourceTypeDesc":120,"sizeBytes":121,"sourceHtmlUrl":122},"templates\u002Fadvanced-form.tsx","OTHER","其他",13399,"https:\u002F\u002Fgithub.com\u002FByeongminLee\u002Fnextjs-claude-code\u002Fblob\u002Fmain\u002Ftemplate\u002Fskills-archive\u002Freact-hook-form-zod\u002Ftemplates\u002Fadvanced-form.tsx",{"path":124,"resourceType":119,"resourceTypeDesc":120,"sizeBytes":125,"sourceHtmlUrl":126},"templates\u002Fasync-validation.tsx",11813,"https:\u002F\u002Fgithub.com\u002FByeongminLee\u002Fnextjs-claude-code\u002Fblob\u002Fmain\u002Ftemplate\u002Fskills-archive\u002Freact-hook-form-zod\u002Ftemplates\u002Fasync-validation.tsx",{"path":128,"resourceType":119,"resourceTypeDesc":120,"sizeBytes":129,"sourceHtmlUrl":130},"templates\u002Fbasic-form.tsx",7964,"https:\u002F\u002Fgithub.com\u002FByeongminLee\u002Fnextjs-claude-code\u002Fblob\u002Fmain\u002Ftemplate\u002Fskills-archive\u002Freact-hook-form-zod\u002Ftemplates\u002Fbasic-form.tsx",{"path":132,"resourceType":119,"resourceTypeDesc":120,"sizeBytes":133,"sourceHtmlUrl":134},"templates\u002Fcustom-error-display.tsx",9951,"https:\u002F\u002Fgithub.com\u002FByeongminLee\u002Fnextjs-claude-code\u002Fblob\u002Fmain\u002Ftemplate\u002Fskills-archive\u002Freact-hook-form-zod\u002Ftemplates\u002Fcustom-error-display.tsx",{"path":136,"resourceType":119,"resourceTypeDesc":120,"sizeBytes":137,"sourceHtmlUrl":138},"templates\u002Fdynamic-fields.tsx",10073,"https:\u002F\u002Fgithub.com\u002FByeongminLee\u002Fnextjs-claude-code\u002Fblob\u002Fmain\u002Ftemplate\u002Fskills-archive\u002Freact-hook-form-zod\u002Ftemplates\u002Fdynamic-fields.tsx",{"path":140,"resourceType":119,"resourceTypeDesc":120,"sizeBytes":141,"sourceHtmlUrl":142},"templates\u002Fmulti-step-form.tsx",12450,"https:\u002F\u002Fgithub.com\u002FByeongminLee\u002Fnextjs-claude-code\u002Fblob\u002Fmain\u002Ftemplate\u002Fskills-archive\u002Freact-hook-form-zod\u002Ftemplates\u002Fmulti-step-form.tsx",{"path":144,"resourceType":75,"resourceTypeDesc":76,"sizeBytes":145,"sourceHtmlUrl":146},"templates\u002Fpackage.json",773,"https:\u002F\u002Fgithub.com\u002FByeongminLee\u002Fnextjs-claude-code\u002Fblob\u002Fmain\u002Ftemplate\u002Fskills-archive\u002Freact-hook-form-zod\u002Ftemplates\u002Fpackage.json",{"path":148,"resourceType":113,"resourceTypeDesc":114,"sizeBytes":149,"sourceHtmlUrl":150},"templates\u002Fserver-validation.ts",8190,"https:\u002F\u002Fgithub.com\u002FByeongminLee\u002Fnextjs-claude-code\u002Fblob\u002Fmain\u002Ftemplate\u002Fskills-archive\u002Freact-hook-form-zod\u002Ftemplates\u002Fserver-validation.ts",{"path":152,"resourceType":119,"resourceTypeDesc":120,"sizeBytes":153,"sourceHtmlUrl":154},"templates\u002Fshadcn-form.tsx",10765,"https:\u002F\u002Fgithub.com\u002FByeongminLee\u002Fnextjs-claude-code\u002Fblob\u002Fmain\u002Ftemplate\u002Fskills-archive\u002Freact-hook-form-zod\u002Ftemplates\u002Fshadcn-form.tsx",[156,174,182,212,240,275],{"skillNo":157,"name":158,"nameZh":6,"description":159,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":160,"categories":161,"keywords":162,"publishedAt":44},"01M6E263DRDCZ5AX01N6MDYC6Z","zustand","Zustand state management guide. Use when working with store code (src\u002Fstore\u002F**), implementing actions, managing state, or creating slices. Triggers on Zustand store development, state management questions, or action implementation.","https:\u002F\u002Fgithub.com\u002FByeongminLee\u002Fnextjs-claude-code\u002Fblob\u002Fmain\u002Ftemplate\u002Fskills-archive\u002Fzustand\u002FSKILL.md",[],[158,163,164,165,166,37,167,168,169,170,171,172,173],"triggers","state management","zustand state","implementation","guide","management","src","actions","state","code","development",{"skillNo":175,"name":176,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":177,"categories":178,"keywords":179,"publishedAt":44},"01M6E260QFP3ZMXY2Y6KTGZYXS","web-vitals","https:\u002F\u002Fgithub.com\u002FByeongminLee\u002Fnextjs-claude-code\u002Fblob\u002Fmain\u002Ftemplate\u002Fskills-archive\u002Fweb-vitals\u002FSKILL.md",[],[180,181],"web vitals","web",{"skillNo":183,"name":184,"nameZh":6,"description":185,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":186,"categories":187,"keywords":191,"publishedAt":44},"01M6E25QEKXHH092S5RB0GKM0K","vercel-storage","Vercel storage expert guidance — Blob, Edge Config, and Marketplace storage (Neon Postgres, Upstash Redis). Use when choosing, configuring, or using data storage with Vercel applications.","https:\u002F\u002Fgithub.com\u002FByeongminLee\u002Fnextjs-claude-code\u002Fblob\u002Fmain\u002Ftemplate\u002Fskills-archive\u002Fvercel-storage\u002FSKILL.md",[188],{"categoryNo":189,"categoryName":190,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000010","后端与接口",[192,193,194,195,196,197,198,199,200,201,202,203,204,205,206,207,208,209,210,211],"vercel","vercel storage","storage","supabase","api","mongodb","SET","nextjs","database","auth","migrate","click","app","neon","prisma","postgres","expert","up","auto","configure",{"skillNo":213,"name":214,"nameZh":6,"description":215,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":216,"categories":217,"keywords":224,"publishedAt":44},"01M6E25EC9YM4QM0KBQ2W5R1SC","vercel-functions","Vercel Functions expert guidance — Serverless Functions, Edge Functions, Fluid Compute, streaming, Cron Jobs, and runtime configuration. Use when configuring, debugging, or optimizing server-side code running on Vercel.","https:\u002F\u002Fgithub.com\u002FByeongminLee\u002Fnextjs-claude-code\u002Fblob\u002Fmain\u002Ftemplate\u002Fskills-archive\u002Fvercel-functions\u002FSKILL.md",[218,219],{"categoryNo":189,"categoryName":190,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":220,"categoryName":221,"taxonomyType":222,"taxonomyTypeDesc":223},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[225,192,226,227,228,229,230,231,204,205,232,233,234,235,38,236,237,238,239,208],"functions","vercel functions","local","shared","project","time","apps","express","vercel ai sdk","router","loop","logs","streaming","delete","create",{"skillNo":241,"name":242,"nameZh":6,"description":243,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":244,"categories":245,"keywords":259,"publishedAt":44},"01M6E25873YRYP96MSQK7E2D9X","ui-ux-pro-max","UI\u002FUX design intelligence for web and mobile. Includes 50+ styles, 161 color palettes, 57 font pairings, 161 product types, 99 UX guidelines, and 25 chart types across 10 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn\u002Fui, and HTML\u002FCSS). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, and check UI\u002FUX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, and mobile app. Elements: button, modal, navbar, sidebar, card, table, form, and chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, and flat design. Topics: color systems, accessibility, animation, layout, typography, font pairing, spacing, interaction states, shadow, and gradient. Integrations: shadcn\u002Fui MCP for component search and examples.","https:\u002F\u002Fgithub.com\u002FByeongminLee\u002Fnextjs-claude-code\u002Fblob\u002Fmain\u002Ftemplate\u002Fskills-archive\u002Fui-ux-pro-max\u002FSKILL.md",[246,247,250,253,256],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":248,"categoryName":249,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000015","视觉设计",{"categoryNo":251,"categoryName":252,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发",{"categoryNo":254,"categoryName":255,"taxonomyType":222,"taxonomyTypeDesc":223},"01JBSEEDCAT000000000000032","设计师",{"categoryNo":257,"categoryName":258,"taxonomyType":222,"taxonomyTypeDesc":223},"01JBSEEDCAT000000000000033","数据分析师",[260,39,261,262,263,264,265,25,204,266,267,268,269,270,271,272,273,170,274,239],"ui ux pro max","ux","max","css","MCP","design","card","chart","fix","projects","plan","improve","Tailwind","Animation","search",{"skillNo":276,"name":277,"nameZh":6,"description":278,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":279,"categories":280,"keywords":281,"publishedAt":44},"01M6E251G3FJSRB9019V20QK9X","turborepo","Turborepo monorepo build system guidance. Triggers on: turbo.json, task pipelines,\ndependsOn, caching, remote cache, the \"turbo\" CLI, --filter, --affected, CI optimization, environment\nvariables, internal packages, monorepo structure\u002Fbest practices, and boundaries.\n\nUse when user: configures tasks\u002Fworkflows\u002Fpipelines, creates packages, sets up\nmonorepo, shares code between apps, runs changed\u002Faffected packages, debugs cache,\nor has apps\u002Fpackages directories.","https:\u002F\u002Fgithub.com\u002FByeongminLee\u002Fnextjs-claude-code\u002Fblob\u002Fmain\u002Ftemplate\u002Fskills-archive\u002Fturborepo\u002FSKILL.md",[],[277,282,37,283,284,231,163,285,286,209,287,288,289,290,291,292,172,293,294,295],"cli","filter","environment variables","caching","structure","environment","monorepo","system","canary","Optimization","ci","packages","tasks","workflows"]