Skip to content

Commit a9e9513

Browse files
brophdawg11jonathanpruvost
authored andcommitted
Add unstable_flushSync option (remix-run#11005)
1 parent 5e671fe commit a9e9513

File tree

13 files changed

+747
-106
lines changed

13 files changed

+747
-106
lines changed

.changeset/flush-sync-router.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@remix-run/router": minor
3+
---
4+
5+
Add `unstable_flushSync` option to `router.navigate` and `router.fetch` to tell the React Router layer to opt-out of `React.startTransition` and into `ReactDOM.flushSync` for state updates

.changeset/flush-sync.md

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
"react-router-dom": minor
3+
"react-router": minor
4+
---
5+
6+
Add `unstable_flushSync` option to `useNavigate`/`useSumbit`/`fetcher.load`/`fetcher.submit` to opt-out of `React.startTransition` and into `ReactDOM.flushSync` for state updates

docs/hooks/use-fetcher.md

+12-2
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,7 @@ function SomeComponent() {
107107

108108
## Methods
109109

110-
## `fetcher.load()`
110+
### `fetcher.load(href, options)`
111111

112112
Loads data from a route loader.
113113

@@ -133,7 +133,15 @@ If you find yourself calling this function inside of click handlers, you can pro
133133

134134
<docs-info>Any `fetcher.load` calls that are active on the page will be re-executed as part of revalidation (either after a navigation submission, another fetcher submission, or a `useRevalidator()` call)</docs-info>
135135

136-
## `fetcher.submit()`
136+
#### `options.unstable_flushSync`
137+
138+
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.
139+
140+
<docs-warning>`ReactDOM.flushSync` de-optimizes React and can hurt the performance of your app.</docs-warning>
141+
142+
<docs-warning>Please note that this API is marked unstable and may be subject to breaking changes without a major release</docs-warning>
143+
144+
### `fetcher.submit()`
137145

138146
The imperative version of `<fetcher.Form>`. If a user interaction should initiate the fetch, you should use `<fetcher.Form>`. But if you, the programmer are initiating the fetch (not in response to a user clicking a button, etc.), then use this function.
139147

@@ -279,3 +287,5 @@ fetcher.formMethod; // "post"
279287
[api-development-strategy]: ../guides/api-development-strategy
280288
[use-submit]: ./use-submit
281289
[use-fetchers]: ./use-fetchers
290+
[flush-sync]: https://react.dev/reference/react-dom/flushSync
291+
[start-transition]: https://react.dev/reference/react/startTransition

docs/hooks/use-navigate.md

+14
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,8 @@ interface NavigateOptions {
2020
state?: any;
2121
preventScrollReset?: boolean;
2222
relative?: RelativeRoutingType;
23+
unstable_flushSync?: boolean;
24+
unstable_viewTransition?: boolean;
2325
}
2426

2527
type RelativeRoutingType = "route" | "path";
@@ -85,6 +87,16 @@ function EditContact() {
8587
}
8688
```
8789

90+
## `options.unstable_flushSync`
91+
92+
The `unstable_flushSync` option tells React Router DOM to wrap the initial state update for this navigation 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.
93+
94+
<docs-warning>`unstable_flushSync` only works when using a data router, see [Picking a Router][picking-a-router]</docs-warning>
95+
96+
<docs-warning>`ReactDOM.flushSync` de-optimizes React and can hurt the performance of your app.</docs-warning>
97+
98+
<docs-warning>Please note that this API is marked unstable and may be subject to breaking changes without a major release</docs-warning>
99+
88100
## `options.unstable_viewTransition`
89101

90102
The `unstable_viewTransition` option 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].
@@ -102,3 +114,5 @@ The `unstable_viewTransition` option enables a [View Transition][view-transition
102114
[use-view-transition-state]: ../hooks//use-view-transition-state
103115
[view-transitions]: https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API
104116
[picking-a-router]: ../routers/picking-a-router
117+
[flush-sync]: https://react.dev/reference/react-dom/flushSync
118+
[start-transition]: https://react.dev/reference/react/startTransition

docs/hooks/use-submit.md

+10
Original file line numberDiff line numberDiff line change
@@ -160,5 +160,15 @@ Because submissions are navigations, the options may also contain the other navi
160160
- `state`
161161
- `unstable_viewTransition`
162162

163+
### `options.unstable_flushSync`
164+
165+
The `unstable_flushSync` option tells React Router DOM to wrap the initial state update for this submission 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.
166+
167+
<docs-warning>`ReactDOM.flushSync` de-optimizes React and can hurt the performance of your app.</docs-warning>
168+
169+
<docs-warning>Please note that this API is marked unstable and may be subject to breaking changes without a major release</docs-warning>
170+
163171
[pickingarouter]: ../routers/picking-a-router
164172
[form]: ../components/form
173+
[flush-sync]: https://react.dev/reference/react-dom/flushSync
174+
[start-transition]: https://react.dev/reference/react/startTransition

package.json

+3-3
Original file line numberDiff line numberDiff line change
@@ -110,7 +110,7 @@
110110
},
111111
"filesize": {
112112
"packages/router/dist/router.umd.min.js": {
113-
"none": "49.0 kB"
113+
"none": "49.2 kB"
114114
},
115115
"packages/react-router/dist/react-router.production.min.js": {
116116
"none": "13.9 kB"
@@ -119,10 +119,10 @@
119119
"none": "16.3 kB"
120120
},
121121
"packages/react-router-dom/dist/react-router-dom.production.min.js": {
122-
"none": "16.1 kB"
122+
"none": "16.7 kB"
123123
},
124124
"packages/react-router-dom/dist/umd/react-router-dom.production.min.js": {
125-
"none": "22.3 kB"
125+
"none": "22.9 kB"
126126
}
127127
}
128128
}

0 commit comments

Comments
 (0)