You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/rtk-query/usage/prefetching.mdx
+40-3Lines changed: 40 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -19,6 +19,25 @@ There are a handful of situations that you may want to do this, but some very co
19
19
3. User hovers over a next pagination button
20
20
4. User navigates to a page and you know that some components down the tree will require said data. This way, you can prevent fetching waterfalls.
21
21
22
+
## Prefetching vs Subscriptions
23
+
24
+
Prefetching is designed as a "fire and forget" operation that loads data into the cache without creating an ongoing subscription. This means:
25
+
26
+
-**No automatic refetching**: Prefetched data will not automatically refetch when tags are invalidated
27
+
-**No subscription management**: You don't need to (and can't) manually unsubscribe from prefetched data
28
+
-**Cache cleanup**: Prefetched data without active subscriptions may be removed during normal cache cleanup
29
+
-**Returns void**: The prefetch trigger function doesn't return a promise or subscription handle
30
+
31
+
If you need data that automatically refetches on invalidation or stays in the cache as long as a component is mounted, use a query hook like `useQuery` or `useQuerySubscription` instead. Prefetch is ideal for warming the cache before a user action, while query hooks are for ongoing data needs.
32
+
33
+
:::tip When to use prefetch vs query hooks
34
+
35
+
-**Use prefetch** when you want to load data ahead of time (e.g., on hover) but don't need it to stay fresh
36
+
-**Use query hooks** when you need data that automatically refetches on invalidation and stays in cache while the component is mounted
37
+
-**Use both together**: Prefetch on hover, then let the query hook create a subscription when the user navigates
38
+
39
+
:::
40
+
22
41
## Prefetching with React Hooks
23
42
24
43
Similar to the [`useMutation`](./mutations) hook, the `usePrefetch` hook will not run automatically — it returns a "trigger function" that can be used to initiate the behavior.
@@ -111,12 +130,30 @@ store.dispatch(
111
130
)
112
131
```
113
132
114
-
You can also dispatch the query action, but you would be responsible for implementing any additional logic.
133
+
### Prefetch vs `initiate()`
115
134
116
-
```ts title="Alternate method of manual prefetching" no-transpile
// This creates a subscription that must be manually cleaned up
139
+
const promise =dispatch(
140
+
api.endpoints[endpointName].initiate(arg, {
141
+
subscribe: true, // Creates a subscription (default)
142
+
forceRefetch: true,
143
+
}),
144
+
)
145
+
146
+
// You must manually unsubscribe to prevent memory leaks
147
+
promise.unsubscribe()
118
148
```
119
149
150
+
**Key differences:**
151
+
152
+
-**`api.util.prefetch()`**: Automatically uses `subscribe: false`, no cleanup needed
153
+
-**`endpoint.initiate()`**: Defaults to `subscribe: true`, requires manual `unsubscribe()` call
154
+
155
+
Use `prefetch()` for simple "load and forget" scenarios. Use `initiate()` directly only when you need fine-grained control over subscriptions and are prepared to manage the subscription lifecycle yourself.
0 commit comments