@beignet/react-hook-form

React Hook Form integration for Beignet

[!CAUTION] Beignet is experimental alpha software. The 0.0.x package line is for early evaluation, and APIs may change between releases while the framework settles.

This package provides automatic form validation using your contract's body schema. Works with any Standard Schema library (Zod, Valibot, ArkType, etc.).

Installation

npm install @beignet/react-hook-form @beignet/core react-hook-form @hookform/resolvers react

TypeScript requirements

This package requires TypeScript 5.0 or higher for proper type inference.

Agent skills

This package ships a TanStack Intent skill for coding agents: @beignet/react-hook-form#forms. Load it when adding contract-backed forms, React Hook Form setup, Standard Schema resolver behavior, rootFormError, React Query mutations, transforming body schemas, feature component boundaries, or field/server error mapping in a Beignet app.

Usage

Basic form

"use client";

import { createReactHookForm } from "@beignet/react-hook-form";
import { createTodo } from "@/features/todos/contracts";

const rhf = createReactHookForm();

function CreateTodoForm() {
  const { useForm } = rhf(createTodo);
  const form = useForm({
    defaultValues: {
      title: "",
      completed: false,
    },
  });

  const onSubmit = form.handleSubmit((values) => {
    // values is the parsed schema output: { title: string; completed?: boolean }
    console.log("Creating todo:", values);
  });

  return (
    <form onSubmit={onSubmit}>
      <input
        {...form.register("title")}
        placeholder="What needs to be done?"
      />
      {form.formState.errors.title && (
        <p className="error">{form.formState.errors.title.message}</p>
      )}

      <label>
        <input type="checkbox" {...form.register("completed")} />
        Completed
      </label>

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

With React Query mutation

"use client";

import { createReactHookForm, rootFormError } from "@beignet/react-hook-form";
import { useMutation } from "@tanstack/react-query";
import { rq } from "@/client";
import { createTodo } from "@/features/todos/contracts";

const rhf = createReactHookForm();

function CreateTodoForm() {
  const { useForm } = rhf(createTodo);
  const form = useForm({
    defaultValues: { title: "" },
  });

  const mutation = useMutation(
    rq(createTodo).mutationOptions({
      onSuccess: () => form.reset(),
      onError: (error) => {
        form.setError("root", rootFormError(error, "Could not create the todo."));
      },
    }),
  );

  const onSubmit = form.handleSubmit((values) => {
    form.clearErrors("root");
    mutation.mutate({ body: values });
  });

  return (
    <form onSubmit={onSubmit}>
      <input {...form.register("title")} placeholder="Title" />
      {form.formState.errors.title && (
        <p>{form.formState.errors.title.message}</p>
      )}
      {form.formState.errors.root && (
        <p>{form.formState.errors.root.message}</p>
      )}

      <button type="submit" disabled={mutation.isPending}>
        {mutation.isPending ? "Creating..." : "Create"}
      </button>
    </form>
  );
}

React Hook Form only owns request body fields. Pass path params, query params, headers, and auth-derived values to the endpoint call or mutation variables. Submit failures come back as Beignet client errors, so map route-owned catalog errors, framework validation errors, network failures, and contract drift through rootFormError(...), then set form.setError("root", ...) or a specific field when your server response identifies one.

Disabling validation

If you need to disable the schema resolver (e.g., for partial form handling):

const { useForm } = rhf(createTodo);
const form = useForm({
  resolverEnabled: false, // Disable schema validation
  defaultValues: { title: "" },
});

Using contract config directly

You can pass either a contract builder or its config:

import { createReactHookForm } from "@beignet/react-hook-form";
import { createTodo } from "@/features/todos/contracts";

const rhf = createReactHookForm();

// Using ContractBuilder directly
const { useForm } = rhf(createTodo);

// Or using the contract config
const { useForm } = rhf(createTodo.config);

API reference

createReactHookForm()

Creates a React Hook Form adapter factory.

const rhf = createReactHookForm();

rhf(contract)

Creates a React Hook Form adapter for a contract.

const adapter = rhf(createTodo);

adapter.useForm(props?)

Returns a React Hook Form useForm result with the contract's body schema as resolver.

const form = adapter.useForm({
  defaultValues?: { ... },
  resolverEnabled?: boolean, // default: true
  // ...other React Hook Form options
});

rootFormError(error, fallback, overrides?)

Maps a failed endpoint call or mutation error to the form.setError("root", ...) shape. Wraps contractErrorMessage from @beignet/core/client: non-contract errors return the fallback copy, client-side input validation failures return a generic "check the highlighted fields" message, and catalog codes can override copy per form.

form.setError(
  "root",
  rootFormError(error, "Could not update profile.", {
    HANDLE_UNAVAILABLE: "That handle is already taken.",
  }),
);

Type inference

Form types come from the contract's body schema and follow React Hook Form's input/output split:

• Live field values — register, watch, setValue, getValues, and defaultValues — use the schema input: what the user edits before validation runs.
• handleSubmit callbacks receive the schema output: the parsed values after coercion, transforms, and defaults run.

// Contract definition
const createTodo = todos
  .post("/api/todos")
  .body(z.object({
    title: z.string().min(1),
    description: z.string().optional(),
    completed: z.boolean().optional(),
  }))
  .responses({ 201: TodoSchema });

// Form values are inferred
const rhf = createReactHookForm();
const form = rhf(createTodo).useForm();
form.register("title");       // ✓ Valid
form.register("description"); // ✓ Valid
form.register("invalid");     // ✗ Type error

For plain schemas like the one above, input and output are identical. For coercing or transforming schemas they differ:

const createPayment = payments
  .post("/api/payments")
  .body(z.object({
    amount: z.string().transform(Number),
    note: z.string().optional(),
  }))
  .responses({ 201: PaymentSchema });

const form = rhf(createPayment).useForm({
  defaultValues: { amount: "" }, // input: string
});

form.watch("amount"); // string (input)

form.handleSubmit((values) => {
  values.amount; // number (output)
});

Submitting transforming schemas

The typed client posts the schema input — the server validates and transforms the body when it receives the request. Parsed output from handleSubmit is still valid input for plain, defaulted, and coerced schemas, so mutation.mutate({ body: values }) keeps working for those. When a transform changes a field's type, the parsed output no longer matches the contract body and TypeScript rejects it. Send the raw field values instead — validation has already passed by the time the submit handler runs:

const onSubmit = form.handleSubmit(() => {
  mutation.mutate({ body: form.getValues() });
});

Standard Schema support

This package uses the @hookform/resolvers/standard-schema resolver, which works with any Standard Schema compatible library:

• Zod - z.object({ ... })
• Valibot - v.object({ ... })
• ArkType - type({ ... })

Validation behavior

React Hook Form controls when the generated resolver runs. With the default React Hook Form settings, the resolver validates before submit and then revalidates changed fields after a failed submit. Pass normal React Hook Form options such as mode: "onBlur" or reValidateMode: "onChange" when a form needs different timing.

Validation errors are available via form.formState.errors:

{form.formState.errors.title && (
  <span className="error">
    {form.formState.errors.title.message}
  </span>
)}

Complete example

import { createReactHookForm } from "@beignet/react-hook-form";
import { useMutation } from "@tanstack/react-query";
import { rq } from "@/client";
import { rootFormError } from "@/client/errors";
import { updateProfile } from "@/features/profile/contracts";

const rhf = createReactHookForm();

function ProfileForm({ profile }) {
  const { useForm } = rhf(updateProfile);
  const form = useForm({
    defaultValues: {
      name: profile.name,
      email: profile.email,
      bio: profile.bio ?? "",
    },
  });

  const mutation = useMutation(
    rq(updateProfile).mutationOptions({
      onSuccess: () => {
        toast.success("Profile updated!");
      },
      onError: (error) => {
        form.setError("root", rootFormError(error, "Could not update the profile."));
      },
    })
  );

  const onSubmit = form.handleSubmit((values) => {
    form.clearErrors("root");
    mutation.mutate({ body: values });
  });

  const { errors, isDirty, isSubmitting } = form.formState;

  return (
    <form onSubmit={onSubmit}>
      <div>
        <label htmlFor="name">Name</label>
        <input id="name" {...form.register("name")} />
        {errors.name && <span className="error">{errors.name.message}</span>}
      </div>

      <div>
        <label htmlFor="email">Email</label>
        <input id="email" type="email" {...form.register("email")} />
        {errors.email && <span className="error">{errors.email.message}</span>}
      </div>

      <div>
        <label htmlFor="bio">Bio</label>
        <textarea id="bio" {...form.register("bio")} />
        {errors.bio && <span className="error">{errors.bio.message}</span>}
      </div>

      <button type="submit" disabled={!isDirty || isSubmitting}>
        {isSubmitting ? "Saving..." : "Save Changes"}
      </button>

      {errors.root && <span className="error">{errors.root.message}</span>}
    </form>
  );
}

Related packages

• @beignet/core/contracts - Core contract definitions
• @beignet/react-query - TanStack Query integration
• @beignet/core/client - HTTP client

License

MIT