Open History to see the last commit
1---
2title: TanStack DB Solid Adapter
3id: adapter
4---
5
6## Installation
7
8```sh
9npm install @tanstack/solid-db
10```
11
12## Solid Primitives
13
14See the [Solid Functions Reference](./reference/index.md) to see the full list of primitives available in the Solid Adapter.
15
16For comprehensive documentation on writing queries (filtering, joins, aggregations, etc.), see the [Live Queries Guide](../../guides/live-queries).
17
18## Basic Usage
19
20### useLiveQuery
21
22The `useLiveQuery` primitive creates a live query that automatically updates your component when data changes. It returns an object where `data` is a plain array and status fields (e.g. `isLoading()`, `status()`) are accessors:
23
24```tsx
25import { useLiveQuery } from '@tanstack/solid-db'
26import { eq } from '@tanstack/db'
27import { Show, For } from 'solid-js'
28
29function TodoList() {
30 const query = useLiveQuery((q) =>
31 q.from({ todos: todosCollection })
32 .where(({ todos }) => eq(todos.completed, false))
33 .select(({ todos }) => ({ id: todos.id, text: todos.text }))
34 )
35
36 return (
37 <Show when={!query.isLoading()} fallback={<div>Loading...</div>}>
38 <ul>
39 <For each={query.data}>
40 {(todo) => <li>{todo.text}</li>}
41 </For>
42 </ul>
43 </Show>
44 )
45}
46```
47
48**Note:** `query.data` returns an array directly (not a function), but status fields like `isLoading()`, `status()`, etc. are accessor functions.
49
50### Reactive Queries with Signals
51
52Solid uses fine-grained reactivity, which means queries automatically track and respond to signal changes. Simply call signals inside your query function, and Solid will automatically recompute when they change:
53
54```tsx
55import { createSignal } from 'solid-js'
56import { useLiveQuery } from '@tanstack/solid-db'
57import { gt } from '@tanstack/db'
58
59function FilteredTodos(props: { minPriority: number }) {
60 const query = useLiveQuery((q) =>
61 q.from({ todos: todosCollection })
62 .where(({ todos }) => gt(todos.priority, props.minPriority))
63 )
64
65 return <div>{query.data.length} high-priority todos</div>
66}
67```
68
69When `props.minPriority` changes, Solid's reactivity system automatically:
701. Detects the prop access inside the query function
712. Cleans up the previous live query collection
723. Creates a new query with the updated value
734. Updates the component with the new data
74
75#### Using Signals from Component State
76
77```tsx
78import { createSignal } from 'solid-js'
79import { useLiveQuery } from '@tanstack/solid-db'
80import { eq, and } from '@tanstack/db'
81
82function TodoList() {
83 const [userId, setUserId] = createSignal(1)
84 const [status, setStatus] = createSignal('active')
85
86 // Solid automatically tracks userId() and status() calls
87 const query = useLiveQuery((q) =>
88 q.from({ todos: todosCollection })
89 .where(({ todos }) => and(
90 eq(todos.userId, userId()),
91 eq(todos.status, status())
92 ))
93 )
94
95 return (
96 <div>
97 <select onChange={(e) => setStatus(e.currentTarget.value)}>
98 <option value="active">Active</option>
99 <option value="completed">Completed</option>
100 </select>
101 <div>{query.data.length} todos</div>
102 </div>
103 )
104}
105```
106
107**Key Point:** Unlike React, you don't need dependency arrays. Solid's reactive system automatically tracks any signals, props, or stores accessed during query execution.
108
109#### Best Practices
110
111**Access signals inside the query function:**
112
113```tsx
114import { createSignal } from 'solid-js'
115import { useLiveQuery } from '@tanstack/solid-db'
116import { gt } from '@tanstack/db'
117
118function TodoList() {
119 const [minPriority, setMinPriority] = createSignal(5)
120
121 // Good - signal accessed inside query function
122 const query = useLiveQuery((q) =>
123 q.from({ todos: todosCollection })
124 .where(({ todos }) => gt(todos.priority, minPriority()))
125 )
126
127 // Solid automatically tracks minPriority() and recomputes when it changes
128 return <div>{query.data.length} todos</div>
129}
130```
131
132**Don't read signals outside the query function:**
133
134```tsx
135import { createSignal } from 'solid-js'
136import { useLiveQuery } from '@tanstack/solid-db'
137import { gt } from '@tanstack/db'
138
139function TodoList() {
140 const [minPriority, setMinPriority] = createSignal(5)
141
142 // Bad - reading signal outside query function
143 const currentPriority = minPriority()
144 const query = useLiveQuery((q) =>
145 q.from({ todos: todosCollection })
146 .where(({ todos }) => gt(todos.priority, currentPriority))
147 )
148 // Won't update when minPriority changes!
149
150 return <div>{query.data.length} todos</div>
151}
152```
153
154**Static queries need no special handling:**
155
156```tsx
157import { useLiveQuery } from '@tanstack/solid-db'
158
159function AllTodos() {
160 // No signals accessed - query never changes
161 const query = useLiveQuery((q) =>
162 q.from({ todos: todosCollection })
163 )
164
165 return <div>{query.data.length} todos</div>
166}
167```
168
169### Using Pre-created Collections
170
171You can also pass an existing collection to `useLiveQuery`. This is useful for sharing queries across components:
172
173```tsx
174import { createLiveQueryCollection } from '@tanstack/db'
175import { useLiveQuery } from '@tanstack/solid-db'
176
177// Create collection outside component
178const todosQuery = createLiveQueryCollection((q) =>
179 q.from({ todos: todosCollection })
180 .where(({ todos }) => eq(todos.active, true))
181)
182
183function TodoList() {
184 // Pass existing collection
185 const query = useLiveQuery(() => todosQuery)
186
187 return <div>{query.data.length} todos</div>
188}
189```