Open History to see the last commit
1---
2id: overview
3title: Solid Query
4---
5β
6The `@tanstack/solid-query` package provides a 1st-class API for using TanStack Query with SolidJS.
7β
8## Example
9β
10```tsx
11import { QueryClient, QueryClientProvider, createQuery } from '@tanstack/solid-query'
12import { Switch, Match, For } from 'solid-js'
13β
14const queryClient = new QueryClient()
15β
16function Example() {
17 const query = createQuery(() => ['todos'], fetchTodos)
18β
19 return (
20 <div>
21 <Switch>
22 <Match when={query.isLoading}>
23 <p>Loading...</p>
24 </Match>
25 <Match when={query.isError}>
26 <p>Error: {query.error.message}</p>
27 </Match>
28 <Match when={query.isSuccess}>
29 <For each={query.data}>
30 {(todo) => <p>{todo.title}</p>}
31 </For>
32 </Match>
33 </Switch>
34 </div>
35 )
36}
37β
38function App() {
39 return (
40 <QueryClientProvider client={queryClient}>
41 <Example />
42 </QueryClientProvider>
43 )
44}
45β
46```
47β
48## Available Functions
49β
50Solid Query offers useful primitives and functions that will make managing server state in SolidJS apps easier.
51β
52- `createQuery`
53- `createQueries`
54- `createInfiniteQueries`
55- `createMutation`
56- `useIsFetching`
57- `useIsMutating`
58- `useQueryClient`
59- `QueryClient`
60- `QueryClientProvider`
61β
62β
63β
64β
65## Important Differences between Solid Query & React Query
66β
67Solid Query offers an API similar to React Query, but there are some key differences to be mindful of.
68β
69- To maintain their reactivity, Query keys need to be wrapped inside a function while using `createQuery`, `createQueries`, `createInfiniteQuery` and `useIsFetching`.
70β
71```tsx
72// β react version
73useQuery(["todos", todo], fetchTodos)
74β
75// β
solid version
76createQuery(() => ["todos", todo()], fetchTodos)
77```
78β
79- Suspense works for queries out of the box if you access the query data inside a `<Suspense>` boundary.
80β
81```tsx
82import { For, Suspense } from 'solid-js'
83β
84function Example() {
85 const query = createQuery(() => ['todos'], fetchTodos)
86 return (
87 <div>
88 {/* β
Will trigger loading fallback, data accessed in a suspense context. */}
89 <Suspense fallback={"Loading..."}>
90 <For each={query.data}>{(todo) => <div>{todo.title}</div>}</For>
91 </Suspense>
92 {/* β Will not trigger loading fallback, data not accessed in a suspense context. */}
93 <For each={query.data}>{(todo) => <div>{todo.title}</div>}</For>
94 </div>
95 )
96}
97```
98β
99- Solid Query primitives (`createX`) do not support destructuring. The return value from these functions is a store, and their properties are only tracked in a reactive context.
100β
101```tsx
102import { QueryClient, QueryClientProvider, createQuery } from '@tanstack/solid-query'
103import { Match, Switch } from 'solid-js'
104β
105const queryClient = new QueryClient()
106β
107export default function App() {
108 return (
109 <QueryClientProvider client={queryClient}>
110 <Example />
111 </QueryClientProvider>
112 )
113}
114β
115function Example() {
116 // β react version -- supports destructing outside reactive context
117 // const { isLoading, error, data } = useQuery(['repoData'], () =>
118 // fetch('https://api.github.com/repos/tannerlinsley/react-query').then(res =>
119 // res.json()
120 // )
121 // )
122β
123 // β
solid version -- does not support destructuring outside reactive context
124 const query = createQuery(
125 () => ['repoData'],
126 () =>
127 fetch('https://api.github.com/repos/tannerlinsley/react-query').then(
128 (res) => res.json(),
129 ),
130 )
131β
132 // β
access query properties in JSX reactive context
133 return (
134 <Switch>
135 <Match when={query.isLoading}>Loading...</Match>
136 <Match when={query.isError}>Error: {query.error.message}</Match>
137 <Match when={query.isSuccess}>
138 <div>
139 <h1>{query.data.name}</h1>
140 <p>{query.data.description}</p>
141 <strong>π {query.data.subscribers_count}</strong>{' '}
142 <strong>β¨ {query.data.stargazers_count}</strong>{' '}
143 <strong>π΄ {query.data.forks_count}</strong>
144 </div>
145 </Match>
146 </Switch>
147 )
148}
149```
150β
151- If you want options to be reactive you need to pass them using object getter syntax. This may look strange at first but it leads to more idiomatic solid code.
152β
153```tsx
154import {
155 QueryClient,
156 QueryClientProvider,
157 createQuery,
158} from '@tanstack/solid-query'
159import { createSignal, For } from 'solid-js'
160β
161const queryClient = new QueryClient()
162β
163function Example() {
164 const [enabled, setEnabled] = createSignal(false)
165 const query = createQuery(() => ['todos'], fetchTodos, {
166 // β passing a signal directly is not reactive
167 // enabled: enabled(),
168β
169 // β
passing a function that returns a signal is reactive
170 get enabled() {
171 return enabled()
172 },
173 })
174β
175 return (
176 <div>
177 <Switch>
178 <Match when={query.isLoading}>
179 <p>Loading...</p>
180 </Match>
181 <Match when={query.isError}>
182 <p>Error: {query.error.message}</p>
183 </Match>
184 <Match when={query.isSuccess}>
185 <For each={query.data}>
186 {(todo) => <p>{todo.title}</p>}
187 </For>
188 </Match>
189 </Switch>
190 <button onClick={() => setEnabled(!enabled())}>Toggle enabled</button>
191 </div>
192 )
193}
194β
195function App() {
196 return (
197 <QueryClientProvider client={queryClient}>
198 <Example />
199 </QueryClientProvider>
200 )
201}
202```
203β
204- Errors can be caught and reset using SolidJS' native `ErrorBoundary` component. `QueryErrorResetBoundary` is not needed with Solid Query
205β
206- Since Property tracking is handled through Solid's fine grained reactivity, options like `notifyOnChangeProps` are not needed