dust-tt

react-hook-form-writer

@dust-tt/react-hook-form-writer
dust-tt
1,268
195 forks
Updated 1/18/2026
View on GitHub

Write and refactor React forms using react-hook-form with Zod validation. Use when creating new form components, converting existing forms to react-hook-form, or implementing form validation patterns.

Installation

$skills install @dust-tt/react-hook-form-writer
Claude Code
Cursor
Copilot
Codex
Antigravity

Details

Repositorydust-tt/dust
Path.claude/skills/dust-react-hook-form-writer/SKILL.md
Branchmain
Scoped Name@dust-tt/react-hook-form-writer

Usage

After installing, this skill will be available to your AI coding assistant.

Verify installation:

skills list

Skill Instructions

name: react-hook-form-writer description: Write and refactor React forms using react-hook-form with Zod validation. Use when creating new form components, converting existing forms to react-hook-form, or implementing form validation patterns.

React Hook Form Writer

This skill helps you write new forms and refactor existing forms to use react-hook-form following project best practices.

When to Use

  • Creating new form components from scratch
  • Converting existing forms to react-hook-form
  • Adding validation to forms
  • Implementing complex form patterns (nested forms, field arrays, multi-step)

Core Principles

1. Always Use Zod for Validation

Define schemas with Zod and integrate via zodResolver:

import { z } from "zod";
import { zodResolver } from "@hookform/resolvers/zod";

const formSchema = z.object({
  name: z.string().min(1, "Name is required"),
  email: z.string().email("Invalid email address"),
  age: z.number().min(18, "Must be at least 18"),
});

type FormValues = z.infer<typeof formSchema>;

const form = useForm<FormValues>({
  resolver: zodResolver(formSchema),
  defaultValues: {
    name: "",
    email: "",
    age: 18,
  },
});

2. Prefer useController Over Controller

Use useController hook for better composability in custom field components:

// Good: useController
function TextField({ name, control, label }: TextFieldProps) {
  const { field, fieldState } = useController({ name, control });

  return (
    <div>
      <label>{label}</label>
      <input {...field} />
      {fieldState.error && <span>{fieldState.error.message}</span>}
    </div>
  );
}

// Avoid: Controller component (less composable)
<Controller
  name="name"
  control={control}
  render={({ field }) => <input {...field} />}
/>

3. Uncontrolled by Default

Leverage react-hook-form's uncontrolled approach for native inputs:

// Good: Uncontrolled with register
<input {...register("name")} />

// Only use Controller/useController for third-party controlled components
// (e.g., shadcn Select, custom date pickers, rich text editors)

4. Use field.onChange, NOT setValue

When working with useController, always use field.onChange from the render prop:

// Good: field.onChange
const { field } = useController({ name: "status", control });

<Select onValueChange={field.onChange} value={field.value}>
  {options.map((opt) => (
    <SelectItem key={opt.value} value={opt.value}>
      {opt.label}
    </SelectItem>
  ))}
</Select>

// Bad: setValue (breaks controller lifecycle)
<Select onValueChange={(v) => setValue("status", v)} value={watch("status")}>

Only use setValue for programmatic updates outside user interactions (e.g., setting values on mount, resetting based on external data).

5. Always Provide Default Values

Always provide defaultValues in useForm for all fields:

// Good: All fields have defaults
const form = useForm<FormValues>({
  resolver: zodResolver(formSchema),
  defaultValues: {
    name: "",
    email: "",
    items: [],
    settings: {
      notifications: true,
      theme: "light",
    },
  },
});

// Bad: Missing defaultValues causes controlled/uncontrolled warnings
const form = useForm<FormValues>({
  resolver: zodResolver(formSchema),
});

6. Watch Specific Fields Only

Never use watch() without parameters:

// Good: Watch specific fields
const selectedType = watch("type");
const [name, email] = watch(["name", "email"]);

// Bad: Watches everything, causes unnecessary re-renders
const allValues = watch();

7. Use Dot Notation for Nested Fields

const schema = z.object({
  user: z.object({
    profile: z.object({
      firstName: z.string(),
      lastName: z.string(),
    }),
  }),
});

// Access nested fields with dot notation
<input {...register("user.profile.firstName")} />

8. Use useFieldArray for Dynamic Lists

const { fields, append, remove } = useFieldArray({
  control,
  name: "items",
});

return (
  <div>
    {fields.map((field, index) => (
      <div key={field.id}>
        <input {...register(`items.${index}.name`)} />
        <button type="button" onClick={() => remove(index)}>
          Remove
        </button>
      </div>
    ))}
    <button type="button" onClick={() => append({ name: "" })}>
      Add Item
    </button>
  </div>
);

9. Proper Form Submission

