Remix V2 Forms

intent

use this skill when you need to handle form submissions, mutations, and data revalidation in remix v2 apps. reach for it whenever you're building forms that need pending states, optimistic ui, file uploads, multi-action routes, or non-navigating in-place edits. the canonical remix approach guarantees revalidation, progressive enhancement, and race-safe state transitions. anything outside this loop (raw fetch, preventDefault + client state, native forms for in-app mutations) breaks revalidation and silently loses data on refresh or concurrent requests.

inputs

remix dependencies (required)

• @remix-run/react v2+: provides <Form>, useFetcher, useNavigation, useActionData, useSubmit, useFetchers
• @remix-run/node v2+: provides json, redirect, ActionFunctionArgs type
• node runtime or edge runtime (deno, cloudflare workers); form parsing works on both

route module setup (required)

• export an action function with signature async (args: ActionFunctionArgs) => Response
• access args.request (a web Request object) to parse formData(), headers, and method
• route file must use .tsx or .ts extension

form inputs (required per submission)

• name attributes on every input, textarea, select you want to capture
• value on button elements if using intent pattern (multi-action routes)
• encType="multipart/form-data" on <Form> if uploading files

optional external integrations

• file upload handler: configure via unstable_parseMultipartFormData(request, uploadHandler) in action. handler can be memory-based (unstable_createMemoryUploadHandler) or disk-based (unstable_createFileUploadHandler). requires setup in action body, not env vars.
• session cookie: if you need post-action side effects (login, role change), set via response.headers.append("set-cookie", ...) in action return
• database or api client: inject via loader or action context; no special remix setup needed

pending state context (required for ui)

• useNavigation() returns {state: "idle" | "submitting" | "loading", formData?: FormData, formAction?: string, ...} at page level
• useFetcher().state returns same shape per fetcher instance
• useFetchers() returns array of all in-flight fetchers; read-only, no methods to invoke

error handling context (required for validation)

• useActionData<typeof action>() reads the most recent action return (non-null only if action returned a Response, not on redirect)
• action can return json({errors: {...}}, {status: 400}) to display validation without navigating

procedure

step 1: set up the action function

parse the incoming request and decide: redirect on success, or return json error data.

inputs: request object with method and body, any db/api clients injected into loader context process:

• call const form = await request.formData() to parse form fields (or unstable_parseMultipartFormData(request, handler) for file uploads)
• extract fields via form.get("fieldName") (single value) or form.getAll("fieldName") (array)
• validate each field; return json({errors: {field: "message"}}, {status: 400}) if invalid
• on success, mutate the database or call your api
• return redirect("/path") to change url and revalidate all loaders, or json({data: ...}) to stay on page and return data to useActionData

edge cases:

• if request.method !== "POST" (or "PUT", "DELETE", "PATCH"), throw a 405 or handle explicitly
• if form parsing fails (malformed multipart), catch and return 400
• if file size exceeds handler limit, handler throws; catch and return 413 or user-friendly message
• if database write fails mid-transaction, return 500 and the form state is left as-is on client; user can retry
• if you return redirect, any json data in the response body is ignored

outputs: Response object (either redirect(url) or json(data, {status}))

step 2: wrap form in <Form> component (page navigation case)

use this when submitting should change the url and revalidate loaders (create new record and route to detail page, delete and go back to list, multi-step flow).

inputs: route action from step 1, form fields, optional replace prop process:

• import {Form} from "@remix-run/react"
• render <Form method="post"> (or "put", "patch", "delete" matching your action)
• add replace prop to replace history entry instead of pushing a new one
• add name attributes to all inputs
• set button name="intent" value="action" if handling multiple actions on one route

edge cases:

• if user has js disabled, native form submission happens; action still runs and redirects work (progressive enhancement)
• if user hits back after form submission, they see the submitted state, not a confirmation dialog
• if action takes >30s, browser may timeout; design your action to be fast or accept the risk

outputs: html form element; submission triggers action and pending state updates

step 3: call useNavigation() to read pending state (page form case)

read the page-level navigation state to show spinners, disable buttons, or read optimistic formdata.

inputs: none (hook, call it in render) process:

• call const nav = useNavigation() in component
• check nav.state === "submitting" or nav.state === "loading" to know if request is in-flight
• check nav.formAction === "/expected-route" if multiple forms on the page to avoid unrelated navigations triggering your spinner
• check nav.formData?.get("field") to read the submitted value while pending (optimistic ui)
• all three properties are null/undefined when state === "idle"

edge cases:

• nav.state goes idle → submitting → loading → idle on post/put/delete; only idle → loading → idle on get navigation
• if user navigates away while form is pending, nav.state resets to idle even though the server is still processing
• if action returns redirect, you see the redirect target's loader run as loading state
• if action returns json, state returns to idle before useActionData updates

outputs: state object for conditional ui

step 4: use useActionData() to display server validation errors

read the json response from step 1 (only if action returned json, not if it returned redirect).

inputs: action result process:

