메뉴
Type-safe React forms with React Hook Form and Zod validation. Use for form schemas, field arrays, multi-step forms, or encountering validation errors, resolver issues, nested field problems.
기본적으로 소스를 먼저 확인하는 Prompt가 선택됩니다. 직접 명령으로 전환하거나 로컬 사본을 다운로드할 수도 있습니다.
설치 여부를 결정하기 전에 SKILL.md와 SkillsMP에 표시된 보조 파일을 읽어 보세요.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
직접 명령은 검토 Prompt를 거치지 않습니다. 실행하기 전에 소스를 확인하세요.
npx skills add https://github.com/secondsky/claude-skills --skill react-hook-form-zod명령은 한 줄로 유지됩니다. 복사하기 전에 가로로 스크롤해 전체 내용을 확인하세요.
로컬 사본을 원하시나요? SkillsMP에서 현재 제공할 수 있는 파일을 다운로드하세요.
Use when reworking a change to prevent tech debt, or auditing existing debt to categorize, score, and prioritize the refactor backlog.
Discover and reduce task unknowns — blindspots, missing context, and unknown unknowns — before committing to a plan, implementation, review, or merge.
MUI Base UI unstyled React components with Floating UI. Use for accessible components, Radix UI migration, render props API, or encountering positioning, popup, v1.0 rc / pre-GA issues.
SKILL.md 표시 중
SOC 직업 분류 기준
| name | react-hook-form-zod |
| description | Type-safe React forms with React Hook Form and Zod validation. Use for form schemas, field arrays, multi-step forms, or encountering validation errors, resolver issues, nested field problems. |
| metadata | {"keywords":["react-hook-form","useForm","zod validation","zodResolver","@hookform/resolvers","form schema","register","handleSubmit","formState","useFieldArray","useWatch","useController","Controller","shadcn form","Field component","client server validation","nested validation","array field validation","dynamic fields","multi-step form","async validation","zod refine","z.infer","form error handling","uncontrolled to controlled","resolver not found","schema validation error"]} |
| license | MIT |
Status: Production Ready ✅ Last Updated: 2025-11-21 Dependencies: None (standalone) Latest Versions: react-hook-form@7.84.0, zod@4.3.6, @hookform/resolvers@5.2.2
bun add react-hook-form@7.84.0 zod@4.3.6 @hookform/resolvers@5.2.2
Why These Packages:
import { useForm } from 'react-hook-form'
import { zodResolver } from '@hookform/resolvers/zod'
import { z } from 'zod'
// 1. Define validation schema
const loginSchema = z.object({
email: z.email({ error: 'Invalid email address' }),
password: z.string().min(8, 'Password must be at least 8 characters'),
})
// 2. Infer TypeScript type from schema
type LoginFormData = z.infer<typeof loginSchema>
function LoginForm() {
// 3. Initialize form with zodResolver
const {
register,
handleSubmit,
formState: { errors, isSubmitting },
} = useForm<LoginFormData>({
resolver: zodResolver(loginSchema),
defaultValues: {
email: '',
password: '',
},
})
// 4. Handle form submission
const onSubmit = async (data: LoginFormData) => {
// Data is guaranteed to be valid here
console.log('Valid data:', data)
}
return (
<form onSubmit={handleSubmit(onSubmit)}>
<div>
<label htmlFor="email">Email</label>
<input id="email" type="email" {...register('email')} />
{errors.email && (
<span role="alert" className="error">
{errors.email.message}
</span>
)}
</div>
<div>
<label htmlFor="password">Password</label>
<input id="password" type="password" {...register('password')} />
{errors.password && (
<span role="alert" className="error">
{errors.password.message}
</span>
)}
</div>
<button type= =>
{isSubmitting ? 'Logging in...' : 'Login'}
)
}
CRITICAL:
defaultValues to prevent "uncontrolled to controlled" warningszodResolver(schema) to connect Zod validationz.infer<typeof schema> for full type safetyTemplate: See templates/basic-form.tsx for complete working example
// server/api/login.ts
import { z } from 'zod'
// SAME schema on server
const loginSchema = z.object({
email: z.email({ error: 'Invalid email address' }),
password: z.string().min(8, 'Password must be at least 8 characters'),
})
export async function loginHandler(req: Request) {
try {
const data = loginSchema.parse(await req.json())
// Data is type-safe and validated
return { success: true }
} catch (error) {
if (error instanceof z.ZodError) {
return { success: false, errors: z.flattenError(error).fieldErrors }
}
throw error
}
}
Why Server Validation:
Template: See templates/server-validation.tsx
const {
register, // Register input fields
handleSubmit, // Wrap onSubmit handler
formState, // Form state (errors, isValid, isDirty, etc.)
setValue, // Set field value programmatically
getValues, // Get current form values
watch, // Watch field values
reset, // Reset form to defaults
trigger, // Trigger validation manually
control, // For Controller/useController
} = useForm<FormData>({
resolver: zodResolver(schema),
mode: 'onSubmit', // When to validate
defaultValues: {}, // Initial values (REQUIRED)
})
Validation Modes:
onSubmit - Validate on submit (best performance)onChange - Validate on every change (live feedback)onBlur - Validate when field loses focus (good balance)all - Validate on submit, blur, and changeReference: See references/rhf-api-reference.md for complete API
import { z } from 'zod'
// Basic types
const schema = z.object({
email: z.email({ error: 'Invalid email' }),
age: z.number().min(18, 'Must be 18+'),
terms: z.boolean().refine(val => val === true, 'Must accept terms'),
})
// Nested objects
const addressSchema = z.object({
user: z.object({
name: z.string(),
email: z.email(),
}),
address: z.object({
street: z.string(),
city: z.string(),
zip: z.string().regex(/^\d{5}$/),
}),
})
// Arrays
const tagsSchema = z.object({
tags: z.array(z.string()).min(1, 'At least one tag required'),
})
// Optional and nullable
const optionalSchema = z.object({
middleName: z.string().optional(),
nickname: z.string().nullable(),
bio: z.string().nullish(), // optional AND nullable
})
Reference: See references/zod-schemas-guide.md for complete patterns
✅ Always set defaultValues - Prevents "uncontrolled to controlled" warnings
✅ Use zodResolver for validation - Connects Zod schemas to React Hook Form
✅ Infer types from schema - Use z.infer<typeof schema> for type safety
✅ Validate on server too - Client validation can be bypassed
✅ Use .register() for native inputs - Simple and performant
✅ Use Controller for custom components - For component libraries (MUI, Chakra, etc.)
✅ Handle errors accessibly - Use role="alert" for screen readers
✅ Reset form after submission - Use reset() to clear form state
Form Patterns: See templates/ for:
basic-form.tsx - Simple login/register formsadvanced-form.tsx - Nested objects, arrays, dynamic fieldsshadcn-form.tsx - Integration with shadcn/uimulti-step-form.tsx - Wizard/stepper formsasync-validation.tsx - Async field validation❌ Never skip defaultValues - Causes "uncontrolled to controlled" errors
❌ Never use only client validation - Security vulnerability
❌ Never mutate form values directly - Use setValue() instead
❌ Never ignore accessibility - Always use proper labels and ARIA
❌ Never forget to disable submit when isSubmitting - Prevents double submissions
Performance: See references/performance-optimization.md for:
mode: 'onBlur' vs 'onChange'useWatch vs watch()Accessibility: See references/accessibility.md for:
Error:
Warning: A component is changing an uncontrolled input to be controlled
Cause: Not setting defaultValues
Solution:
// ❌ BAD
const form = useForm()
// ✅ GOOD
const form = useForm({
defaultValues: {
email: '',
password: '',
}
})
Error: Type inference doesn't work correctly
Solution:
// Explicitly type useForm if needed
const form = useForm<z.infer<typeof schema>>({
resolver: zodResolver(schema),
})
Source: GitHub Issue #13109
Error:
Module not found: Can't resolve '@hookform/resolvers/zod'
Solution:
# Install the resolvers package
bun add @hookform/resolvers@5.2.2
Error: Dynamic array fields not working with useFieldArray
Solution:
const { fields, append, remove } = useFieldArray({
control,
name: "items" // Must match schema field name exactly
})
Template: See templates/dynamic-fields.tsx
Error: Third-party component (MUI, Chakra) doesn't validate
Solution:
Use Controller instead of register:
<Controller
name="date"
control={control}
render={({ field }) => (
<DatePicker {...field} />
)}
/>
Reference: See references/error-handling.md for all patterns
All 12 Errors: See references/top-errors.md for complete documentation
import { useForm } from 'react-hook-form'
import { zodResolver } from '@hookform/resolvers/zod'
import { z } from 'zod'
const schema = z.object({
name: z.string().min(1, 'Name required'),
email: z.email({ error: 'Invalid email' }),
})
type FormData = z.infer<typeof schema>
function MyForm() {
const { register, handleSubmit, formState: { errors } } = useForm<FormData>({
resolver: zodResolver(schema),
defaultValues: { name: '', email: '' }
})
const onSubmit = (data: FormData) => console.log(data)
return (
<form onSubmit={handleSubmit(onSubmit)}>
<input {...register('name')} />
{errors.name && <span>{errors.name.message}</span>}
<button type="submit">Submit</button>
</form>
)
}
Template: See templates/basic-form.tsx
import { useForm, useFieldArray } from 'react-hook-form'
const schema = z.object({
items: z.array(
z.object({
name: z.string(),
quantity: z.number().min(1)
})
).min(1, 'At least one item required')
})
function DynamicForm() {
const { control, handleSubmit } = useForm({
resolver: zodResolver(schema),
defaultValues: { items: [{ name: '', quantity: 1 }] }
})
const { fields, append, remove } = useFieldArray({
control,
name: 'items'
})
return (
<form>
{fields.map((field, index) => (
<div key={field.id}>
<input {...register(`items.${index}.name`)} />
<button onClick={() => remove(index)}>Remove</button>
</div>
))}
<button onClick={() => append({ name: '', quantity: 1 })}>
Add Item
</button>
</form>
)
}
Template: See templates/dynamic-fields.tsx
const schema = z.object({
username: z.string()
.min(3)
.refine(async (username) => {
const response = await fetch(`/api/check-username?username=${username}`)
const { available } = await response.json()
return available
}, 'Username already taken')
})
Template: See templates/async-validation.tsx
function MultiStepForm() {
const [step, setStep] = useState(1)
const form = useForm({
resolver: zodResolver(schema),
mode: 'onBlur' // Validate each step before proceeding
})
const onSubmit = async (data) => {
if (step < 3) {
setStep(step + 1)
} else {
// Final submission
await submitForm(data)
}
}
return (
<form onSubmit={form.handleSubmit(onSubmit)}>
{step === 1 && <Step1Fields />}
{step === 2 && <Step2Fields />}
{step === 3 && <Step3Fields />}
<button type="submit">
{step < 3 ? 'Next' : 'Submit'}
</button>
</form>
)
}
Template: See templates/multi-step-form.tsx
import { useForm } from 'react-hook-form'
import { zodResolver } from '@hookform/resolvers/zod'
import { Form, FormControl, FormField, FormItem, FormLabel, FormMessage } from '@/components/ui/form'
function ShadcnForm() {
const form = useForm({
resolver: zodResolver(schema),
defaultValues: { email: '' }
})
return (
<Form {...form}>
<form onSubmit={form.handleSubmit(onSubmit)}>
<FormField
control={form.control}
name="email"
render={({ field }) => (
<FormItem>
<FormLabel>Email</FormLabel>
<FormControl>
<Input {...field} />
</FormControl>
<FormMessage />
</FormItem>
)}
/>
</form>
</Form>
)
}
Reference: See references/shadcn-integration.md for complete patterns
Template: See templates/shadcn-form.tsx
Copy-paste ready examples:
Detailed documentation:
| Reference | Load When... |
|---|---|
top-errors.md | Debugging validation issues, type errors, or "uncontrolled to controlled" warnings |
rhf-api-reference.md | Need complete API for useForm, register, Controller, formState |
zod-schemas-guide.md | Building complex schemas (nested, arrays, conditional, async validation) |
shadcn-integration.md | Using shadcn/ui Form, FormField, FormItem components |
error-handling.md | Custom error display, validation timing, error message patterns |
performance-optimization.md | Form re-renders too much, optimizing watch/useWatch |
accessibility.md | WCAG compliance, screen readers, keyboard navigation |
links-to-official-docs.md | Need official documentation links |
Quick Tips:
mode: 'onBlur' for balance between UX and performanceuseWatch instead of watch() for specific fieldsshouldUnregister: false for conditional fieldswatch() without arguments (watches all fields)Reference: See references/performance-optimization.md for complete strategies
Quick Checklist:
<label htmlFor="fieldId"> for all inputsrole="alert" to error messagesaria-invalid="true" on invalid fieldsReference: See references/accessibility.md for WCAG compliance guide
Common Patterns:
// Email
z.email({ error: 'Invalid email' })
// Password (min 8 chars, 1 uppercase, 1 number)
z.string()
.min(8)
.regex(/[A-Z]/, 'Need uppercase')
.regex(/[0-9]/, 'Need number')
// URL
z.url({ error: 'Invalid URL' })
// Date
z.datetime() // ISO 8601
z.date() // JS Date object
// File upload
z.instanceof(File)
.refine(file => file.size <= 5000000, 'Max 5MB')
.refine(
file => ['image/jpeg', 'image/png'].includes(file.type),
'Only JPEG/PNG allowed'
)
// Custom validation
z.string().refine(
val => val !== 'admin',
'Username "admin" is reserved'
)
// Async validation
z.string().refine(
async (username) => {
const available = await checkUsername(username)
return available
},
'Username already taken'
)
Reference: See references/zod-schemas-guide.md for all patterns
Required:
react-hook-form@7.84.0 - Form state managementzod@4.3.6 - Schema validation@hookform/resolvers@5.2.2 - Validation adapterOptional:
@radix-ui/react-label@latest - For shadcn/ui integrationclass-variance-authority@latest - For shadcn/ui stylingReference: See references/links-to-official-docs.md for organized links
Solution: Always set defaultValues → See references/top-errors.md #2
Solution: Explicitly type useForm<z.infer<typeof schema>> → See references/top-errors.md #1
Solution: Install @hookform/resolvers package → See references/top-errors.md #3
Solution: Use Controller instead of register → See references/top-errors.md #5
Solution: Use mode: 'onBlur' and useWatch → See references/performance-optimization.md
This skill is based on production patterns from:
Token Savings: ~60% (comprehensive form patterns with templates) Error Prevention: 100% (all 12 documented issues with solutions) Ready for production! ✅