Zod Form Validation Skill

Implements type-safe form validation using Zod schemas with React Hook Form integration in the DTX frontend.

Quick Reference

Form Setup Pattern

import { zodResolver } from '@hookform/resolvers/zod';
import { useForm } from 'react-hook-form';
import { z } from 'zod';
import { Form, FormField, FormItem, FormLabel, FormControl, FormMessage } from '~/components/ui/form';

// 1. Define schema
const MySchema = z.object({
  email: z.string().email('Invalid email'),
  name: z.string().min(2, 'Name too short'),
});

// 2. Create form with zodResolver
const form = useForm<z.infer<typeof MySchema>>({
  resolver: zodResolver(MySchema),
  defaultValues: { email: '', name: '' },
});

// 3. Handle submission
const onSubmit = (data: z.infer<typeof MySchema>) => {
  toast.promise(apiCall(data), {
    loading: 'Saving...',
    success: 'Saved!',
    error: (err) => `Failed: ${err?.response?.data ?? String(err)}`,
  });
};

Form Field Pattern

<FormField
  control={form.control}
  name="email"
  render={({ field }) => (
    <FormItem>
      <FormLabel>Email</FormLabel>
      <FormControl>
        <Input {...field} />
      </FormControl>
      <FormMessage />
    </FormItem>
  )}
/>

Project Conventions

Schema Location

Define schemas in ~/components/<feature>/schemas.ts:

• UserSchema in ~/components/user/schemas.ts
• TeamSchema in ~/components/team/schemas.ts
• GameSchema in ~/components/game/schemas.ts

Type Extraction

Always use z.infer<typeof Schema> for types instead of manual interfaces:

export const UserSchema = z.object({ /* ... */ });
export type UserType = z.infer<typeof UserSchema>;

Error Handling

Wrap mutations in toast.promise():

import { toast } from 'sonner';
import { getLogger } from '~/lib/logger';

const log = getLogger('FormComponent');

toast.promise(apiCall(data), {
  loading: 'Processing...',
  success: (response) => {
    setData(response);
    return 'Success!';
  },
  error: (err) => {
    log.error('API call failed', err);
    return `Failed: ${err?.response?.data ?? String(err)}`;
  },
});

Detailed References

For comprehensive documentation:

• [Zod Schema Patterns](references/zod-schemas.md) - Schema types, validation, composition
• [React Hook Form Integration](references/react-hook-form.md) - Form setup, field types, error handling
• [Form Field Components](references/form-fields.md) - Input, Select, Checkbox patterns

Migration Guide

When migrating legacy forms from manual useState to React Hook Form + Zod:

1. Create/update schema in schemas.ts
2. Replace useState with useForm({ resolver: zodResolver(Schema) })
3. Replace input handlers with <FormField> components
4. Remove manual error state management
5. Wrap form in <Form {...form}> provider

Reference implementation: ~/pages/profile/profile.tsx

Common Patterns

Nested Objects

const Schema = z.object({
  user: z.object({
    name: z.string(),
    email: z.string().email(),
  }),
});

<FormField control={form.control} name="user.name" ... />

Optional & Nullable

const Schema = z.object({
  nickname: z.string().nullable().optional(),
  mmr: z.number().min(0).nullable().optional(),
});

Select Fields (Number Values)

<FormField
  control={form.control}
  name="position"
  render={({ field }) => (
    <Select onValueChange={(v) => field.onChange(Number(v))} defaultValue={field.value?.toString()}>
      {/* options */}
    </Select>
  )}
/>

Dependencies

Required packages (already installed in DTX frontend):

• zod: ^4.1.5
• react-hook-form: ^7.62.0
• @hookform/resolvers: ^5.2.1