UNPKG

8.73 kB Markdown View Raw
1---
2title: React Transitions
3---
4
5# React Transitions
6
7[MODES: framework, data, declarative]
8
9<br/>
10<br/>
11
12[React 18][react-18] introduced the concept of "transitions" which allow you to differentiate urgent from non-urgent UI updates. To learn more about React Transitions and "concurrent rendering" Please refer to React's official documentation:
13
14- [What is Concurrent React][concurrent]
15- [Transitions][transitions]
16- [`React.useTransition`][use-transition]
17- [`React.startTransition`][start-transition]
18
19[React 19][react-19] enhances the async/concurrent landscape by introducing [Actions][actions] and support for using async functions in Transitions. With the support for async Transitions, a new [`React.useOptimistic`][use-optimistic-blog] [hook][use-optimistic] was also introduced that allows you to surface state updates during a Transition to show users instant feedback.
20
21## Transitions in React Router
22
23The introduction of Transitions in React makes the story of how React Router manages your navigations and router state a bit more complicated. These are powerful APIs but they don't come without some nuance and added complexity. We aim to make React Router work seamlessly with the new React features, but in some cases there may exist some tension between the new React ways to do things and some patterns you are already using in your React Router apps (i.e., pending states, optimistic UI).
24
25To ensure a smooth adoption story, we've introduced changes related to Transitions behind an opt-in `useTransitions` flag so that you can upgrade in a non-breaking fashion.
26
27### Current Behavior
28
29We first leveraged `React.startTransition` to make React Router more Suspense-friendly in React Router [6.13.0][rr-6-13-0] via the `future.v7_startTransition` flag. In v7, that became the default behavior and all router state updates are currently wrapped in `React.startTransition`.
30
31This default behavior has 2 potential issues that `useTransitions` is designed to solve:
32
33- There are some valid use cases where you _don't_ want your updates wrapped in `startTransition`
34 - One specific issue is that `React.useSyncExternalStore` updates can't be Transitions ([^1][uses-transition-issue], [^2][uses-transition-tweet]). `useSyncExternalStore` forces a sync update, which means fallbacks can be shown in update transitions that would otherwise avoid showing the fallback.
35 - React Router has a `flushSync` option on navigations to use [`React.flushSync`][flush-sync] for state updates instead, but that's not always a proper solution
36- React 19 has added a new `startTransition(() => Promise))` API as well as a new `useOptimistic` hook to surface updates during Transitions
37 - Without some updates to React Router, `startTransition(() => navigate(path))` doesn't work as you might expect, because we are not using `useOptimistic` internally so router state updates don't surface during the navigation, which breaks hooks like `useNavigation`
38
39To provide a solution to both of the above issues, we're introducing a new `useTransitions` prop to the router components that will let you opt-out of using `startTransition` for router state updates (solving the first issue), or opt-into a more enhanced usage of `startTransition` + `useOptimistic` (solving the second issue). Because the current behavior is a bit incomplete with the new React 19 APIs, we plan to make the opt-in behavior the default in React Router v8, but we will likely retain the opt-out flag for use cases such as `useSyncExternalStore`.
40
41### Opt-out via `useTransitions=false`
42
43If your application is not "Transition-friendly" due to the usage of `useSyncExternalStore` (or other reasons), then you can opt-out via the prop:
44
45```tsx
46// Framework Mode (entry.client.tsx)
47<HydratedRouter useTransitions={false} />
48
49// Data Mode
50<RouterProvider useTransitions={false} />
51
52// Declarative Mode
53<BrowserRouter useTransitions={false} />
54```
55
56This will stop the router from wrapping internal state updates in `startTransition`.
57
58### Opt-in via `useTransitions=true`
59
60<docs-info>Opting into this feature in Framework or Data Mode requires that you are using React 19 because it needs access to [`React.useOptimistic`][use-optimistic]</docs-info>
61
62If you want to make your application play nicely with all of the new React 19 features that rely on concurrent mode and Transitions, then you can opt-in via the new prop:
63
64```tsx
65// Framework Mode (entry.client.tsx)
66<HydratedRouter useTransitions />
67
68// Data Mode
69<RouterProvider useTransitions />
70
71// Declarative Mode
72<BrowserRouter useTransitions />
73```
74
75With this flag enabled:
76
77- All internal state updates are wrapped in `React.startTransition` (current behavior without the flag)
78- All `<Link>`/`<Form>` navigations will be wrapped in `React.startTransition`, using the promise returned by `useNavigate`/`useSubmit` so that the Transition lasts for the duration of the navigation
79 - `useNavigate`/`useSubmit` do not automatically wrap in `React.startTransition`, so you can opt-out of a Transition-enabled navigation by using those directly
80- In Framework/Data modes, a subset of the router state updates during a navigation will be surfaced to the UI via `useOptimistic`
81 - State related to the _ongoing_ navigation and all fetcher information will be surfaced:
82 - `state.navigation` for `useNavigation()`
83 - `state.revalidation` for `useRevalidator()`
84 - `state.actionData` for `useActionData()`
85 - `state.fetchers` for `useFetcher()` and `useFetchers()`
86 - State related to the _current_ location will not be surfaced:
87 - `state.location` for `useLocation`
88 - `state.matches` for `useMatches()`,
89 - `state.loaderData` for `useLoaderData()`
90 - `state.errors` for `useRouteError()`
91 - etc.
92
93Enabling this flag means that you can now have fully-Transition-enabled navigations that play nicely with any other ongoing Transition-enabled aspects of your application.
94
95The only APIs that are automatically wrapped in an async Transition are `<Link>` and `<Form>`. For everything else, you need to wrap the operation in `startTransition` yourself.
96
97```tsx
98// Automatically Transition-enabled
99<Link to="/path" />
100<Form method="post" action="/path" />
101
102// Manually Transition-enabled
103startTransition(() => navigate("/path"));
104startTransition(() => submit(data, { method: 'post', action: "/path" }));
105startTransition(() => fetcher.load("/path"));
106startTransition(() => fetcher.submit(data, { method: "post", action: "/path" }));
107
108// Not Transition-enabled
109navigate("/path");
110submit(data, { method: 'post', action: "/path" });
111fetcher.load("/path");
112fetcher.submit(data, { method: "post", action: "/path" });
113```
114
115**Important:** You must always `return` or `await` the `navigate` promise inside `startTransition` so that the Transition encompasses the full duration of the navigation. If you forget to `return` or `await` the promise, the Transition will end prematurely and things won't work as expected.
116
117```tsx
118// ✅ Returned promise
119startTransition(() => navigate("/path"));
120startTransition(() => {
121 setOptimistic(something);
122 return navigate("/path"));
123});
124
125// ✅ Awaited promise
126startTransition(async () => {
127 setOptimistic(something);
128 await navigate("/path"));
129});
130
131// ❌ Non-returned promise
132startTransition(() => {
133 setOptimistic(something);
134 navigate("/path"));
135});
136
137// ❌ Non-Awaited promise
138startTransition(async () => {
139 setOptimistic(something);
140 navigate("/path"));
141});
142```
143
144#### `popstate` navigations
145
146There is currently a bug with optimistic states and `popstate`. If you need to read the current route during a back navigation, which cannot complete synchronously (e.g. Suspends on uncached data), you can set the optimistic state before navigating back or defer the optimistic update in a timer or microtask.
147
148[react-18]: https://react.dev/blog/2022/03/29/react-v18
149[concurrent]: https://react.dev/blog/2022/03/29/react-v18#what-is-concurrent-react
150[transitions]: https://react.dev/blog/2022/03/29/react-v18#new-feature-transitions
151[use-transition]: https://react.dev/reference/react/useTransition#reference
152[start-transition]: https://react.dev/reference/react/startTransition
153[react-19]: https://react.dev/blog/2024/12/05/react-19
154[actions]: https://react.dev/blog/2024/12/05/react-19#actions
155[use-optimistic-blog]: https://react.dev/blog/2024/12/05/react-19#new-hook-optimistic-updates
156[use-optimistic]: https://react.dev/reference/react/useOptimistic
157[flush-sync]: https://react.dev/reference/react-dom/flushSync
158[rr-6-13-0]: https://github.com/remix-run/react-router/blob/main/CHANGELOG.md#v6130
159[uses-transition-issue]: https://github.com/facebook/react/issues/26382
160[uses-transition-tweet]: https://x.com/rickhanlonii/status/1683636856808775682