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

overview.md

212 lines5.5 KB

1---
2title: TanStack DB Angular Adapter
3id: adapter
4---
5​
6## Installation
7​
8```sh
9npm install @tanstack/angular-db
10```
11​
12## Angular inject function
13​
14See the [Angular Functions Reference](./reference/index.md) to see the full list of functions available in the Angular 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### injectLiveQuery
21​
22The `injectLiveQuery` function creates a live query that automatically updates your component when data changes. It returns an object containing Angular signals for reactive state management:
23​
24```typescript
25import { Component } from '@angular/core'
26import { injectLiveQuery } from '@tanstack/angular-db'
27import { eq } from '@tanstack/db'
28​
29@Component({
30 selector: 'app-todo-list',
31 standalone: true,
32 template: `
33 @if (query.isLoading()) {
34 <div>Loading...</div>
35 } @else {
36 <ul>
37 @for (todo of query.data(); track todo.id) {
38 <li>{{ todo.text }}</li>
39 }
40 </ul>
41 }
42 `
43})
44export class TodoListComponent {
45 query = injectLiveQuery((q) =>
46 q.from({ todos: todosCollection })
47 .where(({ todos }) => eq(todos.completed, false))
48 .select(({ todos }) => ({ id: todos.id, text: todos.text }))
49 )
51```
52​
53**Note:** All return values (`data`, `isLoading`, `status`, etc.) are Angular signals, so call them with `()` in your template: `query.data()`, `query.isLoading()`.
54​
55> **Template Syntax:** Examples use Angular 17+ control flow (`@if`, `@for`). For Angular 16, use `*ngIf` and `*ngFor` instead.
56​
57### Reactive Parameters
58​
59For queries that depend on reactive values, use the `params` option to re-run the query when those values change:
60​
61```typescript
62import { Component, signal } from '@angular/core'
63import { injectLiveQuery } from '@tanstack/angular-db'
64import { gt } from '@tanstack/db'
65​
66@Component({
67 selector: 'app-filtered-todos',
68 standalone: true,
69 template: `
70 <div>{{ query.data().length }} high-priority todos</div>
71 `
72})
73export class FilteredTodosComponent {
74 minPriority = signal(5)
75​
76 query = injectLiveQuery({
77 params: () => ({ minPriority: this.minPriority() }),
78 query: ({ params, q }) =>
79 q.from({ todos: todosCollection })
80 .where(({ todos }) => gt(todos.priority, params.minPriority))
81 })
83```
84​
85#### When to Use Reactive Parameters
86​
87Use the reactive `params` option when your query depends on:
88- Component signals
89- Input properties
90- Computed values
91- Other reactive state
92​
93When any reactive value accessed in the `params` function changes, the query is recreated and re-executed.
94​
95#### What Happens When Parameters Change
96​
97When a parameter value changes:
981. The previous live-query collection is disposed
992. A new query is created with the updated parameter values
1003. `status()`/`isLoading()` reflect the new query's lifecycle
1014. `data()` updates automatically when the new results arrive
102​
103#### Best Practices
104​
105**Use reactive params for dynamic queries:**
106​
107```typescript
108import { Component, Input, signal } from '@angular/core'
109import { injectLiveQuery } from '@tanstack/angular-db'
110import { eq, and } from '@tanstack/db'
111​
112@Component({
113 selector: 'app-todo-list',
114 standalone: true,
115 template: `<div>{{ query.data().length }} todos</div>`
116})
117export class TodoListComponent {
118 // Angular 16+ compatible input
119 @Input({ required: true }) userId!: number
120 status = signal('active')
121​
122 // Good - reactive params track all dependencies
123 query = injectLiveQuery({
124 params: () => ({
125 userId: this.userId,
126 status: this.status()
127 }),
128 query: ({ params, q }) =>
129 q.from({ todos: todosCollection })
130 .where(({ todos }) => and(
131 eq(todos.userId, params.userId),
132 eq(todos.status, params.status)
133 ))
134 })
136```
137​
138**Using Angular 17+ signal inputs:**
139​
140```typescript
141import { Component, input, signal } from '@angular/core'
142import { injectLiveQuery } from '@tanstack/angular-db'
143import { eq, and } from '@tanstack/db'
144​
145@Component({
146 selector: 'app-todo-list',
147 standalone: true,
148 template: `<div>{{ query.data().length }} todos</div>`
149})
150export class TodoListComponent {
151 // Angular 17+ signal-based input
152 userId = input.required<number>()
153 status = signal('active')
154​
155 query = injectLiveQuery({
156 params: () => ({
157 userId: this.userId(),
158 status: this.status()
159 }),
160 query: ({ params, q }) =>
161 q.from({ todos: todosCollection })
162 .where(({ todos }) => and(
163 eq(todos.userId, params.userId),
164 eq(todos.status, params.status)
165 ))
166 })
168```
169​
170**Static queries don't need params:**
171​
172```typescript
173import { Component } from '@angular/core'
174import { injectLiveQuery } from '@tanstack/angular-db'
175​
176@Component({
177 selector: 'app-all-todos',
178 standalone: true,
179 template: `<div>{{ query.data().length }} todos</div>`
180})
181export class AllTodosComponent {
182 // No reactive dependencies - query never changes
183 query = injectLiveQuery((q) =>
184 q.from({ todos: todosCollection })
185 )
187```
188​
189**Access multiple signals in template:**
190​
191```typescript
192import { Component } from '@angular/core'
193import { injectLiveQuery } from '@tanstack/angular-db'
194import { eq } from '@tanstack/db'
195​
196@Component({
197 selector: 'app-todos',
198 standalone: true,
199 template: `
200 <div>Status: {{ query.status() }}</div>
201 <div>Loading: {{ query.isLoading() }}</div>
202 <div>Ready: {{ query.isReady() }}</div>
203 <div>Total: {{ query.data().length }}</div>
204 `
205})
206export class TodosComponent {
207 query = injectLiveQuery((q) =>
208 q.from({ todos: todosCollection })
209 .where(({ todos }) => eq(todos.completed, false))
210 )
212```