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 {
12 QueryClient,
13 QueryClientProvider,
14 createQuery,
15} from '@tanstack/solid-query'
16import { Switch, Match, For } from 'solid-js'
17β
18const queryClient = new QueryClient()
19β
20function Example() {
21 const query = createQuery(() => ({
22 queryKey: ['todos'],
23 queryFn: fetchTodos,
24 }))
25β
26 return (
27 <div>
28 <Switch>
29 <Match when={query.isPending}>
30 <p>Loading...</p>
31 </Match>
32 <Match when={query.isError}>
33 <p>Error: {query.error.message}</p>
34 </Match>
35 <Match when={query.isSuccess}>
36 <For each={query.data}>{(todo) => <p>{todo.title}</p>}</For>
37 </Match>
38 </Switch>
39 </div>
40 )
41}
42β
43function App() {
44 return (
45 <QueryClientProvider client={queryClient}>
46 <Example />
47 </QueryClientProvider>
48 )
49}
50```
51β
52## Available Functions
53β
54Solid Query offers useful primitives and functions that will make managing server state in SolidJS apps easier.
55β
56- `createQuery`
57- `createQueries`
58- `createInfiniteQueries`
59- `createMutation`
60- `useIsFetching`
61- `useIsMutating`
62- `useQueryClient`
63- `QueryClient`
64- `QueryClientProvider`
65β
66## Important Differences between Solid Query & React Query
67β
68Solid Query offers an API similar to React Query, but there are some key differences to be mindful of.
69β
70- Arguments to `solid-query` primitives (like `createQuery`, `createMutation`, `useIsFetching`) listed above are functions, so that they can be tracked in a reactive scope.
71β
72```tsx
73// β react version
74useQuery({
75 queryKey: ['todos', todo],
76 queryFn: fetchTodos,
77})
78β
79// β
solid version
80createQuery(() => ({
81 queryKey: ['todos', todo],
82 queryFn: fetchTodos,
83}))
84```
85β
86- Suspense works for queries out of the box if you access the query data inside a `<Suspense>` boundary.
87β
88```tsx
89import { For, Suspense } from 'solid-js'
90β
91function Example() {
92 const query = createQuery(() => ({
93 queryKey: ['todos'],
94 queryFn: fetchTodos,
95 }))
96 return (
97 <div>
98 {/* β
Will trigger loading fallback, data accessed in a suspense boundary. */}
99 <Suspense fallback={'Loading...'}>
100 <For each={query.data}>{(todo) => <div>{todo.title}</div>}</For>
101 </Suspense>
102 {/* β Will not trigger loading fallback, data not accessed in a suspense boundary. */}
103 <For each={query.data}>{(todo) => <div>{todo.title}</div>}</For>
104 </div>
105 )
106}
107```
108β
109- 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.
110β
111```tsx
112import {
113 QueryClient,
114 QueryClientProvider,
115 createQuery,
116} from '@tanstack/solid-query'
117import { Match, Switch } from 'solid-js'
118β
119const queryClient = new QueryClient()
120β
121export default function App() {
122 return (
123 <QueryClientProvider client={queryClient}>
124 <Example />
125 </QueryClientProvider>
126 )
127}
128β
129function Example() {
130 // β react version -- supports destructing outside reactive context
131 // const { isPending, error, data } = useQuery({
132 // queryKey: ['repoData'],
133 // queryFn: () =>
134 // fetch('https://api.github.com/repos/tannerlinsley/react-query').then(
135 // (res) => res.json()
136 // ),
137 // })
138β
139 // β
solid version -- does not support destructuring outside reactive context
140 const query = createQuery(() => ({
141 queryKey: ['repoData'],
142 queryFn: () =>
143 fetch('https://api.github.com/repos/tannerlinsley/react-query').then(
144 (res) => res.json(),
145 ),
146 }))
147β
148 // β
access query properties in JSX reactive context
149 return (
150 <Switch>
151 <Match when={query.isPending}>Loading...</Match>
152 <Match when={query.isError}>Error: {query.error.message}</Match>
153 <Match when={query.isSuccess}>
154 <div>
155 <h1>{query.data.name}</h1>
156 <p>{query.data.description}</p>
157 <strong>π {query.data.subscribers_count}</strong>{' '}
158 <strong>β¨ {query.data.stargazers_count}</strong>{' '}
159 <strong>π΄ {query.data.forks_count}</strong>
160 </div>
161 </Match>
162 </Switch>
163 )
164}
165```
166β
167- Signals and store values can be passed in directly to function arguments. Solid Query will update the query `store` automatically.
168β
169```tsx
170import {
171 QueryClient,
172 QueryClientProvider,
173 createQuery,
174} from '@tanstack/solid-query'
175import { createSignal, For } from 'solid-js'
176β
177const queryClient = new QueryClient()
178β
179function Example() {
180 const [enabled, setEnabled] = createSignal(false)
181 const [todo, setTodo] = createSignal(0)
182β
183 // β
passing a signal directly is safe and observers update
184 // automatically when the value of a signal changes
185 const todosQuery = createQuery(() => ({
186 queryKey: ['todos'],
187 queryFn: fetchTodos,
188 enabled: enabled(),
189 }))
190β
191 const todoDetailsQuery = createQuery(() => ({
192 queryKey: ['todo', todo()],
193 queryFn: fetchTodo,
194 enabled: todo() > 0,
195 }))
196β
197 return (
198 <div>
199 <Switch>
200 <Match when={query.isPending}>
201 <p>Loading...</p>
202 </Match>
203 <Match when={query.isError}>
204 <p>Error: {query.error.message}</p>
205 </Match>
206 <Match when={query.isSuccess}>
207 <For each={query.data}>
208 {(todo) => (
209 <button onClick={() => setTodo(todo.id)}>{todo.title}</button>
210 )}
211 </For>
212 </Match>
213 </Switch>
214 <button onClick={() => setEnabled(!enabled())}>Toggle enabled</button>
215 </div>
216 )
217}
218β
219function App() {
220 return (
221 <QueryClientProvider client={queryClient}>
222 <Example />
223 </QueryClientProvider>
224 )
225}
226```
227β
228- Errors can be caught and reset using SolidJS' native `ErrorBoundary` component.
229 Set `throwOnError` or the `suspense` option to `true` to make sure errors are thrown to the `ErrorBoundary`
230β
231- Since Property tracking is handled through Solid's fine grained reactivity, options like `notifyOnChangeProps` are not needed