remix-v2-forms

Remix v2 Forms & Mutations

Canonical mutation primitives for the @remix-run/react@^2 route-module framework. A correct Remix v2 mutation is: a <Form method="post"> (or <fetcher.Form>), an action that parses request.formData() and returns either redirect(...) or json(...), and UI that reads useActionData() (or fetcher.data) for errors plus useNavigation() (or fetcher.state) for pending state. Anything that bypasses this loop — fetch(), raw <form>, e.preventDefault() + client state — silently sacrifices revalidation, progressive enhancement, and race-safe transitions.

Quick Reference

<Form> + action:

import { json, redirect, type ActionFunctionArgs } from "@remix-run/node";
import { Form, useActionData, useNavigation } from "@remix-run/react";

export async function action({ request }: ActionFunctionArgs) {
  const form = await request.formData();
  const email = String(form.get("email") ?? "");
  if (!email.includes("@")) return json({ errors: { email: "Invalid" } }, { status: 400 });
  await createUser({ email });
  return redirect("/dashboard");
}

export default function Signup() {
  const actionData = useActionData<typeof action>();
  const nav = useNavigation();
  const busy = nav.state !== "idle" && nav.formAction === "/signup";
  return (
    <Form method="post" replace>
      <input name="email" type="email" />
      {actionData?.errors?.email ? <em>{actionData.errors.email}</em> : null}
      <button disabled={busy}>{busy ? "Signing up..." : "Sign Up"}</button>
    </Form>
  );
}

Primitives

| Name | Purpose | |---|---| | <Form> from @remix-run/react | Navigating, progressively-enhanced form that posts to a route action and triggers full-page revalidation | | <Form navigate={false}> | Shorthand for "post via fetcher; do not navigate." Equivalent to <fetcher.Form> without holding a fetcher ref — useful when you only need pending state, not a programmatic handle | | useFetcher() | Non-navigating submission channel for inline mutations, list rows, popovers — same revalidation, no URL change | | useFetchers() | Read-only array of all in-flight fetcher states across the app. Use for global pending indicators (top-bar loader) without prop drilling. No Form/submit/load methods on the returned items — just formData, state, etc. | | useNavigation() | Observes page-level navigation; the source of truth for <Form> pending state | | useSubmit() | Programmatic submission (onChange autosave, keyboard shortcuts). Accepts HTMLFormElement, FormData, plain object (form-encoded), or plain object encoded as JSON via { encType: "application/json" } | | useActionData<typeof action>() | Read the most recent action result for the current route |

State transitions:

• useNavigation().state: idle → submitting → loading → idle for non-GET

form submissions; idle → loading → idle for GET navigation.

• useFetcher().state: idle → submitting → loading → idle.

Asymmetry: useNavigation skips submitting for GET navigations; useFetcher does NOT — only fetcher.load() skips it. <fetcher.Form method='get'> and fetcher.submit(..., {method:'get'}) both transition through submitting.

Key Patterns

<Form> for navigation, useFetcher for in-place

<Form> changes the URL, adds history, and revalidates all loaders. useFetcher does the same revalidation but stays on the current URL. Each useFetcher() call returns an independent submission channel, so two rows submitting at once do not share pending state.

Intent pattern for multiple actions on one route

One action, switch on formData.get("intent"), distinct <button name="intent" value="..."> per operation. Only the clicked submit button's name=value lands in the body. See [references/intent-actions.md](references/intent-actions.md).

Optimistic UI from formData

fetcher.formData and navigation.formData are populated synchronously on submit and cleared at idle. Read directly each render; never mirror into local React state. See [references/optimistic-ui.md](references/optimistic-ui.md).

File uploads need encType="multipart/form-data"

Without it, request.formData() strips file data and you get the filename string instead of a File. Parse with unstable_parseMultipartFormData and a bounded upload handler. The unstable_ prefix is permanent in v2. See [references/uploads.md](references/uploads.md).

Gates (decision sequencing)

Answer in order. Pass means the condition is true; pick the API on the same line and stop.

<Form> vs useFetcher

1. Does the URL need to change after the mutation (creating a record

and routing to /records/:id, deleting and going back to a list, multi-step flow)?

• Pass → <Form method="post"> + redirect(...) from the action. Stop.
• Fail → Step 2.
• **Is this a mutation against a row, cell, toggle, or sub-section while

the user stays on the same page** (favorite, like, increment quantity, inline edit)?

• Pass → useFetcher() with <fetcher.Form>. Stop.
• Fail → Step 3.
• Is this loading data outside of normal navigation (popover content,

combobox results, prefetch)?

• Pass → fetcher.load(href). Stop.
• Fail → Default to <Form>. Navigation is the conservative

choice — revalidation and history work out of the box.

Hard rule: never reach for fetch() or axios for in-app mutations against your own Remix routes. That bypasses the action lifecycle and skips loader revalidation.

useNavigation vs useFetcher.state for pending state

1. Is the pending indicator global (page spinner in root, top-bar

loading bar)?

• Pass → useNavigation() in root.tsx

(navigation.state !== "idle"). Stop.

• Fail → Step 2.
• Was the mutation made with useFetcher?
• Pass → Use that fetcher's fetcher.state. useNavigation()

will NOT reflect fetcher activity. Stop.

• Fail → Step 3.
• **Is the indicator scoped to one row/button inside a list where each

row has its own fetcher?**

• Pass → Use the per-row fetcher.state (or look up by key via

useFetchers()) so other rows do not flicker. Stop.

• Fail → Step 4.
• Is the indicator scoped to the form just submitted via <Form>?
• Pass → useNavigation() AND check

navigation.formAction === "/expected-path" so unrelated navigations don't trigger your local spinner. Stop.

• Fail → Step 5.
• Need to render an optimistic value?
• Pass → Read navigation.formData?.get("field") (page form) or

fetcher.formData?.get("field") (fetcher) — both are populated while state !== "idle". Stop.

Additional Documentation

• <Form> component: See [references/form.md](references/form.md) for

<Form> vs native <form> vs fetch(), progressive enhancement, redirect-after-success, and validation error display via useActionData.

• useFetcher: See [references/fetcher.md](references/fetcher.md) for

inline mutations, list operations, popovers, fetcher.state, fetcher.data, fetcher.Form, fetcher.submit, fetcher.load.

• Optimistic UI: See

[references/optimistic-ui.md](references/optimistic-ui.md) for fetcher.formData and useNavigation.formData, when to apply, and reverting on failure.

• File uploads: See [references/uploads.md](references/uploads.md)

for unstable_parseMultipartFormData, unstable_createMemoryUploadHandler, unstable_createFileUploadHandler, and bounded handlers.

• Intent-based actions: See

[references/intent-actions.md](references/intent-actions.md) for multiple actions on one route via the FormData intent field.

Comparison

| Concern | <Form> | useFetcher | Native <form> | fetch() | |---|---|---|---|---| | URL change / history entry | Yes | No | Yes (hard