Open History to see the last commit
1---
2id: createQuery
3title: createQuery
4---
5β
6<!-- DO NOT EDIT: this page is autogenerated from the type comments -->
7β
8```ts
9const createQuery: {
10<TQueryFnData, TError, TData, TQueryKey> (options: UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>, queryClient?: () => QueryClient): UseQueryResult<TData, TError>;
11<TQueryFnData, TError, TData, TQueryKey> (options: DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>, queryClient?: () => QueryClient): DefinedUseQueryResult<TData, TError>;
12} = useQuery;
13```
14β
15Defined in: [packages/solid-query/src/index.ts:57](https://github.com/TanStack/query/blob/main/packages/solid-query/src/index.ts#L57)
16β
17## Call Signature
18β
19```ts
20<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>, queryClient?: () => QueryClient): UseQueryResult<TData, TError>;
21```
22β
23Subscribes to a query: a declarative dependency on an asynchronous source of data that is tied to a unique key.
24The query runs when the options call for it β `enabled: false` skips the initial fetch.
25β
26### Type Parameters
27β
28#### TQueryFnData
29β
30`TQueryFnData` = `unknown`
31β
32#### TError
33β
34`TError` = `Error`
35β
36#### TData
37β
38`TData` = `TQueryFnData`
39β
40#### TQueryKey
41β
42`TQueryKey` *extends* readonly `unknown`[] = readonly `unknown`[]
43β
44### Parameters
45β
46#### options
47β
48[`UndefinedInitialDataOptions`](../type-aliases/UndefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
49β
50An accessor returning the [UndefinedInitialDataOptions](../type-aliases/UndefinedInitialDataOptions.md) to use β everything you can
51pass to `useQuery`.
52β
53#### queryClient?
54β
55() => [`QueryClient`](../classes/QueryClient.md)
56β
57An accessor for a custom `QueryClient`. Otherwise, the one from the nearest context
58will be used.
59β
60### Returns
61β
62[`UseQueryResult`](../type-aliases/UseQueryResult.md)\<`TData`, `TError`\>
63β
64The current query result, as a Solid store. `status` is `pending` if there is no cached data to
65display, `error` if the last fetch attempt failed, or `success` if the query has data to display.
66`isPending`/`isSuccess`/`isError` are derived booleans for convenience.
67β
68### See
69β
70[queryOptions](../functions/queryOptions.md) to share these options between `useQuery` and imperative APIs like `queryClient.query`.
71β
72### Examples
73β
74```tsx
75import { For, Match, Switch } from 'solid-js'
76import { useQuery } from '@tanstack/solid-query'
77β
78function Posts() {
79 const postsQuery = useQuery(() => ({
80 queryKey: ['posts'],
81 queryFn: fetchPosts,
82 }))
83β
84 return (
85 <Switch>
86 <Match when={postsQuery.isPending}>Loading...</Match>
87 <Match when={postsQuery.isError}>Error: {postsQuery.error.message}</Match>
88 <Match when={postsQuery.isSuccess}>
89 <ul>
90 <For each={postsQuery.data}>{(post) => <li>{post.title}</li>}</For>
91 </ul>
92 <div>{postsQuery.isFetching ? 'Background Updating...' : ' '}</div>
93 </Match>
94 </Switch>
95 )
96}
97```
98β
99`select` derives whatever `data` a component needs from the cached value, without changing what's
100actually stored in the cache β the cache still holds the full `Post[]`, but `data` here is a `number`:
101```tsx
102import { Match, Switch } from 'solid-js'
103import { useQuery } from '@tanstack/solid-query'
104β
105function PostCount() {
106 const postsQuery = useQuery(() => ({
107 queryKey: ['posts'],
108 queryFn: fetchPosts,
109 select: (posts) => posts.length,
110 }))
111β
112 return (
113 <Switch>
114 <Match when={postsQuery.isPending}>Loading...</Match>
115 <Match when={postsQuery.isError}>Error: {postsQuery.error.message}</Match>
116 <Match when={postsQuery.isSuccess}>{postsQuery.data} posts</Match>
117 </Switch>
118 )
119}
120```
121β
122A dependent query, only enabled once `postId` is set:
123```tsx
124import { Match, Switch } from 'solid-js'
125import { useQuery } from '@tanstack/solid-query'
126β
127function Post(props: { postId: number | undefined }) {
128 const postQuery = useQuery(() => ({
129 queryKey: ['post', props.postId],
130 queryFn: () => fetchPost(props.postId!),
131 enabled: props.postId != null,
132 }))
133β
134 return (
135 <Switch fallback={<h1>{postQuery.data?.title}</h1>}>
136 <Match when={props.postId == null}>Select a post</Match>
137 <Match when={postQuery.isLoading}>Loading...</Match>
138 <Match when={postQuery.isError}>Error: {postQuery.error.message}</Match>
139 </Switch>
140 )
141}
142```
143β
144The same dependent query, using `skipToken` to disable it in a type-safe way instead of relying on
145`enabled`. The non-null assertion is still needed β Solid's `props` narrowing doesn't survive into the
146`queryFn` closure the way a local `const` would β but `skipToken` keeps `queryFn`'s return type accurate
147without it. `refetch` doesn't work while `queryFn` is `skipToken` β use `enabled: false` instead if you
148need to trigger the query manually:
149```tsx
150import { Match, Switch } from 'solid-js'
151import { skipToken, useQuery } from '@tanstack/solid-query'
152β
153function Post(props: { postId: number | undefined }) {
154 const postQuery = useQuery(() => ({
155 queryKey: ['post', props.postId],
156 queryFn: props.postId != null ? () => fetchPost(props.postId!) : skipToken,
157 }))
158β
159 return (
160 <Switch fallback={<h1>{postQuery.data?.title}</h1>}>
161 <Match when={props.postId == null}>Select a post</Match>
162 <Match when={postQuery.isLoading}>Loading...</Match>
163 <Match when={postQuery.isError}>Error: {postQuery.error.message}</Match>
164 </Switch>
165 )
166}
167```
168β
169Seeding a detail query from an already-cached list, to skip the loading state. `initialDataUpdatedAt` carries
170over the list's own fetch time, so that if you set a `staleTime`, it's measured from when the list was
171fetched rather than from now:
172```tsx
173import { useQuery, useQueryClient } from '@tanstack/solid-query'
174β
175function Post(props: { postId: number }) {
176 const queryClient = useQueryClient()
177β
178 const postQuery = useQuery(() => ({
179 queryKey: ['post', props.postId],
180 queryFn: () => fetchPost(props.postId),
181 initialData: () =>
182 queryClient
183 .getQueryData<Array<Post>>(['posts'])
184 ?.find((post) => post.id === props.postId),
185 initialDataUpdatedAt: () =>
186 queryClient.getQueryState(['posts'])?.dataUpdatedAt,
187 }))
188β
189 return postQuery.isError ? <span>Error: {postQuery.error.message}</span> : <h1>{postQuery.data?.title}</h1>
190}
191```
192β
193Paginated data, keeping the previous page's data visible while the next page loads:
194```tsx
195import { For, createSignal } from 'solid-js'
196import { keepPreviousData, useQuery } from '@tanstack/solid-query'
197β
198function Posts() {
199 const [page, setPage] = createSignal(0)
200β
201 const postsQuery = useQuery(() => ({
202 queryKey: ['posts', page()],
203 queryFn: () => fetchPosts(page()),
204 placeholderData: keepPreviousData,
205 }))
206β
207 return (
208 <div>
209 <ul>
210 <For each={postsQuery.data}>{(post) => <li>{post.title}</li>}</For>
211 </ul>
212 <button
213 disabled={postsQuery.isPlaceholderData}
214 onClick={() => setPage((old) => old + 1)}
215 >
216 Next Page
217 </button>
218 </div>
219 )
220}
221```
222β
223## Call Signature
224β
225```ts
226<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>, queryClient?: () => QueryClient): DefinedUseQueryResult<TData, TError>;
227```
228β
229Subscribes to a query: a declarative dependency on an asynchronous source of data that is tied to a unique key.
230The query runs when the options call for it β `enabled: false` skips the initial fetch.
231β
232This overload is selected when `initialData` is set, so the resulting `data` is never `undefined` (unless
233a `select` changes `TData` to include `undefined`).
234β
235### Type Parameters
236β
237#### TQueryFnData
238β
239`TQueryFnData` = `unknown`
240β
241#### TError
242β
243`TError` = `Error`
244β
245#### TData
246β
247`TData` = `TQueryFnData`
248β
249#### TQueryKey
250β
251`TQueryKey` *extends* readonly `unknown`[] = readonly `unknown`[]
252β
253### Parameters
254β
255#### options
256β
257[`DefinedInitialDataOptions`](../type-aliases/DefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
258β
259An accessor returning the [DefinedInitialDataOptions](../type-aliases/DefinedInitialDataOptions.md) to use β everything you can
260pass to `useQuery`, with `initialData` set.
261β
262#### queryClient?
263β
264() => [`QueryClient`](../classes/QueryClient.md)
265β
266An accessor for a custom `QueryClient`. Otherwise, the one from the nearest context
267will be used.
268β
269### Returns
270β
271[`DefinedUseQueryResult`](../type-aliases/DefinedUseQueryResult.md)\<`TData`, `TError`\>
272β
273The current query result, as a Solid store, typed so that `status` is `success` β or `error` if a
274fetch attempt fails while keeping the existing data (`status` never resolves to `pending` in this overload's
275type, since `initialData` guarantees data upfront). `isSuccess`/`isError` are derived booleans for
276convenience.
277β
278### See
279β
280[queryOptions](../functions/queryOptions.md) to share these options between `useQuery` and imperative APIs like `queryClient.query`.
281β
282### Example
283β
284```tsx
285import { For } from 'solid-js'
286import { useQuery } from '@tanstack/solid-query'
287β
288function Posts() {
289 // `postsQuery.data` is never `undefined`, thanks to `initialData` β even if a refetch fails, so the
290 // list stays visible alongside the error.
291 const postsQuery = useQuery(() => ({
292 queryKey: ['posts'],
293 queryFn: fetchPosts,
294 initialData: [],
295 }))
296β
297 return (
298 <div>
299 {postsQuery.isError ? <span>Error: {postsQuery.error.message}</span> : null}
300 <ul>
301 <For each={postsQuery.data}>{(post) => <li>{post.title}</li>}</For>
302 </ul>
303 </div>
304 )
305}
306```