dev
Viewing docs for dev branch, not the latest release. View latest
Form
On this page

<Form>

A progressively enhanced HTML <form> that submits data to actions via fetch, activating pending states in useNavigation which enables advanced user interfaces beyond a basic HTML form. After a form's action completes, all data on the page is automatically revalidated from the server to keep the UI in sync with the data.

Because it uses the HTML form API, server rendered pages are interactive at a basic level before JavaScript loads. Instead of Remix managing the submission, the browser manages the submission as well as the pending states (like the spinning favicon). After JavaScript loads, Remix takes over enabling web application user experiences.

Form is most useful for submissions that should also change the URL or otherwise add an entry to the browser history stack. For forms that shouldn't manipulate the browser history stack, use <fetcher.Form>.

import { Form } from "@remix-run/react";

function NewEvent() {
  return (
    <Form action="/events" method="post">
      <input name="title" type="text" />
      <input name="description" type="text" />
    </Form>
  );
}

Props

action

The URL to submit the form data to.

If undefined, this defaults to the closest route in context. If a parent route renders a <Form> but the URL matches deeper child routes, the form will post to the parent route. Likewise, a form inside the child route will post to the child route. This differs from a native <form> that will always point to the full URL.

Please see the Splat Paths section on the useResolvedPath docs for a note on the behavior of the future.v3_relativeSplatPath future flag for relative <Form action> behavior within splat routes

method

This determines the HTTP verb to be used: DELETE, GET, PATCH, POST, and PUT. The default is GET.

<Form method="post" />

Native <form> only supports GET and POST, so you should avoid the other verbs if you'd like to support progressive enhancement

encType

The encoding type to use for the form submission.

<Form encType="multipart/form-data" />

Defaults to application/x-www-form-urlencoded, use multipart/form-data for file uploads.

You can tell the form to skip the navigation and use a fetcher internally by specifying <Form navigate={false}>. This is essentially a shorthand for useFetcher() + <fetcher.Form> where you don't care about the resulting data and only want to kick off a submission and access the pending state via useFetchers().

<Form method="post" navigate={false} />

fetcherKey

When using a non-navigating Form, you may also optionally specify your own fetcher key to use.

<Form method="post" navigate={false} fetcherKey="my-key" />

preventScrollReset

If you are using <ScrollRestoration>, this lets you prevent the scroll position from being reset to the top of the window when the form is submitted.

<Form preventScrollReset />

replace

Replaces the current entry in the history stack, instead of pushing the new entry.

<Form replace />

reloadDocument

If true, it will submit the form with the browser instead of client side routing. The same as a native <form>.

<Form reloadDocument />

This is recommended over <form>. When the action prop is omitted, <Form> and <form> will sometimes call different actions depending on what the current URL is since <form> uses the current URL as the default, but <Form> uses the URL for the route the form is rendered in.

viewTransition

The viewTransition prop enables a View Transition for this navigation by wrapping the final state update in document.startViewTransition(). If you need to apply specific styles for this view transition, you will also need to leverage the useViewTransitionState().

Notes

?index

Because index routes and their parent route share the same URL, the ?index param is used to differentiate between them.

<Form action="/accounts?index" method="post" />
action url route action
/accounts?index app/routes/accounts._index.tsx
/accounts app/routes/accounts.tsx

See also:

Additional Resources

Videos:

Related Discussions:

Related APIs:

Docs and examples licensed under MIT