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

useQueries.md

147 lines6.9 KB

1---
2id: useQueries
3title: useQueries
4---
5​
6<!-- DO NOT EDIT: this page is autogenerated from the type comments -->
7​
8```ts
9function useQueries<T extends any[], TCombinedResult = T extends [] ? [] : T extends [Head] ? [GetUseQueryResult<Head>] : T extends [Head, ...Tails[]] ? [...Tails[]] extends [] ? [] : [...Tails[]] extends [Head] ? [GetUseQueryResult<Head>, GetUseQueryResult<Head>] : [...Tails[]] extends [Head, ...Tails[]] ? [...Tails[]] extends [] ? [] : [...Tails[]] extends [Head] ? [GetUseQueryResult<Head>, GetUseQueryResult<Head>, GetUseQueryResult<Head>] : [...Tails[]] extends [Head, ...Tails[]] ? [...(...)[]] extends [] ? [] : ... extends ... ? ... : ... : [...{ [K in (...)]: (...) }[]] : [...{ [K in string | number | symbol]: GetUseQueryResult<Tails[K]> }[]] : { [K in string | number | symbol]: GetUseQueryResult<T[K]> }>(options: object, queryClient?: QueryClient): TCombinedResult;
10```
11​
12Defined in: [packages/preact-query/src/useQueries.ts:304](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQueries.ts#L304)
13​
14The `useQueries` hook can be used to fetch a variable number of queries.
15​
16The `queries` key accepts an array with query option objects mostly identical to `useQuery` β€” see the
17`queries` parameter below for the differences. A custom `QueryClient` is supplied once, as `useQueries`' own
18top-level second argument, rather than per query.
19​
20Having the same query key more than once in the array of query objects may cause some data to be shared
21between queries. To avoid this, consider de-duplicating the queries and map the results back to the desired
22structure.
23​
24The `combine` option can be used to combine the results of the queries into a single value. The result will
25be structurally shared to be as referentially stable as possible.
26​
27## Type Parameters
28​
29### T
30​
31`T` *extends* `any`[]
32​
33### TCombinedResult
34​
35`TCombinedResult` = `T` *extends* \[\] ? \[\] : `T` *extends* \[`Head`\] ? \[`GetUseQueryResult`\<`Head`\>\] : `T` *extends* \[`Head`, `...Tails[]`\] ? \[`...Tails[]`\] *extends* \[\] ? \[\] : \[`...Tails[]`\] *extends* \[`Head`\] ? \[`GetUseQueryResult`\<`Head`\>, `GetUseQueryResult`\<`Head`\>\] : \[`...Tails[]`\] *extends* \[`Head`, `...Tails[]`\] ? \[`...Tails[]`\] *extends* \[\] ? \[\] : \[`...Tails[]`\] *extends* \[`Head`\] ? \[`GetUseQueryResult`\<`Head`\>, `GetUseQueryResult`\<`Head`\>, `GetUseQueryResult`\<`Head`\>\] : \[`...Tails[]`\] *extends* \[`Head`, `...Tails[]`\] ? \[`...(...)[]`\] *extends* \[\] ? \[\] : ... *extends* ... ? ... : ... : \[`...{ [K in (...)]: (...) }[]`\] : \[...\{ \[K in string \| number \| symbol\]: GetUseQueryResult\<Tails\[K\]\> \}\[\]\] : \{ \[K in string \| number \| symbol\]: GetUseQueryResult\<T\[K\]\> \}
36​
37## Parameters
38​
39### options
40​
41The `queries` array to run, and the optional `combine` and `subscribed` options.
42​
43#### combine?
44​
45(`result`: `T` *extends* \[\] ? \[\] : `T` *extends* \[`Head`\] ? \[`GetUseQueryResult`\<`Head`\>\] : `T` *extends* \[`Head`, `...Tails[]`\] ? \[`...Tails[]`\] *extends* \[\] ? \[\] : \[`...Tails[]`\] *extends* \[`Head`\] ? \[`GetUseQueryResult`\<`Head`\>, `GetUseQueryResult`\<`Head`\>\] : \[`...Tails[]`\] *extends* \[`Head`, `...Tails[]`\] ? \[`...(...)[]`\] *extends* \[\] ? \[\] : ... *extends* ... ? ... : ... : \[`...{ [K in (...)]: (...) }[]`\] : \{ \[K in string \| number \| symbol\]: GetUseQueryResult\<T\[K\]\> \}) => `TCombinedResult`
46​
47Use this to combine the results of the queries into a single value. The result will be structurally
48shared to be as referentially stable as possible.
49​
50#### queries
51​
52 \| readonly \[`T` *extends* \[\] ? \[\] : `T` *extends* \[`Head`\] ? \[`GetUseQueryOptionsForUseQueries`\<`Head`\>\] : `T` *extends* \[`Head`, `...Tails[]`\] ? \[`...Tails[]`\] *extends* \[\] ? \[\] : \[`...Tails[]`\] *extends* \[`Head`\] ? \[`GetUseQueryOptionsForUseQueries`\<`Head`\>, `GetUseQueryOptionsForUseQueries`\<`Head`\>\] : \[`...Tails[]`\] *extends* \[`Head`, `...Tails[]`\] ? \[`...(...)[]`\] *extends* \[\] ? \[\] : ... *extends* ... ? ... : ... : readonly ...[] *extends* \[`...(...)[]`\] ? \[`...(...)[]`\] : ... *extends* ... ? ... : ... : readonly `unknown`[] *extends* `T` ? `T` : `T` *extends* `UseQueryOptionsForUseQueries`\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>[] ? `UseQueryOptionsForUseQueries`\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>[] : `UseQueryOptionsForUseQueries`\<`unknown`, `Error`, `unknown`, readonly ...[]\>[]\]
53 \| readonly \[\{ \[K in string \| number \| symbol\]: GetUseQueryOptionsForUseQueries\<T\[K\]\> \}\]
54​
55An array with query option objects, mostly identical to `useQuery` β€” except that `queryClient` and
56`subscribed` aren't accepted per-query (`subscribed` is a top-level option here instead), and
57`placeholderData` accepts a [QueriesPlaceholderDataFunction](../type-aliases/QueriesPlaceholderDataFunction.md), which is called with `previousData`
58and `previousQuery` always `undefined`, rather than `useQuery`'s placeholder function.
59​
60#### subscribed?
61​
62`boolean`
63​
64Set this to `false` to unsubscribe this observer from updates to the query cache.
65​
66**Default Value**
67​
68```ts
69true
70```
71​
72### queryClient?
73​
74[`QueryClient`](../classes/QueryClient.md)
75​
76Use this to provide a custom `QueryClient`. Otherwise, the one from the nearest context
77will be used.
78​
79## Returns
80​
81`TCombinedResult`
82​
83The combined result. Without `combine`, this is an array with all the query results, in the same
84order as the input. When `combine` is provided, this is the value returned by `combine` instead.
85​
86## Throws
87​
88The error of the first query that should be thrown to the nearest error boundary (see
89`throwOnError`). While suspending, it throws a promise instead.
90​
91## Examples
92​
93```tsx
94import { useQueries } from '@tanstack/preact-query'
95​
96function Posts({ ids }: { ids: Array<number> }) {
97 const postQueries = useQueries({
98 queries: ids.map((id) => ({
99 queryKey: ['post', id],
100 queryFn: () => fetchPost(id),
101 staleTime: Infinity,
102 })),
103 })
104​
105 return (
106 <ul>
107 {postQueries.map((query, index) => {
108 if (query.isPending) return <li key={ids[index]}>Loading...</li>
109 if (query.isError) return <li key={ids[index]}>Error: {query.error.message}</li>
110 return <li key={ids[index]}>{query.data.title}</li>
111 })}
112 </ul>
113 )
115```
116​
117Combining results into a single value:
118```tsx
119import { useQueries } from '@tanstack/preact-query'
120​
121function Posts({ ids }: { ids: Array<number> }) {
122 const { data, isPending, isError } = useQueries({
123 queries: ids.map((id) => ({
124 queryKey: ['post', id],
125 queryFn: () => fetchPost(id),
126 })),
127 combine: (postQueries) => {
128 return {
129 data: postQueries.map((query) => query.data),
130 isPending: postQueries.some((query) => query.isPending),
131 isError: postQueries.some((query) => query.isError),
132 }
133 },
134 })
135​
136 if (isPending) return 'Loading...'
137 if (isError) return 'Error loading posts'
138​
139 return (
140 <ul>
141 {data.map((post) => (
142 <li key={post?.id}>{post?.title}</li>
143 ))}
144 </ul>
145 )
147```