• call const actionData = useActionData<typeof action>()
• check actionData?.errors?.fieldName to conditionally render error messages
• if action returned redirect, actionData is null (it was the previous action result)
• type it with <typeof action> to get autocompletion on the data shape

edge cases:

• useActionData does not change during pending state; the value is stale until the action completes
• if the same form submits twice in a row, the second result overwrites the first
• if user navigates to a different route and back, useActionData persists until that route's action runs

outputs: parsed json data for conditional rendering

step 5: use useFetcher() for inline mutations (no url change case)

use this when submitting should NOT change the url (favorite a post, increment a counter, inline edit a row, toggle a switch).

inputs: none (hook) process:

• call const fetcher = useFetcher() to get an independent submission channel
• render <fetcher.Form method="post"> with form fields; it posts to the current route's action (or use action="/custom-route" to target a different route)
• or call fetcher.submit(data, {method: "post"}) programmatically (onChange, keyboard shortcut, etc.)
• read fetcher.state and fetcher.data for pending state and response data
• read fetcher.formData?.get("field") while fetcher.state !== "idle" for optimistic ui

edge cases:

• each useFetcher() call is independent; two rows with separate fetchers do not share pending state
• if you call useFetcher() in the same component twice, you get two fetchers (do not do this; store the fetcher in state or a ref)
• if fetcher submits to a different route, it still revalidates all loaders on the current page
• if action returns redirect, the redirect is followed (url changes); fetcher is designed for non-redirects
• if network fails mid-request, fetcher state does not automatically retry; you must implement retry logic

outputs: fetcher object with Form, submit(), load() methods and state, data, formData properties

step 6: handle multiple actions on one route (intent pattern)

when a single route action needs to handle create, update, delete, or other variants, switch on a hidden field.

inputs: form with multiple submit buttons, each with name="intent" value="action-name" process:

• add <button name="intent" value="create">Create</button> and <button name="intent" value="delete">Delete</button> etc. (one button per action)
• in action, call const intent = formData.get("intent")
• switch on intent and handle each branch separately
• return appropriate response (json with errors, or redirect on success)
• only the clicked button's name/value pair lands in the request body

edge cases:

• if user presses enter in a text field, no intent is sent (no button was clicked); handle this case or require explicit button click
• if form has default button (no name), that button sends nothing; make sure every codepath is explicit

outputs: single action function that handles multiple mutations

step 7: handle file uploads with multipart parsing

when accepting file inputs, parse with unstable_parseMultipartFormData and a bounded handler.

inputs: <Form encType="multipart/form-data"> with <input type="file" name="avatar">, action setup with upload handler process:

• add encType="multipart/form-data" to <Form>
• in action, import {unstable_parseMultipartFormData, unstable_createFileUploadHandler} from "@remix-run/node"
• call const form = await unstable_parseMultipartFormData(request, unstable_createFileUploadHandler({directory: "./uploads", maxPartSize: 5_000_000}))
• extract file via const file = form.get("avatar") (returns a File object, not a string)
• check file instanceof File and file.size > 0 to detect if file was uploaded
• read file.name, file.stream(), file.type etc. as normal
• move or process the file (store in s3, scan for malware, etc.)

edge cases:

• without encType="multipart/form-data", form.get("avatar") returns the filename string, not a File; easy mistake
• unstable_parseMultipartFormData reads the full request into memory or disk depending on handler; budget ram/disk accordingly
• if file size exceeds maxPartSize, handler throws; catch and return 413
• if you use memory handler (unstable_createMemoryUploadHandler), all files stay in-memory; only safe for tiny files or testing
• if multiple files use the same name, only the last one is kept; use form.getAll("files") for multiple

outputs: parsed form with File objects for file fields

step 8: implement optimistic ui by reading formdata

show the user their input immediately without waiting for server response; revert on error.

inputs: navigation.formData (page form) or fetcher.formData (fetcher), current data from useLoaderData or fetcher.data process:

• while navigation.state !== "idle", read navigation.formData?.get("newTitle") and render it in the ui alongside or instead of the stale data
• if action returns json with errors, keep rendering stale data and show error message
• if action returns redirect, optimistic render is cleared and loaders revalidate (new truth from server)
• never mirror formdata into react state; read it fresh each render

edge cases:

• if form submits before first render completes, formdata is populated but not yet rendered; next render sees it
• if user closes browser or loses network while pending, optimistic render is lost (next visit loads stale data from server)
• if you render optimistic data and also show a spinner, user sees both; it feels responsive but can be confusing

outputs: ui that feels fast because it reflects user input before server confirms

decision points

when to use <Form> vs useFetcher vs fetch

use <Form method="post"> if:

• the mutation should change the url and add a history entry (creating a record and routing to /records/:id, deleting and returning to list, multi-step form completion)
• you want full revalidation of all loaders after the mutation
• you want pending state reflected in the page title and tab indicator
• progressive enhancement matters (form works without js)

use useFetcher() if:

• the mutation should NOT change the url (favorite, like, increment, inline edit, toggle)
• you only need to revalidate loaders, not navigate
• you want per-row or per-cell pending state without affecting the whole page
• the mutation is triggered by a user interaction on a sub-component (popover, modal, list item)

