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:

tsx

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#

NamePurpose<Form> from @remix-run/reactNavigating, 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 handleuseFetcher()Non-navigating submission channel for inline mutations, list rows, popovers — same revalidation, no URL changeuseFetchers()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 stateuseSubmit()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.

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.

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.

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.

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.

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.

2. Was the mutation made with useFetcher?

   • Pass → Use that fetcher's fetcher.state. useNavigation() will NOT reflect fetcher activity. Stop.
   • Fail → Step 3.

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.

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.

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 for <Form> vs native <form> vs fetch(), progressive enhancement, redirect-after-success, and validation error display via useActionData.
• useFetcher: See 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 for fetcher.formData and useNavigation.formData, when to apply, and reverting on failure.
• File uploads: See references/uploads.md for unstable_parseMultipartFormData, unstable_createMemoryUploadHandler, unstable_createFileUploadHandler, and bounded handlers.
• Intent-based actions: See references/intent-actions.md for multiple actions on one route via the FormData intent field.

Comparison#

Concern<Form>``useFetcherNative <form>``fetch()URL change / history entryYesNoYes (hard nav)NoWorks without JSYesYesYesNoRevalidates loadersYesYesYes (hard reload)NoPending state hookuseNavigation()``fetcher.stateNoneManualOptimistic input sourcenavigation.formData``fetcher.formDataNoneManualIn-app mutation use caseCreate / delete / multi-stepInline / row / toggleExternal targets onlyNever for own routes