Skip to main content

​
Overview

The QueryObserver class is used to subscribe to a query and receive reactive updates when the query’s state changes. It’s the foundation for framework-specific hooks like useQuery in React.

​
Constructor

const observer = new QueryObserver<TQueryFnData, TError, TData, TQueryData, TQueryKey>(
  client: QueryClient,
  options: QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>
)
​
client
QueryClient
required
The QueryClient instance
​
options
QueryObserverOptions
required
Options for the query observer
Example: 
const observer = new QueryObserver(queryClient, {
  queryKey: ['todos'],
  queryFn: fetchTodos,
  staleTime: 5000,
})

​
Methods

​
subscribe()

Subscribes to query updates. 
const unsubscribe = observer.subscribe(
  listener: (result: QueryObserverResult<TData, TError>) => void
): () => void
​
listener
(result: QueryObserverResult<TData, TError>) => void
required
Callback function that receives query results
Returns: Function to unsubscribe Example: 
const unsubscribe = observer.subscribe((result) => {
  console.log('Data:', result.data)
  console.log('Status:', result.status)
  console.log('Is loading:', result.isLoading)
})

// Later, unsubscribe
unsubscribe()

​
getCurrentResult()

Returns the current result without subscribing. 
const result = observer.getCurrentResult(): QueryObserverResult<TData, TError>
Returns: Current query result
​
QueryObserverResult
object

​
setOptions()

Updates the observer’s options. 
observer.setOptions(
  options: QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>
): void
​
options
QueryObserverOptions
required
New options for the observer
Example: 
observer.setOptions({
  queryKey: ['todos'],
  queryFn: fetchTodos,
  staleTime: 10000, // Updated stale time
})

​
getOptimisticResult()

Returns an optimistic result based on the provided options, without triggering a fetch. 
const result = observer.getOptimisticResult(
  options: DefaultedQueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>
): QueryObserverResult<TData, TError>
Returns: Optimistic query result
This method is useful for framework integrations that need to compute what the result would be before actually subscribing.

​
refetch()

Manually refetches the query. 
const result = await observer.refetch(options?: RefetchOptions): Promise<QueryObserverResult<TData, TError>>
​
options
RefetchOptions
Returns: Promise resolving to the query result Example: 
const result = await observer.refetch()
console.log('Refetched data:', result.data)

​
fetchOptimistic()

Fetches a query with new options without subscribing. 
const result = await observer.fetchOptimistic(
  options: QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>
): Promise<QueryObserverResult<TData, TError>>
Returns: Promise resolving to the query result

​
getCurrentQuery()

Returns the underlying Query instance. 
const query = observer.getCurrentQuery(): Query<TQueryFnData, TError, TQueryData, TQueryKey>
Returns: The Query instance

​
trackResult()

Returns a proxied result that tracks which properties are accessed. 
const trackedResult = observer.trackResult(
  result: QueryObserverResult<TData, TError>,
  onPropTracked?: (key: keyof QueryObserverResult) => void
): QueryObserverResult<TData, TError>
This is used internally for optimizing re-renders by only triggering updates when tracked properties change.

​
destroy()

Destroys the observer and unsubscribes from the query. 
observer.destroy(): void
Example: 
observer.destroy()

​
Properties

​
options

The current options for the observer. 
observer.options: QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>

​
Type Parameters

  • TQueryFnData - The type of data returned by the query function
  • TError - The type of error that can be thrown (defaults to DefaultError)
  • TData - The type of data after selection/transformation
  • TQueryData - The type of data stored in the cache
  • TQueryKey - The type of the query key

​
Usage Example

import { QueryClient, QueryObserver } from '@tanstack/query-core'

const queryClient = new QueryClient()

const observer = new QueryObserver(queryClient, {
  queryKey: ['todos'],
  queryFn: async () => {
    const response = await fetch('/api/todos')
    return response.json()
  },
  staleTime: 5000,
})

// Subscribe to updates
const unsubscribe = observer.subscribe((result) => {
  if (result.isLoading) {
    console.log('Loading...')
  } else if (result.isError) {
    console.error('Error:', result.error)
  } else if (result.isSuccess) {
    console.log('Data:', result.data)
  }
})

// Later, clean up
unsubscribe()
observer.destroy()

Build docs developers (and LLMs) love

Get started for freeTalk to us