React Hook Form Zod

• Create a file named {Feature}Form.schema.ts (or editStop.schema.ts) in the same feature folder as the form.
• Define the schema with z.object({ ... }) and use Zod’s full API:
  • z.string(), z.number(), z.boolean(), z.date(), z.enum(), z.array(), etc.
  • .min(), .max(), .email(), .url(), .optional(), .nullable()
  • .refine() / .superRefine() for cross-field or custom validation
  • .transform() for coercion (use with care with form inputs; prefer parsing at submit if needed)
• Export the schema and the form data type.

// editStop.schema.ts
import { z } from "zod";

export const editStopSchema = z.object({
  id: z.number().nullable(),
  name: z.string().min(1, "Name is required"),
  location: z.string().min(1, "Location is required"),
  county_id: z.number().min(1, "County is required"),
  lat: z.number().min(-90).max(90),
  lng: z.number().min(-180).max(180),
});

export type EditStopFormData = z.infer<typeof editStopSchema>;

• For cross-field validation use .refine():

const schema = z.object({
  password: z.string().min(8),
  confirmPassword: z.string(),
}).refine((data) => data.password === data.confirmPassword, {
  message: "Passwords do not match",
  path: ["confirmPassword"],
});

2. Form setup (useForm)

• Import useForm from react-hook-form, zodResolver from @hookform/resolvers/zod, and the schema + type from the .schema.ts file.
• Initialize with resolver: zodResolver(schema) and defaultValues that match the schema shape (e.g. from an entity or empty defaults).

import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { editStopSchema, type EditStopFormData } from "./editStop.schema";

const { register, handleSubmit, setValue, watch, reset, formState: { errors } } = useForm<EditStopFormData>({
  resolver: zodResolver(editStopSchema),
  defaultValues: {
    id: stop?.id ?? null,
    name: stop?.name ?? "",
    location: stop?.location ?? "",
    county_id: stop?.county_id ?? 0,
    lat: stop?.lat ?? DEFAULT_LAT,
    lng: stop?.lng ?? DEFAULT_LNG,
  },
});

• Use the same EditStopFormData type for handleSubmit(onSubmit) so submit receives typed data.

3. Native and shadcn inputs – use register

• For <input>, <select>, and shadcn components that forward ref and props (e.g. Input), use register.
• Spread {...register("fieldName")} and add validation/options as needed (e.g. valueAsNumber for numbers).

<Input
  id="name"
  {...register("name")}
  placeholder="Enter name"
  className={errors.name ? "border-destructive" : undefined}
  aria-invalid={!!errors.name}
/>
{errors.name && <FieldError errors={[{ message: errors.name.message }]} />}

• For number inputs use valueAsNumber so the form value is a number (matches z.number()):

<Input
  id="lat"
  type="number"
  step="any"
  {...register("lat", { valueAsNumber: true })}
  placeholder="40.7128"
  className={errors.lat ? "border-destructive" : undefined}
  aria-invalid={!!errors.lat}
/>

• If you need to run extra logic on change (e.g. sync local state), call register("field").onChange(e) inside your handler and then call setValue or other logic; keep the field registered.

4. Custom components – use setValue and watch

• For components that are not simple inputs (custom select, autocomplete, map picker, etc.), do not use Controller. Use:
  • Read: watch("fieldName") for the current value.
  • Write: setValue("fieldName", value) in the component’s onChange (optionally with shouldValidate: true).
• Pass value={watch("fieldName")} and onChange={(value) => setValue("fieldName", value)} (or the equivalent for the component’s API).
• Pass the error from errors.fieldName?.message if the component supports an error prop.

const countyValue = watch("county_id");

<SelectDropdown
  options={counties ?? []}
  value={countyValue}
  onChange={(option) => setValue("county_id", option.id)}
  displayKey="name"
  valueKey="id"
  label="County"
  placeholder="Select a county"
  error={errors.county_id?.message}
/>

• For an autocomplete that returns a complex value (e.g. place with lat/lng), call setValue for each form field:

const handlePlaceSelect = (place: PlaceData) => {
  setLocationInput(place.address);
  setValue("location", place.address);
  setValue("lat", place.lat);
  setValue("lng", place.lng);
};

<LocationAutocomplete
  value={locationInput}
  onChange={handlePlaceSelect}
  label="Location"
  error={errors.location?.message}
/>

• For a map marker drag, update only the fields that change:

const latValue = watch("lat");
const lngValue = watch("lng");

const handleMapMarkerDrag = (lat: number, lng: number) => {
  setValue("lat", lat);
  setValue("lng", lng);
};

<MapView
  lat={latValue}
  lng={lngValue}
  onMarkerDragEnd={handleMapMarkerDrag}
/>

5. Submit and reset

• Submit: onSubmit={handleSubmit(onSubmit)} on the <form>. The onSubmit callback receives data typed as the schema’s inferred type.
• Cancel / reset: call reset(defaultValues) with the same shape as defaultValues, then call the parent’s onCancel (or navigate away) so the form is closed or cleared.

const handleCancel = () => {
  reset({
    id: null,
    name: "",
    location: "",
    county_id: 0,
    lat: DEFAULT_LAT,
    lng: DEFAULT_LNG,
  });
  onCancel();
};

6. Error display

• Use formState.errors; each field may have errors.fieldName?.message.
• For shadcn-style fields use Field + FieldLabel + FieldError (or equivalent). Pass errors.fieldName?.message to the component’s error prop when it supports it (e.g. SelectDropdown, LocationAutocomplete).
• Use className={errors.fieldName ? "border-destructive" : undefined} and aria-invalid={!!errors.fieldName} on inputs for accessibility and styling.

Summary

• Schema: in .schema.ts, full Zod API, export schema + z.infer type.
• Form: useForm with zodResolver(schema) and defaultValues; no Controller.
• For more examples see examples.md.