Resource API
IMPORTANT: toResource is experimental. Its API may change in minor and patch releases. Pin @tanstack/angular-query to an exact version when using this feature.
Angular Query can convert any query result into an Angular Resource-compatible view with toResource. The query remains responsible for fetching and caching the server state while Angular APIs can consume the familiar Resource shape.
import { Component, input } from '@angular/core'
import { injectQuery, toResource } from '@tanstack/angular-query'
@Component({
selector: 'todo-detail',
template: `
@if (todo.hasValue()) {
<h1>{{ todo.value().title }}</h1>
}
`,
})
export class TodoDetail {
readonly id = input.required<number>()
readonly todoQuery = injectQuery(() => {
const id = this.id()
return {
queryKey: ['todo', id],
queryFn: () => fetchTodo(id),
}
})
readonly todo = toResource(this.todoQuery)
}The Resource view exposes these fields:
| Field | Description |
|---|---|
| value | The current query data |
| status | The query state as an Angular ResourceStatus |
| error | The current error, normalized to Error |
| isLoading | Whether the query is loading or reloading |
| hasValue | Whether a value is available |
| snapshot | The current Resource state as one signal |
| reload | Refetches when the query is stale and returns whether a fetch started |
Use the query's field signals and methods for normal application code. Use toResource(query) when an Angular API expects a Resource or when Resource terminology makes an integration clearer. Call query.refetch() instead of resource.reload() when you need an unconditional refetch.
Errors#
value() throws when the Resource's status is error. Read hasValue() before accessing it, or inspect error() and snapshot() to render an error state. A failed background refetch can leave cached data available through query.data() while the Resource is in its error state.
Resource errors are not automatically reported globally. See Error handling for an opt-in ErrorHandler integration.
Using Resource with Signal Forms#
Signal Forms integration requires Angular 21 or newer.
Angular Signal Forms' validateAsync accepts a Resource factory. Passing injectQuery(...) to toResource lets async validation use Angular Query caching, request deduplication, cancellation, retries, and stale-time behavior.
The example below validates a username. The query is disabled while the field has no value, and the factory returns toResource(query).
In Angular 21, validateAsync's factory requires a return type of ResourceRef while the implementation works with the read-only Resource interface returned by toResource. To use the integration, cast the result of toResource as toResource(query) as unknown as ResourceRef<T | undefined> where T is the query's data type.
The debounce option on validateAsync does not work with toResource(query) due to an upstream Angular issue. Use debounce from @angular/forms/signals on the field instead. This delays updates from the input to the form model by 300 ms; blurring the field or submitting the form flushes the pending update immediately.
import { Component, inject, signal } from '@angular/core'
import {
FormField,
debounce,
form,
validateAsync,
} from '@angular/forms/signals'
import { injectQuery, toResource } from '@tanstack/angular-query'
type UsernameValidation = {
available: boolean
}
@Component({
selector: 'registration-form',
imports: [FormField],
template: `<input [formField]="registrationForm.username" />`,
})
export class RegistrationForm {
private readonly users = inject(UserService)
readonly model = signal({ username: '' })
readonly registrationForm = form(this.model, (path) => {
debounce(path.username, 300)
validateAsync(path.username, {
params: ({ value }) => value().trim() || undefined,
factory: (username) =>
toResource(
injectQuery(() => {
const name = username()
return {
queryKey: ['username-availability', name],
enabled: !!name,
queryFn: (): Promise<UsernameValidation> =>
this.users.checkUsername(name!),
}
}),
),
onSuccess: (result) =>
result?.available
? null
: {
kind: 'usernameTaken',
message: 'Username is already taken',
},
onError: () => ({
kind: 'usernameUnavailable',
message: 'Could not check username availability',
}),
})
})
}Calling reloadValidation() on the field refetches the query only when its cached data is stale.
Comparison#
Choosing between Angular's built-in resource and TanStack Query depends on whether the operation is isolated async state or server state shared across the application.
This table focuses on built-in behavior and may not capture every custom implementation. Review both APIs for the needs of your application.
Feature/Capability Key:
- âś… 1st-class, built-in, and ready to use with no added configuration or code
- đźź Supported through an additional package
- đź”¶ Possible, but requires custom application code
- 🛑 Not built in
| Angular resource | TanStack Query | |
|---|---|---|
| Reactive parameters and signal state | âś… | âś… |
| Request cancellation | âś… | âś… |
| Angular Resource interface | âś… | âś… Through toResource(query) |
| Shared cache by data identity | 🛑 | ✅ Query keys identify cached data |
| Request deduplication across components | 🛑 | ✅ For queries with the same key |
| Stale and garbage-collection timing | đź”¶ | âś… staleTime and gcTime |
| Cache invalidation and updates | đź”¶ | âś… invalidateQueries and setQueryData |
| Retries and background refetching | đź”¶ | âś… Including focus and reconnect refetching |
| Mutations and optimistic updates | đź”¶ | âś… injectMutation and QueryClient cache updates |
| SSR | âś… A resource can transfer its value with id | âś… The complete query cache is hydrated automatically |
| Persistence | đź”¶ | đźź Through the persistence package |
Angular resource is a good fit for a self-contained asynchronous task. It retains the value of its own instance and can transfer that value during SSR, but it does not provide a shared, query-keyed cache or coordinate invalidation and mutations across the application. Use TanStack Query for server data that is reused, cached, invalidated, mutated, retried, or persisted.