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

useSubmit

The imperative version of <Form> that lets you, the programmer, submit a form instead of the user.

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

function SomeComponent() {
  const submit = useSubmit();
  return (
    <Form
      onChange={(event) => {
        submit(event.currentTarget);
      }}
    />
  );
}

Signature

submit(targetOrData, options);

targetOrData

Can be any of the following:

HTMLFormElement instance

<Form
  onSubmit={(event) => {
    submit(event.currentTarget);
  }}
/>

FormData instance

const formData = new FormData();
formData.append("myKey", "myValue");
submit(formData, { method: "post" });

Plain object that will be serialized as FormData

submit({ myKey: "myValue" }, { method: "post" });

Plain object that will be serialized as JSON

submit(
  { myKey: "myValue" },
  { method: "post", encType: "application/json" }
);

options

Options for the submission, the same as <Form> props. All options are optional.

  • action: The href to submit to. Default is the current route path.
  • method: The HTTP method to use like POST, default is GET.
  • encType: The encoding type to use for the form submission: application/x-www-form-urlencoded, multipart/form-data, application/json, or text/plain. Default is application/x-www-form-urlencoded.
  • navigate: Specify false to submit using a fetcher instead of performing a navigation
  • fetcherKey: The fetcher key to use when submitting using a fetcher via navigate: false
  • preventScrollReset: Prevents the scroll position from being reset to the top of the window when the data is submitted. Default is false.
  • replace: Replaces the current entry in the history stack, instead of pushing the new entry. Default is false.
  • relative: Defines relative route resolution behavior. Either "route" (relative to the route hierarchy) or "path" (relative to the URL).
  • flushSync: Wraps the initial state update for this navigation in a ReactDOM.flushSync call instead of the default React.startTransition
  • viewTransition: 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()
submit(data, {
  action: "",
  method: "post",
  encType: "application/x-www-form-urlencoded",
  preventScrollReset: false,
  replace: false,
  relative: "route",
});

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 useSubmit() behavior within splat routes

Additional Resources

Discussion

Related API

Docs and examples licensed under MIT