Skip to content
Source
Sign inSign up
TanStack/db
Open History to see the last commit

overview.md

189 lines5.3 KB

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 )
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>
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 )
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>
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>
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>
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))
182​
183function TodoList() {
184 // Pass existing collection
185 const query = useLiveQuery(() => todosQuery)
186​
187 return <div>{query.data.length} todos</div>
189```