Add missing <Form state> prop

.changeset/form-state-prop.md

@@ -0,0 +1,5 @@
+---
+"react-router-dom": patch
+---
+
+Add missing `<Form state>` prop to populate `history.state` on submission navigations

docs/components/form.md

@@ -215,6 +215,24 @@ See also:
 - [`useActionData`][useactiondata]
 - [`useSubmit`][usesubmit]
 
+## `state`
+
+The `state` property can be used to set a stateful value for the new location which is stored inside [history state][history-state]. This value can subsequently be accessed via `useLocation()`.
+
+```tsx
+<Form
+  method="post"
+  action="new-path"
+  state={{ some: "value" }}
+/>
+```
+
+You can access this state value while on the "new-path" route:
+
+```ts
+let { state } = useLocation();
+```
+
 ## `preventScrollReset`
 
 If you are using [`<ScrollRestoration>`][scrollrestoration], this lets you prevent the scroll position from being reset to the top of the window when the form action redirects to a new location.
@@ -330,3 +348,4 @@ You can access those values from the `request.url`
 [pickingarouter]: ../routers/picking-a-router
 [scrollrestoration]: ./scroll-restoration
 [link-preventscrollreset]: ./link#preventscrollreset
+[history-state]: https://developer.mozilla.org/en-US/docs/Web/API/History/state

docs/hooks/use-submit.md

@@ -134,4 +134,7 @@ submit(null, {
 <Form action="/logout" method="post" />;
 ```
 
+Because submissions are navigations, the options may also contain the other navigation related props from [`<Form>`][form] such as `replace`, `state`, `preventScrollReset`, `relative`, etc.
+
 [pickingarouter]: ../routers/picking-a-router
+[form]: ../components/form.md

package.json

@@ -118,7 +118,7 @@
       "none": "16.2 kB"
     },
     "packages/react-router-dom/dist/react-router-dom.production.min.js": {
-      "none": "12.5 kB"
+      "none": "12.6 kB"
     },
     "packages/react-router-dom/dist/umd/react-router-dom.production.min.js": {
       "none": "18.6 kB"

packages/react-router-dom/__tests__/data-browser-router-test.tsx

@@ -1541,6 +1541,46 @@ function testDomRouter(
       `);
     });
 
+    it("supports <Form state>", async () => {
+      let testWindow = getWindow("/");
+      let router = createTestRouter(
+        [
+          {
+            path: "/",
+            Component() {
+              return (
+                <Form method="post" action="/action" state={{ key: "value" }}>
+                  <button type="submit">Submit</button>
+                </Form>
+              );
+            },
+          },
+          {
+            path: "/action",
+            action: () => null,
+            Component() {
+              let state = useLocation().state;
+              return <p>{JSON.stringify(state)}</p>;
+            },
+          },
+        ],
+        { window: testWindow }
+      );
+      let { container } = render(<RouterProvider router={router} />);
+      expect(testWindow.history.state.usr).toBeUndefined();
+
+      fireEvent.click(screen.getByText("Submit"));
+      await waitFor(() => screen.getByText('{"key":"value"}'));
+      expect(getHtml(container)).toMatchInlineSnapshot(`
+        "<div>
+          <p>
+            {"key":"value"}
+          </p>
+        </div>"
+      `);
+      expect(testWindow.history.state.usr).toEqual({ key: "value" });
+    });
+
     it("supports <Form reloadDocument={true}>", async () => {
       let actionSpy = jest.fn();
       let router = createTestRouter(

packages/react-router-dom/dom.ts

@@ -161,6 +161,11 @@ export interface SubmitOptions {
    */
   replace?: boolean;
 
+  /**
+   * State object to add to the history stack entry for this navigation
+   */
+  state?: any;
+
   /**
    * Determines whether the form action is relative to the route hierarchy or
    * the pathname.  Use this if you want to opt out of navigating the route

packages/react-router-dom/index.tsx

@@ -730,6 +730,11 @@ export interface FormProps extends React.FormHTMLAttributes<HTMLFormElement> {
    */
   replace?: boolean;
 
+  /**
+   * State object to add to the history stack entry for this navigation
+   */
+  state?: any;
+
   /**
    * Determines whether the form action is relative to the route hierarchy or
    * the pathname.  Use this if you want to opt out of navigating the route
@@ -784,6 +789,7 @@ const FormImpl = React.forwardRef<HTMLFormElement, FormImplProps>(
     {
       reloadDocument,
       replace,
+      state,
       method = defaultMethod,
       action,
       onSubmit,
@@ -812,6 +818,7 @@ const FormImpl = React.forwardRef<HTMLFormElement, FormImplProps>(
       submit(submitter || event.currentTarget, {
         method: submitMethod,
         replace,
+        state,
         relative,
         preventScrollReset,
       });
@@ -1068,6 +1075,7 @@ export function useSubmit(): SubmitFunction {
         formMethod: options.method || (method as HTMLFormMethod),
         formEncType: options.encType || (encType as FormEncType),
         replace: options.replace,
+        state: options.state,
         fromRouteId: currentRouteId,
       });
     },