), 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

, e.preventDefault() + client state — silently sacrifices

revalidation, progressive enhancement, and race-safe transitions.

Quick Reference

+ 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

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. and fetcher.submit(..., {method:'get'}) both transition through submitting.

Key Patterns

for navigation, useFetcher for in-place

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

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.

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 → + redirect(...) from the action. Stop.
• Fail → Step 2.

1. **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 . Stop.
• Fail → Step 3.

1. Is this loading data outside of normal navigation (popover content,

combobox results, prefetch)?

• Pass → fetcher.load(href). Stop.
• Fail → Default to . 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.

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

will NOT reflect fetcher activity. Stop.

• Fail → Step 3.

1. **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.

1. Is the indicator scoped to the form just submitted via ?
• Pass → useNavigation() AND check

navigation.formAction === "/expected-path" so unrelated navigations

don't trigger your local spinner. Stop.

• Fail → Step 5.

1. 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

• component: See references/form.md for

vs native 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		useFetcher	Native	fetch()
---	---	---	---	---
URL change / history entry	Yes	No	Yes (hard nav)	No
Works without JS	Yes	Yes	Yes	No
Revalidates loaders	Yes	Yes	Yes (hard reload)	No
Pending state hook	useNavigation()	fetcher.state	None	Manual
Optimistic input source	navigation.formData	fetcher.formData	None	Manual
In-app mutation use case	Create / delete / multi-step	Inline / row / toggle	External targets only	Never for own routes