const onSubmit = async (data: FormValues) => {
  try {
    await submitToApi(data);
  } catch (error) {
    // Handle API errors, optionally set form errors
    form.setError("root", { message: "Submission failed" });
  }
};

<form onSubmit={form.handleSubmit(onSubmit)}>
  {/* fields */}
  {form.formState.errors.root && (
    <div className="error">{form.formState.errors.root.message}</div>
  )}
  <button type="submit" disabled={form.formState.isSubmitting}>
    Submit
  </button>
</form>

10. Reset Forms Correctly

// Good: Reset with new values
form.reset({
  name: "New Name",
  email: "new@email.com",
});

// Good: Reset to default values
form.reset();

// Bad: Manual field clearing
setValue("name", "");
setValue("email", "");

11. Sub-form Validation with trigger()

// Validate specific fields (useful for multi-step forms)
const isStepValid = await form.trigger(["name", "email"]);

if (isStepValid) {
  goToNextStep();
}

12. Error Display Pattern

// Access errors via formState.errors
const {
  formState: { errors },
} = form;

<div>
  <input {...register("email")} />
  {errors.email && (
    <span className="text-red-500">{errors.email.message}</span>
  )}
</div>

Complete Example

import { useForm, useController, useFieldArray } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { z } from "zod";

const schema = z.object({
  name: z.string().min(1, "Name is required"),
  email: z.string().email("Invalid email"),
  role: z.enum(["admin", "user", "guest"]),
  tags: z.array(z.object({ value: z.string().min(1) })),
});

type FormValues = z.infer<typeof schema>;

function MyForm() {
  const form = useForm<FormValues>({
    resolver: zodResolver(schema),
    defaultValues: {
      name: "",
      email: "",
      role: "user",
      tags: [],
    },
  });

  const { fields, append, remove } = useFieldArray({
    control: form.control,
    name: "tags",
  });

  const onSubmit = async (data: FormValues) => {
    console.log(data);
  };

  return (
    <form onSubmit={form.handleSubmit(onSubmit)}>
      <div>
        <label>Name</label>
        <input {...form.register("name")} />
        {form.formState.errors.name && (
          <span>{form.formState.errors.name.message}</span>
        )}
      </div>

      <div>
        <label>Email</label>
        <input {...form.register("email")} />
        {form.formState.errors.email && (
          <span>{form.formState.errors.email.message}</span>
        )}
      </div>

      <RoleSelect control={form.control} />

      <div>
        <label>Tags</label>
        {fields.map((field, index) => (
          <div key={field.id}>
            <input {...form.register(`tags.${index}.value`)} />
            <button type="button" onClick={() => remove(index)}>
              Remove
            </button>
          </div>
        ))}
        <button type="button" onClick={() => append({ value: "" })}>
          Add Tag
        </button>
      </div>

      <button type="submit" disabled={form.formState.isSubmitting}>
        Submit
      </button>
    </form>
  );
}

// Custom controlled component using useController
function RoleSelect({ control }: { control: Control<FormValues> }) {
  const { field, fieldState } = useController({
    name: "role",
    control,
  });

  return (
    <div>
      <label>Role</label>
      <select onChange={field.onChange} value={field.value} ref={field.ref}>
        <option value="admin">Admin</option>
        <option value="user">User</option>
        <option value="guest">Guest</option>
      </select>
      {fieldState.error && <span>{fieldState.error.message}</span>}
    </div>
  );
}

Refactoring Checklist

When refactoring existing forms to react-hook-form:

  1. Define Zod schema matching existing validation
  2. Set up useForm with zodResolver and defaultValues
  3. Replace controlled inputs with register() where possible
  4. Use useController for third-party controlled components
  5. Replace manual state management with form state
  6. Convert submit handlers to use handleSubmit
  7. Update error display to use formState.errors
  8. Replace manual arrays with useFieldArray
  9. Remove unnecessary useState for form values

More by dust-tt

View all
dust-hive
1,268

Information about dust-hive, a CLI tool for running multiple isolated Dust development environments. ALWAYS enable this skill when the working directory is under ~/dust-hive/. Use for environment status, Dust app commands, and understanding port allocation.

dust-llm
1,268

Step-by-step guide for adding support for a new LLM in Dust. Use when adding a new model, or updating a previous one.

dust-temporal
1,268

Step-by-step guide for creating Temporal workflows in Dust. Use when adding background jobs, async processing, durable workflows, or task queues.

dust-mcp-server
1,268

Step-by-step guide for creating new internal MCP server integrations in Dust that connect to remote platforms (Jira, HubSpot, Salesforce, etc.). Use when adding a new MCP server, implementing a platform integration, or connecting Dust to a new external service.