Add unstable_flushSync option (#7996)

docs/hooks/use-fetcher.md

@@ -87,7 +87,9 @@ fetcher.submit(
 fetcher.submit(formData);
 ```
 
-## `fetcher.load(href)`
+`fetcher.submit` is a wrapper around a [`useSubmit`][use-submit] call for the fetcher instance, so it also accepts the same options as `useSubmit`.
+
+### `fetcher.load(href, options)`
 
 Loads data from a route loader. While multiple nested routes can match a URL, only the leaf route will be called.
 
@@ -96,6 +98,12 @@ fetcher.load("/some/route");
 fetcher.load("/some/route?foo=bar");
 ```
 
+#### `options.unstable_flushSync`
+
+The `unstable_flushSync` option tells React Router DOM to wrap the initial state update for this `fetcher.load` in a [`ReactDOM.flushSync`][flush-sync] call instead of the default [`React.startTransition`][start-transition]. This allows you to perform synchronous DOM actions immediately after the update is flushed to the DOM.
+
+<docs-warning>`ReactDOM.flushSync` de-optimizes React and can hurt the performance of your app.</docs-warning>
+
 ## Properties
 
 ### `fetcher.state`
@@ -146,3 +154,6 @@ The form method of the submission.
 [concurrent_mutations_with_use_fetcher]: https://www.youtube.com/watch?v=vTzNpiOk668&list=PLXoynULbYuEDG2wBFSZ66b85EIspy3fy6
 [optimistic_ui]: https://www.youtube.com/watch?v=EdB_nj01C80&list=PLXoynULbYuEDG2wBFSZ66b85EIspy3fy6
 [use_fetchers]: ./use-fetchers
+[flush-sync]: https://react.dev/reference/react-dom/flushSync
+[start-transition]: https://react.dev/reference/react/startTransition
+[use-submit]: ./use-submit

docs/hooks/use-navigate.md

@@ -77,7 +77,15 @@ navigate(".", {
 ```
 
 - **replace**: boolean - replace the current entry in the history stack instead of pushing a new one
-- **relative**: `"route" | "path"` - defines the relative path behavior for the link. `"route"` will use the route hierarchy so `".."` will remove all URL segments of the current route pattern while `"path"` will use the URL path so `".."` will remove one URL segment.
-- **state**: any - adds persistent client side routing state to the next location.
+- **relative**: `"route" | "path"` - defines the relative path behavior for the link
+  - `"route"` will use the route hierarchy so `".."` will remove all URL segments of the current route pattern while `"path"` will use the URL path so `".."` will remove one URL segment
+- **state**: any - adds persistent client side routing state to the next location
+- **unstable_flushSync**: boolean - wraps the initial state update for this navigation in a [`ReactDOM.flushSync`][flush-sync] call instead of the default [`React.startTransition`][start-transition]
+- **unstable_viewTransition**: boolean - enables a [View Transition][view-transitions] 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()`][use-view-transition-state]
 
 [redirect]: ../fetch/redirect
+[flush-sync]: https://react.dev/reference/react-dom/flushSync
+[start-transition]: https://react.dev/reference/react/startTransition
+[view-transitions]: https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API
+[use-view-transition-state]: ../hooks//use-view-transition-state

docs/hooks/use-submit.md

@@ -67,6 +67,9 @@ Options for the submission, the same as `<Form>` props. All options are optional
 - **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).
+- **unstable_flushSync**: Wraps the initial state update for this navigation in a [`ReactDOM.flushSync`][flush-sync] call instead of the default [`React.startTransition`][start-transition]
+- **unstable_viewTransition**: Enables a [View Transition][view-transitions] 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()`][use-view-transition-state]
 
 ```tsx
 submit(data, {
@@ -93,3 +96,7 @@ submit(data, {
 [form-vs-fetcher]: ../discussion/form-vs-fetcher
 [form]: ../components/form
 [fetcher-submit]: ../hooks/use-fetcher#fetchersubmitformdata-options
+[flush-sync]: https://react.dev/reference/react-dom/flushSync
+[start-transition]: https://react.dev/reference/react/startTransition
+[view-transitions]: https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API
+[use-view-transition-state]: ../hooks//use-view-transition-state