Viewing docs for an older release. View latest
Form
On this page

<Form>

A progressively enhanced HTML <form> wrapper, 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.

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.

unstable_viewTransition

The unstable_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 unstable_useViewTransitionState().

Please note that this API is marked unstable and may be subject to breaking changes without a major release.

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