Open History to see the last commit
1---
2id: quick-start
3title: Quick Start
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 useQuery,
15} from '@tanstack/solid-query'
16import { Switch, Match, For } from 'solid-js'
17β
18const queryClient = new QueryClient()
19β
20function Example() {
21 const query = useQuery(() => ({
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## Important Differences between Solid Query & React Query
53β
54Solid Query offers an API similar to React Query, but there are some key differences to be mindful of.
55β
56- Arguments to `solid-query` primitives (like `useQuery`, `useMutation`, `useIsFetching`) are functions, so that they can be tracked in a reactive scope.
57β
58```tsx
59// β react version
60useQuery({
61 queryKey: ['todos', todo],
62 queryFn: fetchTodos,
63})
64β
65// β
solid version
66useQuery(() => ({
67 queryKey: ['todos', todo],
68 queryFn: fetchTodos,
69}))
70```
71β
72- Suspense works for queries out of the box if you access the query data inside a `<Suspense>` boundary.
73β
74```tsx
75import { For, Suspense } from 'solid-js'
76β
77function Example() {
78 const query = useQuery(() => ({
79 queryKey: ['todos'],
80 queryFn: fetchTodos,
81 }))
82 return (
83 <div>
84 {/* β
Will trigger loading fallback, data accessed in a suspense boundary. */}
85 <Suspense fallback={'Loading...'}>
86 <For each={query.data}>{(todo) => <div>{todo.title}</div>}</For>
87 </Suspense>
88 {/* β Will not trigger loading fallback, data not accessed in a suspense boundary. */}
89 <For each={query.data}>{(todo) => <div>{todo.title}</div>}</For>
90 </div>
91 )
92}
93```
94β
95- Solid Query primitives do not support destructuring. The return value from these functions is a store, and their properties are only tracked in a reactive context.
96β
97```tsx
98import {
99 QueryClient,
100 QueryClientProvider,
101 useQuery,
102} 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 { isPending, error, data } = useQuery({
118 // queryKey: ['repoData'],
119 // queryFn: () =>
120 // fetch('https://api.github.com/repos/TanStack/query').then(
121 // (res) => res.json()
122 // ),
123 // })
124β
125 // β
solid version -- does not support destructuring outside reactive context
126 const query = useQuery(() => ({
127 queryKey: ['repoData'],
128 queryFn: () =>
129 fetch('https://api.github.com/repos/TanStack/query').then((res) =>
130 res.json(),
131 ),
132 }))
133β
134 // β
access query properties in JSX reactive context
135 return (
136 <Switch>
137 <Match when={query.isPending}>Loading...</Match>
138 <Match when={query.isError}>Error: {query.error.message}</Match>
139 <Match when={query.isSuccess}>
140 <div>
141 <h1>{query.data.name}</h1>
142 <p>{query.data.description}</p>
143 <strong>π {query.data.subscribers_count}</strong>{' '}
144 <strong>β¨ {query.data.stargazers_count}</strong>{' '}
145 <strong>π΄ {query.data.forks_count}</strong>
146 </div>
147 </Match>
148 </Switch>
149 )
150}
151```
152β
153- Signals and store values can be passed in directly to function arguments. Solid Query will update the query `store` automatically.
154β
155```tsx
156import {
157 QueryClient,
158 QueryClientProvider,
159 useQuery,
160} from '@tanstack/solid-query'
161import { createSignal, For } from 'solid-js'
162β
163const queryClient = new QueryClient()
164β
165function Example() {
166 const [enabled, setEnabled] = createSignal(false)
167 const [todo, setTodo] = createSignal(0)
168β
169 // β
passing a signal directly is safe and observers update
170 // automatically when the value of a signal changes
171 const todosQuery = useQuery(() => ({
172 queryKey: ['todos'],
173 queryFn: fetchTodos,
174 enabled: enabled(),
175 }))
176β
177 const todoDetailsQuery = useQuery(() => ({
178 queryKey: ['todo', todo()],
179 queryFn: fetchTodo,
180 enabled: todo() > 0,
181 }))
182β
183 return (
184 <div>
185 <Switch>
186 <Match when={todosQuery.isPending}>
187 <p>Loading...</p>
188 </Match>
189 <Match when={todosQuery.isError}>
190 <p>Error: {todosQuery.error.message}</p>
191 </Match>
192 <Match when={todosQuery.isSuccess}>
193 <For each={todosQuery.data}>
194 {(todo) => (
195 <button onClick={() => setTodo(todo.id)}>{todo.title}</button>
196 )}
197 </For>
198 </Match>
199 </Switch>
200 <button onClick={() => setEnabled(!enabled())}>Toggle enabled</button>
201 </div>
202 )
203}
204β
205function App() {
206 return (
207 <QueryClientProvider client={queryClient}>
208 <Example />
209 </QueryClientProvider>
210 )
211}
212```
213β
214- Errors can be caught and reset using SolidJS' native `ErrorBoundary` component.
215 Set `throwOnError` to `true` to make sure errors are thrown to the `ErrorBoundary`
216β
217- Since Property tracking is handled through Solid's fine grained reactivity, options like `notifyOnChangeProps` are not needed