use fetcher.load(href) if:

• you need to load data without mutation (prefetch, popover content on hover, combobox filtering)
• revalidation of other loaders is not needed
• you want a separate pending state channel from form submissions

never use fetch() or axios for in-app mutations against your own remix routes. it bypasses revalidation, loader cache, and action lifecycle. the only exception is external apis (stripe, github, slack) that have no remix route.

when to use useNavigation() vs fetcher.state vs useFetchers()

use useNavigation() if:

• you need a global pending indicator (page spinner in root, top-bar loader, document title)
• the mutation was made with <Form> on the current page
• you want to track all page-level navigation and form submissions at once
• check nav.formAction === "/expected-route" to filter unrelated navigations

use fetcher.state if:

• the mutation was made with useFetcher() on the current page
• you have the fetcher instance in scope (stored as component state or passed as prop)
• useNavigation() will NOT show fetcher activity; they are separate channels

use useFetchers() if:

• you need to show a global pending indicator for all fetchers in the app without prop drilling
• you want to render a top-bar loader that lights up for any fetcher activity
• you do NOT need to call fetcher.submit() or fetcher.load(); useFetchers() is read-only
• loop through the array and check fetcher.state !== "idle" to see if any are pending

when to show validation errors in useActionData vs client-side validation

return json with errors from action if:

• the validation requires server state (email already exists, username taken, inventory check)
• the field is required or complex (multi-field dependencies, async checks)
• you want the error to persist if user reloads the page
• the error blocks form submission

use html5 validation (required, pattern, type="email") if:

• the validation is purely client-side (field is required, format is wrong, password is too short)
• you want instant feedback without a network request
• the field should fail before the form is even sent
• combine with server-side checks in the action anyway; never trust the client

when to use intent pattern vs separate routes

use intent pattern (multiple actions, one route) if:

• the actions are closely related (create and update on same page, favorite and unfavorite)
• they share validation logic or data models
• the ui for multiple actions is on the same form (multiple submit buttons)

use separate routes if:

• the actions are unrelated (user settings, file upload, report generation)
• they have completely different validation and response shapes
• you want granular permission checks per route
• intent names become unreadable or nested switches

when file upload fails

if unstable_parseMultipartFormData throws during parsing:

• catch the error and return json({errors: {upload: "File too large or malformed"}}, {status: 413})
• display the error via useActionData().errors.upload
• do NOT let the error bubble; it will return a 500 to the user

if file size is legitimate but the request exceeds maxPartSize:

• the handler rejects it automatically; you get an error
• increase maxPartSize if needed, but do not set it higher than your memory/disk budget
• consider chunked uploads or presigned urls for very large files (outside remix form scope)

if move or processing the file fails in action:

• return json({errors: {upload: "Failed to save file"}}, {status: 500})
• clean up any partial files on disk

output contract

on successful form submission via <Form>:

• action returns redirect(url) (http 302 or 303)
• browser navigates to the url and reruns loaders
• useActionData returns null on the new route (old action result is discarded)
• url changes, history entry is added (or replaced if <Form replace> was set)

on successful form submission via useFetcher (action returns json):

• action returns json(data) (http 200)
• fetcher.data is populated with the response data
• loaders are revalidated in the background
• url does not change, no history entry is added

on validation error:

• action returns json({errors: {...}}, {status: 400})
• useActionData or fetcher.data contains the errors object
• form is NOT submitted; user stays on the same page
• user can fix the inputs and resubmit

on server error during action:

• action throws or returns json({...}, {status: 500})
• browser shows the error boundary (or default remix error page)
• form is aborted; user can reload and try again

on file upload:

• if successful: file is stored at the path specified by handler (e.g., ./uploads/avatar.png)
• if size exceeded: handler throws and you return 413
• if parsing failed: you catch and return 400 or 413

pending state ui:

• while nav.state !== "idle" or fetcher.state !== "idle", buttons are disabled, spinners are shown, inputs reflect formData
• when request completes, state returns to idle and ui returns to normal (or shows errors)

outcome signal

user knows the form worked if:

• they are redirected to a success page (form with <Form>, action returns redirect)
• the page stayed the same but their change appeared in the ui (inline mutation with useFetcher, action returns json)
• if they reload the page, their change persists (action committed to database)
• if they have slow network and hit the back button, the form re-submits and completes (progressive enhancement)

user knows the form failed if:

• they see an error message below the field (validation error from useActionData)
• the button re-enabled and the spinner stopped spinning, but the url did not change (non-redirect error)
• they can correct the input and resubmit
• if they reload, the error is gone (error was not committed to database)

developer knows the skill is working if:

• form submission runs the action and logs or calls your mutation function
• pending state changes reflect in useNavigation() or fetcher.state
• validation errors appear in useActionData or fetcher.data
• on file upload, the file is written to disk and available in the action
• if you add a second fetcher in a list row, it does not affect the first fetcher's pending state
• if you use intent pattern and click different buttons, the correct branch of the action runs each time
• if user submits form without js, the action still runs and redirect works