Skip to content
Source
Sign inSign up
TanStack/query
Open History to see the last commit

usePrefetchQuery.md

91 lines2.5 KB

1---
2id: usePrefetchQuery
3title: usePrefetchQuery
4redirect_from:
5 - framework/react/reference/usePrefetchQuery
6---
7​
8<!-- DO NOT EDIT: this page is autogenerated from the type comments -->
9​
10```ts
11function usePrefetchQuery<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: UsePrefetchQueryOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>, queryClient?: QueryClient): void;
12```
13​
14Defined in: [packages/react-query/src/usePrefetchQuery.tsx:39](https://github.com/TanStack/query/blob/main/packages/react-query/src/usePrefetchQuery.tsx#L39)
15​
16`usePrefetchQuery` does not return anything, it should be used just to fire a prefetch during render, before
17a suspense boundary that wraps a component that uses `useSuspenseQuery`. You can pass everything to
18`usePrefetchQuery` that you can pass to `queryClient.query`, though `queryKey` is always required, and
19`queryFn` is required unless a default query function has been defined.
20​
21The prefetch is skipped if the query already has any cached state β€” including a `pending`/`error` state left
22over from a previous attempt β€” so calling this on every render is cheap and won't refetch data that's
23already there or already in flight.
24​
25## Type Parameters
26​
27### TQueryFnData
28​
29`TQueryFnData` = `unknown`
30​
31### TError
32​
33`TError` = `Error`
34​
35### TData
36​
37`TData` = `TQueryFnData`
38​
39### TQueryData
40​
41`TQueryData` = `TQueryFnData`
42​
43### TQueryKey
44​
45`TQueryKey` *extends* readonly `unknown`[] = readonly `unknown`[]
46​
47## Parameters
48​
49### options
50​
51[`UsePrefetchQueryOptions`](../type-aliases/UsePrefetchQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryData`, `TQueryKey`\>
52​
53The [UsePrefetchQueryOptions](../type-aliases/UsePrefetchQueryOptions.md) to use β€” everything you can pass to `queryClient.query`.
54​
55<a id="options-properties"></a>
56​
57#### `options` properties
58​
59Built from [`QueryExecuteOptions`](../interfaces/QueryExecuteOptions.md#properties). See the type above for what it changes.
60​
61### queryClient?
62​
63[`QueryClient`](../classes/QueryClient.md)
64​
65Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
66be used.
67​
68## Returns
69​
70`void`
71​
72## Example
73​
74```tsx
75import { Suspense } from 'react'
76import { usePrefetchQuery } from '@tanstack/react-query'
77​
78function App() {
79 // Fire the prefetch during render, before the suspense boundary below.
80 usePrefetchQuery({
81 queryKey: ['posts'],
82 queryFn: fetchPosts,
83 })
84​
85 return (
86 <Suspense fallback={<h1>Loading posts...</h1>}>
87 <Posts />
88 </Suspense>
89 )
91```