Cursor rule

1---
2description: Form handling patterns with React Hook Form and Zod validation
3globs: ["src/components/forms/**/*.tsx", "src/lib/validations/**/*.ts"]
4alwaysApply: false
5---
6 
7# Form Handling Rules
8 
9## React Hook Form + Zod Pattern
10 
11### Basic Form Setup
12```tsx
13// components/forms/UserForm.tsx
14interface UserFormProps {
15  onSubmit: (data: UserFormData) => void
16  initialData?: Partial<User>
17  isLoading?: boolean
18}
19 
20export const UserForm = ({ onSubmit, initialData, isLoading }: UserFormProps) => {
21  const form = useForm<UserFormData>({
22    resolver: zodResolver(userSchema),
23    defaultValues: {
24      name: initialData?.name || '',
25      email: initialData?.email || '',
26      phone: initialData?.phone || '',
27    }
28  })
29 
30  return (
31    <Form {...form}>
32      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-6">
33        <FormField
34          control={form.control}
35          name="name"
36          render={({ field }) => (
37            <FormItem>
38              <FormLabel>Full Name</FormLabel>
39              <FormControl>
40                <Input placeholder="Enter full name" {...field} />
41              </FormControl>
42              <FormMessage />
43            </FormItem>
44          )}
45        />
46        
47        <FormField
48          control={form.control}
49          name="email"
50          render={({ field }) => (
51            <FormItem>
52              <FormLabel>Email</FormLabel>
53              <FormControl>
54                <Input type="email" placeholder="Enter email" {...field} />
55              </FormControl>
56              <FormMessage />
57            </FormItem>
58          )}
59        />
60        
61        <Button type="submit" disabled={isLoading} className="w-full">
62          {isLoading ? 'Saving...' : 'Save User'}
63        </Button>
64      </form>
65    </Form>
66  )
67}
68```
69 
70### Form Hook Pattern
71```tsx
72// hooks/useUserForm.ts
73export const useUserForm = (userId?: string) => {
74  const { data: user } = useUser(userId)
75  const createUser = useCreateUser()
76  const updateUser = useUpdateUser()
77  
78  const form = useForm<UserFormData>({
79    resolver: zodResolver(userSchema),
80    defaultValues: {
81      name: '',
82      email: '',
83      phone: '',
84    }
85  })
86  
87  // Reset form when user data loads
88  useEffect(() => {
89    if (user) {
90      form.reset({
91        name: user.name,
92        email: user.email,
93        phone: user.phone || '',
94      })
95    }
96  }, [user, form])
97  
98  const handleSubmit = (data: UserFormData) => {
99    if (userId) {
100      updateUser.mutate({ id: userId, data })
101    } else {
102      createUser.mutate(data)
103    }
104  }
105  
106  const isLoading = createUser.isPending || updateUser.isPending
107  
108  return {
109    form,
110    handleSubmit,
111    isLoading,
112    reset: form.reset,
113  }
114}
115```
116 
117### Advanced Form Patterns
118 
119#### Multi-Step Form
120```tsx
121// hooks/useMultiStepForm.ts
122export const useMultiStepForm = <T extends Record<string, any>>(
123  steps: Array<{ key: string; schema: ZodSchema<any> }>,
124  onComplete: (data: T) => void
125) => {
126  const [currentStep, setCurrentStep] = useState(0)
127  const [formData, setFormData] = useState<Partial<T>>({})
128  
129  const currentStepConfig = steps[currentStep]
130  
131  const form = useForm({
132    resolver: zodResolver(currentStepConfig.schema),
133    defaultValues: formData[currentStepConfig.key] || {}
134  })
135  
136  const nextStep = (data: any) => {
137    setFormData(prev => ({ ...prev, [currentStepConfig.key]: data }))
138    
139    if (currentStep < steps.length - 1) {
140      setCurrentStep(prev => prev + 1)
141    } else {
142      onComplete({ ...formData, [currentStepConfig.key]: data } as T)
143    }
144  }
145  
146  const prevStep = () => {
147    if (currentStep > 0) {
148      setCurrentStep(prev => prev - 1)
149    }
150  }
151  
152  return {
153    form,
154    currentStep,
155    totalSteps: steps.length,
156    isFirstStep: currentStep === 0,
157    isLastStep: currentStep === steps.length - 1,
158    nextStep,
159    prevStep,
160    handleSubmit: form.handleSubmit(nextStep)
161  }
162}
163```
164 
165#### Dynamic Form Fields
166```tsx
167// components/forms/DynamicFieldArray.tsx
168export const DynamicFieldArray = ({ name, control }: DynamicFieldArrayProps) => {
169  const { fields, append, remove } = useFieldArray({
170    control,
171    name,
172  })
173 
174  return (
175    <div className="space-y-4">
176      {fields.map((field, index) => (
177        <div key={field.id} className="flex gap-2 items-end">
178          <FormField
179            control={control}
180            name={`${name}.${index}.value`}
181            render={({ field }) => (
182              <FormItem className="flex-1">
183                <FormLabel>Item {index + 1}</FormLabel>
184                <FormControl>
185                  <Input {...field} />
186                </FormControl>
187                <FormMessage />
188              </FormItem>
189            )}
190          />
191          <Button
192            type="button"
193            variant="outline"
194            size="icon"
195            onClick={() => remove(index)}
196          >
197            <X className="h-4 w-4" />
198          </Button>
199        </div>
200      ))}
201      
202      <Button
203        type="button"
204        variant="outline"
205        onClick={() => append({ value: '' })}
206      >
207        <Plus className="h-4 w-4 mr-2" />
208        Add Item
209      </Button>
210    </div>
211  )
212}
213```
214 
215### Form Validation Rules
216 
217#### Complex Validation Schema
218```tsx
219// lib/validations/userProfile.ts
220export const userProfileSchema = z.object({
221  personal: z.object({
222    firstName: z.string().min(2, 'First name required'),
223    lastName: z.string().min(2, 'Last name required'),
224    email: emailSchema,
225    phone: phoneSchema.optional(),
226    dateOfBirth: z.string().optional(),
227  }),
228  address: z.object({
229    street: z.string().min(5, 'Street address required'),
230    city: z.string().min(2, 'City required'),
231    state: z.string().min(2, 'State required'),
232    zipCode: z.string().regex(/^\d{5}(-\d{4})?$/, 'Invalid zip code'),
233    country: z.string().min(2, 'Country required'),
234  }),
235  preferences: z.object({
236    newsletter: z.boolean().default(false),
237    notifications: z.boolean().default(true),
238    theme: z.enum(['light', 'dark', 'system']).default('system'),
239  })
240})
241```
242 
243#### Conditional Validation
244```tsx
245export const conditionalSchema = z.object({
246  userType: z.enum(['individual', 'business']),
247  email: emailSchema,
248  companyName: z.string().optional(),
249  taxId: z.string().optional(),
250}).refine(
251  (data) => {
252    if (data.userType === 'business') {
253      return data.companyName && data.taxId
254    }
255    return true
256  },
257  {
258    message: "Company name and tax ID required for business accounts",
259    path: ["companyName"],
260  }
261)
262```
263 
264## Form Anti-Patterns
265- Manual form state management
266- Inline validation logic
267- No error handling
268- Uncontrolled components mixing with controlled
269- No loading states during submission
270 
271## Form Best Practices
272- Always use React Hook Form + Zod
273- Extract form logic to custom hooks
274- Provide loading states during submission
275- Reset forms after successful submission
276- Handle both client and server validation errors
277