Skip to Content
⚠️Active Development Notice: TimeTiles is under active development. Information may be placeholder content or not up-to-date.
ReferenceAPI ReferenceLibraryHooksUse Events Queries

web

web / lib/hooks/use-events-queries

lib/hooks/use-events-queries

This file centralizes all TanStack Query (React Query) hooks for fetching events-related data.

It defines the data fetching functions, query keys, and custom hooks for various API endpoints, including:

  • Fetching lists of events.
  • Retrieving map clusters for efficient visualization of large datasets.
  • Getting data for temporal histograms.

By co-locating these hooks, it provides a consistent and organized way to manage server state related to events throughout the application.

Interfaces

EventsListResponse

Client-side events list response (flattened from API pagination shape).

Properties

events

events: object[]

id

id: number

dataset

dataset: object

dataset.id

id: number

dataset.title?

optional title: string

dataset.catalog?

optional catalog: string

data

data: Record<string, unknown>

location

location: { longitude: number; latitude: number; } | null

eventTimestamp

eventTimestamp: string

isValid

isValid: boolean

total

total: number

page

page: number

limit

limit: number

hasNextPage

hasNextPage: boolean

hasPrevPage

hasPrevPage: boolean

MapClustersResponse

Client-side map clusters response (subset of API GeoJSON FeatureCollection).

Properties

features

features: ClusterFeature[]

Variables

eventsQueryKeys

const eventsQueryKeys: object

Type Declaration

all

all: readonly ["events"]

detail()

detail: (eventId) => readonly ["events", "detail", number]

Parameters
eventId

number

Returns

readonly ["events", "detail", number]

lists()

lists: () => readonly ["events", "list"]

Returns

readonly ["events", "list"]

list()

list: (filters, bounds, limit, scope?) => readonly ["events", "list", { filters: [FilterState](../types/filter-state.md#filterstate); bounds: [BoundsType](../utils/event-params.md#boundstype); limit: number; scope: [ViewScope](../utils/event-params.md#viewscope) \| undefined; }]

Parameters
filters

FilterState

bounds

BoundsType

limit

number

scope?

ViewScope

Returns

readonly ["events", "list", { filters: [FilterState](../types/filter-state.md#filterstate); bounds: [BoundsType](../utils/event-params.md#boundstype); limit: number; scope: [ViewScope](../utils/event-params.md#viewscope) \| undefined; }]

infinite()

infinite: () => readonly ["events", "infinite"]

Returns

readonly ["events", "infinite"]

infiniteList()

infiniteList: (filters, bounds, limit, scope?) => readonly ["events", "infinite", { filters: [FilterState](../types/filter-state.md#filterstate); bounds: [BoundsType](../utils/event-params.md#boundstype); limit: number; scope: [ViewScope](../utils/event-params.md#viewscope) \| undefined; }]

Parameters
filters

FilterState

bounds

BoundsType

limit

number

scope?

ViewScope

Returns

readonly ["events", "infinite", { filters: [FilterState](../types/filter-state.md#filterstate); bounds: [BoundsType](../utils/event-params.md#boundstype); limit: number; scope: [ViewScope](../utils/event-params.md#viewscope) \| undefined; }]

clusters()

clusters: () => readonly ["events", "clusters"]

Returns

readonly ["events", "clusters"]

cluster()

cluster: (filters, bounds, zoom, scope?) => readonly ["events", "clusters", { filters: [FilterState](../types/filter-state.md#filterstate); bounds: [BoundsType](../utils/event-params.md#boundstype); zoom: number; scope: [ViewScope](../utils/event-params.md#viewscope) \| undefined; }]

Parameters
filters

FilterState

bounds

BoundsType

zoom

number

scope?

ViewScope

Returns

readonly ["events", "clusters", { filters: [FilterState](../types/filter-state.md#filterstate); bounds: [BoundsType](../utils/event-params.md#boundstype); zoom: number; scope: [ViewScope](../utils/event-params.md#viewscope) \| undefined; }]

clusterStats()

clusterStats: () => readonly ["events", "cluster-stats"]

Returns

readonly ["events", "cluster-stats"]

clusterStat()

clusterStat: (filters, scope?) => readonly ["events", "cluster-stats", { filters: [FilterState](../types/filter-state.md#filterstate); scope: [ViewScope](../utils/event-params.md#viewscope) \| undefined; }]

Parameters
filters

FilterState

scope?

ViewScope

Returns

readonly ["events", "cluster-stats", { filters: [FilterState](../types/filter-state.md#filterstate); scope: [ViewScope](../utils/event-params.md#viewscope) \| undefined; }]

histograms()

histograms: () => readonly ["events", "histogram"]

Returns

readonly ["events", "histogram"]

histogram()

histogram: (filters, bounds, scope?) => readonly ["events", "histogram", { filters: [FilterState](../types/filter-state.md#filterstate); bounds: [BoundsType](../utils/event-params.md#boundstype); scope: [ViewScope](../utils/event-params.md#viewscope) \| undefined; }]

Parameters
filters

FilterState

bounds

BoundsType

scope?

ViewScope

Returns

readonly ["events", "histogram", { filters: [FilterState](../types/filter-state.md#filterstate); bounds: [BoundsType](../utils/event-params.md#boundstype); scope: [ViewScope](../utils/event-params.md#viewscope) \| undefined; }]

aggregations()

aggregations: () => readonly ["events", "aggregation"]

Returns

readonly ["events", "aggregation"]

aggregation()

aggregation: (filters, bounds, groupBy, scope?) => readonly ["events", "aggregation", { filters: [FilterState](../types/filter-state.md#filterstate); bounds: [BoundsType](../utils/event-params.md#boundstype); groupBy: "catalog" \| "dataset"; scope: [ViewScope](../utils/event-params.md#viewscope) \| undefined; }]

Parameters
filters

FilterState

bounds

BoundsType

groupBy

"catalog" | "dataset"

scope?

ViewScope

Returns

readonly ["events", "aggregation", { filters: [FilterState](../types/filter-state.md#filterstate); bounds: [BoundsType](../utils/event-params.md#boundstype); groupBy: "catalog" \| "dataset"; scope: [ViewScope](../utils/event-params.md#viewscope) \| undefined; }]

histogramsFull()

histogramsFull: () => readonly ["events", "histogram-full"]

Returns

readonly ["events", "histogram-full"]

histogramFull()

histogramFull: (filters, scope?) => readonly ["events", "histogram-full", { catalog: string \| null; datasets: string[]; scope: [ViewScope](../utils/event-params.md#viewscope) \| undefined; }]

Parameters
filters

FilterState

scope?

ViewScope

Returns

readonly ["events", "histogram-full", { catalog: string \| null; datasets: string[]; scope: [ViewScope](../utils/event-params.md#viewscope) \| undefined; }]

bounds()

bounds: () => readonly ["events", "bounds"]

Returns

readonly ["events", "bounds"]

boundsFiltered()

boundsFiltered: (filters, scope?) => readonly ["events", "bounds", { filters: [FilterState](../types/filter-state.md#filterstate); scope: [ViewScope](../utils/event-params.md#viewscope) \| undefined; }]

Parameters
filters

FilterState

scope?

ViewScope

Returns

readonly ["events", "bounds", { filters: [FilterState](../types/filter-state.md#filterstate); scope: [ViewScope](../utils/event-params.md#viewscope) \| undefined; }]

Functions

useEventsListQuery()

useEventsListQuery(filters, bounds, limit?, enabled?, scope?): UseQueryResult<EventsListResponse, Error>

Parameters

filters

FilterState

bounds

BoundsType

limit?

number = 1000

enabled?

boolean = true

scope?

ViewScope

Returns

UseQueryResult<EventsListResponse, Error>

useEventsTotalQuery()

useEventsTotalQuery(filters, enabled?, scope?): UseQueryResult<EventsListResponse, Error>

Parameters

filters

FilterState

enabled?

boolean = true

scope?

ViewScope

Returns

UseQueryResult<EventsListResponse, Error>

useMapClustersQuery()

useMapClustersQuery(filters, bounds, zoom, enabled?, scope?): UseQueryResult<MapClustersResponse, Error>

Parameters

filters

FilterState

bounds

BoundsType

zoom

number

enabled?

boolean = true

scope?

ViewScope

Returns

UseQueryResult<MapClustersResponse, Error>

useHistogramQuery()

useHistogramQuery(filters, bounds, enabled?, scope?): UseQueryResult<{ histogram: object[]; metadata: \{ total: number; dateRange: \{ min: string \| null; max: string \| null; }; bucketSizeSeconds: number | null; bucketCount: number; counts: { datasets: number; catalogs: number; }; topDatasets: unknown[]; topCatalogs: unknown[]; }; }, Error>

Parameters

filters

FilterState

bounds

BoundsType

enabled?

boolean = true

scope?

ViewScope

Returns

UseQueryResult<{ histogram: object[]; metadata: \{ total: number; dateRange: \{ min: string \| null; max: string \| null; }; bucketSizeSeconds: number | null; bucketCount: number; counts: { datasets: number; catalogs: number; }; topDatasets: unknown[]; topCatalogs: unknown[]; }; }, Error>

useFullHistogramQuery()

useFullHistogramQuery(filters, scope?): UseQueryResult<{ histogram: object[]; metadata: \{ total: number; dateRange: \{ min: string \| null; max: string \| null; }; bucketSizeSeconds: number | null; bucketCount: number; counts: { datasets: number; catalogs: number; }; topDatasets: unknown[]; topCatalogs: unknown[]; }; }, Error>

Hook to fetch histogram data for the full date range (no date or bounds filters).

Used by the time range slider to show the complete temporal distribution regardless of the currently selected date range.

Parameters

filters

FilterState

scope?

ViewScope

Returns

UseQueryResult<{ histogram: object[]; metadata: \{ total: number; dateRange: \{ min: string \| null; max: string \| null; }; bucketSizeSeconds: number | null; bucketCount: number; counts: { datasets: number; catalogs: number; }; topDatasets: unknown[]; topCatalogs: unknown[]; }; }, Error>

useClusterStatsQuery()

useClusterStatsQuery(filters, enabled?, scope?): UseQueryResult<{ p20: number; p40: number; p60: number; p80: number; p100: number; }, Error>

Parameters

filters

FilterState

enabled?

boolean = true

scope?

ViewScope

Returns

UseQueryResult<{ p20: number; p40: number; p60: number; p80: number; p100: number; }, Error>

useBoundsQuery()

useBoundsQuery(filters, enabled?, scope?): UseQueryResult<BoundsResponse, Error>

Hook to fetch geographic bounds of all events matching the current filters.

Used for initial map positioning and “zoom to data” functionality. Returns the bounding box containing all accessible events.

Parameters

filters

FilterState

Current filter state (catalog, datasets, dates)

enabled?

boolean = true

Whether the query should be enabled

scope?

ViewScope

Returns

UseQueryResult<BoundsResponse, Error>

React Query result with bounds data

useEventsAggregationQuery()

useEventsAggregationQuery(filters, bounds, groupBy, enabled?, scope?): UseQueryResult<{ items: object[]; total: number; groupedBy: string; }, Error>

Parameters

filters

FilterState

bounds

BoundsType

groupBy

"catalog" | "dataset"

enabled?

boolean = true

scope?

ViewScope

Returns

UseQueryResult<{ items: object[]; total: number; groupedBy: string; }, Error>

useEventsInfiniteQuery()

useEventsInfiniteQuery(filters, bounds, limit?, enabled?, scope?): UseInfiniteQueryResult<InfiniteData<EventsListResponse, unknown>, Error>

Parameters

filters

FilterState

bounds

BoundsType

limit?

number = 20

enabled?

boolean = true

scope?

ViewScope

Returns

UseInfiniteQueryResult<InfiniteData<EventsListResponse, unknown>, Error>

useEventsInfiniteFlattened()

useEventsInfiniteFlattened(filters, bounds, limit?, enabled?, scope?): { dataUpdatedAt: number; errorUpdatedAt: number; failureCount: number; failureReason: Error \| null; errorUpdateCount: number; isFetched: boolean; isFetchedAfterMount: boolean; isFetching: boolean; isInitialLoading: boolean; isPaused: boolean; isRefetching: boolean; isStale: boolean; isEnabled: boolean; refetch: (options?) => Promise\<QueryObserverResult\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>, Error\>\>; fetchStatus: FetchStatus; promise: Promise\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>\>; fetchNextPage: (options?) => Promise\<InfiniteQueryObserverResult\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>, Error\>\>; fetchPreviousPage: (options?) => Promise\<InfiniteQueryObserverResult\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>, Error\>\>; hasNextPage: boolean; hasPreviousPage: boolean; isFetchNextPageError: boolean; isFetchingNextPage: boolean; isFetchPreviousPageError: boolean; isFetchingPreviousPage: boolean; data: InfiniteData; error: Error; isError: true; isPending: false; isLoading: false; isLoadingError: false; isRefetchError: true; isSuccess: false; isPlaceholderData: false; status: "error"; events: object[]; total: number; loadedCount: number; } | { dataUpdatedAt: number; errorUpdatedAt: number; failureCount: number; failureReason: Error \| null; errorUpdateCount: number; isFetched: boolean; isFetchedAfterMount: boolean; isFetching: boolean; isInitialLoading: boolean; isPaused: boolean; isRefetching: boolean; isStale: boolean; isEnabled: boolean; refetch: (options?) => Promise\<QueryObserverResult\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>, Error\>\>; fetchStatus: FetchStatus; promise: Promise\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>\>; fetchNextPage: (options?) => Promise\<InfiniteQueryObserverResult\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>, Error\>\>; fetchPreviousPage: (options?) => Promise\<InfiniteQueryObserverResult\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>, Error\>\>; hasNextPage: boolean; hasPreviousPage: boolean; isFetchingNextPage: boolean; isFetchingPreviousPage: boolean; data: InfiniteData; error: null; isError: false; isPending: false; isLoading: false; isLoadingError: false; isRefetchError: false; isFetchNextPageError: false; isFetchPreviousPageError: false; isSuccess: true; isPlaceholderData: false; status: "success"; events: object[]; total: number; loadedCount: number; } | { dataUpdatedAt: number; errorUpdatedAt: number; failureCount: number; failureReason: Error \| null; errorUpdateCount: number; isFetched: boolean; isFetchedAfterMount: boolean; isFetching: boolean; isInitialLoading: boolean; isPaused: boolean; isRefetching: boolean; isStale: boolean; isEnabled: boolean; refetch: (options?) => Promise\<QueryObserverResult\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>, Error\>\>; fetchStatus: FetchStatus; promise: Promise\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>\>; fetchNextPage: (options?) => Promise\<InfiniteQueryObserverResult\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>, Error\>\>; fetchPreviousPage: (options?) => Promise\<InfiniteQueryObserverResult\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>, Error\>\>; hasNextPage: boolean; hasPreviousPage: boolean; isFetchingNextPage: boolean; isFetchingPreviousPage: boolean; data: undefined; error: Error; isError: true; isPending: false; isLoading: false; isLoadingError: true; isRefetchError: false; isFetchNextPageError: false; isFetchPreviousPageError: false; isSuccess: false; isPlaceholderData: false; status: "error"; events: object[]; total: number; loadedCount: number; } | { dataUpdatedAt: number; errorUpdatedAt: number; failureCount: number; failureReason: Error \| null; errorUpdateCount: number; isFetched: boolean; isFetchedAfterMount: boolean; isFetching: boolean; isInitialLoading: boolean; isPaused: boolean; isRefetching: boolean; isStale: boolean; isEnabled: boolean; refetch: (options?) => Promise\<QueryObserverResult\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>, Error\>\>; fetchStatus: FetchStatus; promise: Promise\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>\>; fetchNextPage: (options?) => Promise\<InfiniteQueryObserverResult\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>, Error\>\>; fetchPreviousPage: (options?) => Promise\<InfiniteQueryObserverResult\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>, Error\>\>; hasNextPage: boolean; hasPreviousPage: boolean; isFetchingNextPage: boolean; isFetchingPreviousPage: boolean; data: undefined; error: null; isError: false; isPending: true; isLoading: true; isLoadingError: false; isRefetchError: false; isFetchNextPageError: false; isFetchPreviousPageError: false; isSuccess: false; isPlaceholderData: false; status: "pending"; events: object[]; total: number; loadedCount: number; } | { dataUpdatedAt: number; errorUpdatedAt: number; failureCount: number; failureReason: Error \| null; errorUpdateCount: number; isFetched: boolean; isFetchedAfterMount: boolean; isFetching: boolean; isLoading: boolean; isInitialLoading: boolean; isPaused: boolean; isRefetching: boolean; isStale: boolean; isEnabled: boolean; refetch: (options?) => Promise\<QueryObserverResult\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>, Error\>\>; fetchStatus: FetchStatus; promise: Promise\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>\>; fetchNextPage: (options?) => Promise\<InfiniteQueryObserverResult\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>, Error\>\>; fetchPreviousPage: (options?) => Promise\<InfiniteQueryObserverResult\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>, Error\>\>; hasNextPage: boolean; hasPreviousPage: boolean; isFetchingNextPage: boolean; isFetchingPreviousPage: boolean; data: undefined; error: null; isError: false; isPending: true; isLoadingError: false; isRefetchError: false; isFetchNextPageError: false; isFetchPreviousPageError: false; isSuccess: false; isPlaceholderData: false; status: "pending"; events: object[]; total: number; loadedCount: number; } | { dataUpdatedAt: number; errorUpdatedAt: number; failureCount: number; failureReason: Error \| null; errorUpdateCount: number; isFetched: boolean; isFetchedAfterMount: boolean; isFetching: boolean; isInitialLoading: boolean; isPaused: boolean; isRefetching: boolean; isStale: boolean; isEnabled: boolean; refetch: (options?) => Promise\<QueryObserverResult\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>, Error\>\>; fetchStatus: FetchStatus; promise: Promise\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>\>; fetchNextPage: (options?) => Promise\<InfiniteQueryObserverResult\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>, Error\>\>; fetchPreviousPage: (options?) => Promise\<InfiniteQueryObserverResult\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>, Error\>\>; hasNextPage: boolean; hasPreviousPage: boolean; isFetchingNextPage: boolean; isFetchingPreviousPage: boolean; data: InfiniteData; isError: false; error: null; isPending: false; isLoading: false; isLoadingError: false; isRefetchError: false; isSuccess: true; isPlaceholderData: true; isFetchNextPageError: false; isFetchPreviousPageError: false; status: "success"; events: object[]; total: number; loadedCount: number; }

Parameters

filters

FilterState

bounds

BoundsType

limit?

number = 20

enabled?

boolean = true

scope?

ViewScope

Returns

{ dataUpdatedAt: number; errorUpdatedAt: number; failureCount: number; failureReason: Error \| null; errorUpdateCount: number; isFetched: boolean; isFetchedAfterMount: boolean; isFetching: boolean; isInitialLoading: boolean; isPaused: boolean; isRefetching: boolean; isStale: boolean; isEnabled: boolean; refetch: (options?) => Promise\<QueryObserverResult\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>, Error\>\>; fetchStatus: FetchStatus; promise: Promise\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>\>; fetchNextPage: (options?) => Promise\<InfiniteQueryObserverResult\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>, Error\>\>; fetchPreviousPage: (options?) => Promise\<InfiniteQueryObserverResult\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>, Error\>\>; hasNextPage: boolean; hasPreviousPage: boolean; isFetchNextPageError: boolean; isFetchingNextPage: boolean; isFetchPreviousPageError: boolean; isFetchingPreviousPage: boolean; data: InfiniteData; error: Error; isError: true; isPending: false; isLoading: false; isLoadingError: false; isRefetchError: true; isSuccess: false; isPlaceholderData: false; status: "error"; events: object[]; total: number; loadedCount: number; }

dataUpdatedAt

dataUpdatedAt: number

The timestamp for when the query most recently returned the status as "success".

errorUpdatedAt

errorUpdatedAt: number

The timestamp for when the query most recently returned the status as "error".

failureCount

failureCount: number

The failure count for the query.

  • Incremented every time the query fails.
  • Reset to 0 when the query succeeds.
failureReason

failureReason: Error | null

The failure reason for the query retry.

  • Reset to null when the query succeeds.
errorUpdateCount

errorUpdateCount: number

The sum of all errors.

isFetched

isFetched: boolean

Will be true if the query has been fetched.

isFetchedAfterMount

isFetchedAfterMount: boolean

Will be true if the query has been fetched after the component mounted.

  • This property can be used to not show any previously cached data.
isFetching

isFetching: boolean

A derived boolean from the fetchStatus variable, provided for convenience.

  • true whenever the queryFn is executing, which includes initial pending as well as background refetch.
isInitialLoading

isInitialLoading: boolean

Deprecated

isInitialLoading is being deprecated in favor of isLoading and will be removed in the next major version.

isPaused

isPaused: boolean

A derived boolean from the fetchStatus variable, provided for convenience.

  • The query wanted to fetch, but has been paused.
isRefetching

isRefetching: boolean

Is true whenever a background refetch is in-flight, which does not include initial pending.

  • Is the same as isFetching && !isPending.
isStale

isStale: boolean

Will be true if the data in the cache is invalidated or if the data is older than the given staleTime.

isEnabled

isEnabled: boolean

true if this observer is enabled, false otherwise.

refetch()

refetch: (options?) => Promise<QueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>

A function to manually refetch the query.

Parameters
options?

RefetchOptions

Returns

Promise<QueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>

fetchStatus

fetchStatus: FetchStatus

The fetch status of the query.

  • fetching: Is true whenever the queryFn is executing, which includes initial pending as well as background refetch.
  • paused: The query wanted to fetch, but has been paused.
  • idle: The query is not fetching.
  • See Network Mode  for more information.
promise

promise: Promise<InfiniteData<EventsListResponse, unknown>>

A stable promise that will be resolved with the data of the query. Requires the experimental_prefetchInRender feature flag to be enabled.

Example

Enabling the feature flag

const client = new QueryClient({
  defaultOptions: {
    queries: {
      experimental_prefetchInRender: true,
    },
  },
})

Usage

import { useQuery } from '@tanstack/react-query'
import React from 'react'
import { fetchTodos, type Todo } from './api'
 
function TodoList({ query }: { query: UseQueryResult<Todo[], Error> }) {
  const data = React.use(query.promise)
 
  return (
    <ul>
      {data.map(todo => (
        <li key={todo.id}>{todo.title}</li>
      ))}
    </ul>
  )
}
 
export function App() {
  const query = useQuery({ queryKey: ['todos'], queryFn: fetchTodos })
 
  return (
    <>
      <h1>Todos</h1>
      <React.Suspense fallback={<div>Loading...</div>}>
        <TodoList query={query} />
      </React.Suspense>
    </>
  )
}
fetchNextPage()

fetchNextPage: (options?) => Promise<InfiniteQueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>

This function allows you to fetch the next “page” of results.

Parameters
options?

FetchNextPageOptions

Returns

Promise<InfiniteQueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>

fetchPreviousPage()

fetchPreviousPage: (options?) => Promise<InfiniteQueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>

This function allows you to fetch the previous “page” of results.

Parameters
options?

FetchPreviousPageOptions

Returns

Promise<InfiniteQueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>

hasNextPage

hasNextPage: boolean

Will be true if there is a next page to be fetched (known via the getNextPageParam option).

hasPreviousPage

hasPreviousPage: boolean

Will be true if there is a previous page to be fetched (known via the getPreviousPageParam option).

isFetchNextPageError

isFetchNextPageError: boolean

Will be true if the query failed while fetching the next page.

isFetchingNextPage

isFetchingNextPage: boolean

Will be true while fetching the next page with fetchNextPage.

isFetchPreviousPageError

isFetchPreviousPageError: boolean

Will be true if the query failed while fetching the previous page.

isFetchingPreviousPage

isFetchingPreviousPage: boolean

Will be true while fetching the previous page with fetchPreviousPage.

data

data: InfiniteData

The last successfully resolved data for the query.

error

error: Error

The error object for the query, if an error was thrown.

  • Defaults to null.
isError

isError: true

A derived boolean from the status variable, provided for convenience.

  • true if the query attempt resulted in an error.
isPending

isPending: false

Will be pending if there’s no cached data and no query attempt was finished yet.

isLoading

isLoading: false

Is true whenever the first fetch for a query is in-flight.

  • Is the same as isFetching && isPending.
isLoadingError

isLoadingError: false

Will be true if the query failed while fetching for the first time.

isRefetchError

isRefetchError: true

Will be true if the query failed while refetching.

isSuccess

isSuccess: false

A derived boolean from the status variable, provided for convenience.

  • true if the query has received a response with no errors and is ready to display its data.
isPlaceholderData

isPlaceholderData: false

Will be true if the data shown is the placeholder data.

status

status: "error"

The status of the query.

  • Will be:
    • pending if there’s no cached data and no query attempt was finished yet.
    • error if the query attempt resulted in an error.
    • success if the query has received a response with no errors and is ready to display its data.
events

events: object[]

total

total: number

loadedCount

loadedCount: number = events.length

{ dataUpdatedAt: number; errorUpdatedAt: number; failureCount: number; failureReason: Error \| null; errorUpdateCount: number; isFetched: boolean; isFetchedAfterMount: boolean; isFetching: boolean; isInitialLoading: boolean; isPaused: boolean; isRefetching: boolean; isStale: boolean; isEnabled: boolean; refetch: (options?) => Promise\<QueryObserverResult\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>, Error\>\>; fetchStatus: FetchStatus; promise: Promise\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>\>; fetchNextPage: (options?) => Promise\<InfiniteQueryObserverResult\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>, Error\>\>; fetchPreviousPage: (options?) => Promise\<InfiniteQueryObserverResult\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>, Error\>\>; hasNextPage: boolean; hasPreviousPage: boolean; isFetchingNextPage: boolean; isFetchingPreviousPage: boolean; data: InfiniteData; error: null; isError: false; isPending: false; isLoading: false; isLoadingError: false; isRefetchError: false; isFetchNextPageError: false; isFetchPreviousPageError: false; isSuccess: true; isPlaceholderData: false; status: "success"; events: object[]; total: number; loadedCount: number; }

dataUpdatedAt

dataUpdatedAt: number

The timestamp for when the query most recently returned the status as "success".

errorUpdatedAt

errorUpdatedAt: number

The timestamp for when the query most recently returned the status as "error".

failureCount

failureCount: number

The failure count for the query.

  • Incremented every time the query fails.
  • Reset to 0 when the query succeeds.
failureReason

failureReason: Error | null

The failure reason for the query retry.

  • Reset to null when the query succeeds.
errorUpdateCount

errorUpdateCount: number

The sum of all errors.

isFetched

isFetched: boolean

Will be true if the query has been fetched.

isFetchedAfterMount

isFetchedAfterMount: boolean

Will be true if the query has been fetched after the component mounted.

  • This property can be used to not show any previously cached data.
isFetching

isFetching: boolean

A derived boolean from the fetchStatus variable, provided for convenience.

  • true whenever the queryFn is executing, which includes initial pending as well as background refetch.
isInitialLoading

isInitialLoading: boolean

Deprecated

isInitialLoading is being deprecated in favor of isLoading and will be removed in the next major version.

isPaused

isPaused: boolean

A derived boolean from the fetchStatus variable, provided for convenience.

  • The query wanted to fetch, but has been paused.
isRefetching

isRefetching: boolean

Is true whenever a background refetch is in-flight, which does not include initial pending.

  • Is the same as isFetching && !isPending.
isStale

isStale: boolean

Will be true if the data in the cache is invalidated or if the data is older than the given staleTime.

isEnabled

isEnabled: boolean

true if this observer is enabled, false otherwise.

refetch()

refetch: (options?) => Promise<QueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>

A function to manually refetch the query.

Parameters
options?

RefetchOptions

Returns

Promise<QueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>

fetchStatus

fetchStatus: FetchStatus

The fetch status of the query.

  • fetching: Is true whenever the queryFn is executing, which includes initial pending as well as background refetch.
  • paused: The query wanted to fetch, but has been paused.
  • idle: The query is not fetching.
  • See Network Mode  for more information.
promise

promise: Promise<InfiniteData<EventsListResponse, unknown>>

A stable promise that will be resolved with the data of the query. Requires the experimental_prefetchInRender feature flag to be enabled.

Example

Enabling the feature flag

const client = new QueryClient({
  defaultOptions: {
    queries: {
      experimental_prefetchInRender: true,
    },
  },
})

Usage

import { useQuery } from '@tanstack/react-query'
import React from 'react'
import { fetchTodos, type Todo } from './api'
 
function TodoList({ query }: { query: UseQueryResult<Todo[], Error> }) {
  const data = React.use(query.promise)
 
  return (
    <ul>
      {data.map(todo => (
        <li key={todo.id}>{todo.title}</li>
      ))}
    </ul>
  )
}
 
export function App() {
  const query = useQuery({ queryKey: ['todos'], queryFn: fetchTodos })
 
  return (
    <>
      <h1>Todos</h1>
      <React.Suspense fallback={<div>Loading...</div>}>
        <TodoList query={query} />
      </React.Suspense>
    </>
  )
}
fetchNextPage()

fetchNextPage: (options?) => Promise<InfiniteQueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>

This function allows you to fetch the next “page” of results.

Parameters
options?

FetchNextPageOptions

Returns

Promise<InfiniteQueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>

fetchPreviousPage()

fetchPreviousPage: (options?) => Promise<InfiniteQueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>

This function allows you to fetch the previous “page” of results.

Parameters
options?

FetchPreviousPageOptions

Returns

Promise<InfiniteQueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>

hasNextPage

hasNextPage: boolean

Will be true if there is a next page to be fetched (known via the getNextPageParam option).

hasPreviousPage

hasPreviousPage: boolean

Will be true if there is a previous page to be fetched (known via the getPreviousPageParam option).

isFetchingNextPage

isFetchingNextPage: boolean

Will be true while fetching the next page with fetchNextPage.

isFetchingPreviousPage

isFetchingPreviousPage: boolean

Will be true while fetching the previous page with fetchPreviousPage.

data

data: InfiniteData

The last successfully resolved data for the query.

error

error: null

The error object for the query, if an error was thrown.

  • Defaults to null.
isError

isError: false

A derived boolean from the status variable, provided for convenience.

  • true if the query attempt resulted in an error.
isPending

isPending: false

Will be pending if there’s no cached data and no query attempt was finished yet.

isLoading

isLoading: false

Is true whenever the first fetch for a query is in-flight.

  • Is the same as isFetching && isPending.
isLoadingError

isLoadingError: false

Will be true if the query failed while fetching for the first time.

isRefetchError

isRefetchError: false

Will be true if the query failed while refetching.

isFetchNextPageError

isFetchNextPageError: false

Will be true if the query failed while fetching the next page.

isFetchPreviousPageError

isFetchPreviousPageError: false

Will be true if the query failed while fetching the previous page.

isSuccess

isSuccess: true

A derived boolean from the status variable, provided for convenience.

  • true if the query has received a response with no errors and is ready to display its data.
isPlaceholderData

isPlaceholderData: false

Will be true if the data shown is the placeholder data.

status

status: "success"

The status of the query.

  • Will be:
    • pending if there’s no cached data and no query attempt was finished yet.
    • error if the query attempt resulted in an error.
    • success if the query has received a response with no errors and is ready to display its data.
events

events: object[]

total

total: number

loadedCount

loadedCount: number = events.length

{ dataUpdatedAt: number; errorUpdatedAt: number; failureCount: number; failureReason: Error \| null; errorUpdateCount: number; isFetched: boolean; isFetchedAfterMount: boolean; isFetching: boolean; isInitialLoading: boolean; isPaused: boolean; isRefetching: boolean; isStale: boolean; isEnabled: boolean; refetch: (options?) => Promise\<QueryObserverResult\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>, Error\>\>; fetchStatus: FetchStatus; promise: Promise\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>\>; fetchNextPage: (options?) => Promise\<InfiniteQueryObserverResult\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>, Error\>\>; fetchPreviousPage: (options?) => Promise\<InfiniteQueryObserverResult\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>, Error\>\>; hasNextPage: boolean; hasPreviousPage: boolean; isFetchingNextPage: boolean; isFetchingPreviousPage: boolean; data: undefined; error: Error; isError: true; isPending: false; isLoading: false; isLoadingError: true; isRefetchError: false; isFetchNextPageError: false; isFetchPreviousPageError: false; isSuccess: false; isPlaceholderData: false; status: "error"; events: object[]; total: number; loadedCount: number; }

dataUpdatedAt

dataUpdatedAt: number

The timestamp for when the query most recently returned the status as "success".

errorUpdatedAt

errorUpdatedAt: number

The timestamp for when the query most recently returned the status as "error".

failureCount

failureCount: number

The failure count for the query.

  • Incremented every time the query fails.
  • Reset to 0 when the query succeeds.
failureReason

failureReason: Error | null

The failure reason for the query retry.

  • Reset to null when the query succeeds.
errorUpdateCount

errorUpdateCount: number

The sum of all errors.

isFetched

isFetched: boolean

Will be true if the query has been fetched.

isFetchedAfterMount

isFetchedAfterMount: boolean

Will be true if the query has been fetched after the component mounted.

  • This property can be used to not show any previously cached data.
isFetching

isFetching: boolean

A derived boolean from the fetchStatus variable, provided for convenience.

  • true whenever the queryFn is executing, which includes initial pending as well as background refetch.
isInitialLoading

isInitialLoading: boolean

Deprecated

isInitialLoading is being deprecated in favor of isLoading and will be removed in the next major version.

isPaused

isPaused: boolean

A derived boolean from the fetchStatus variable, provided for convenience.

  • The query wanted to fetch, but has been paused.
isRefetching

isRefetching: boolean

Is true whenever a background refetch is in-flight, which does not include initial pending.

  • Is the same as isFetching && !isPending.
isStale

isStale: boolean

Will be true if the data in the cache is invalidated or if the data is older than the given staleTime.

isEnabled

isEnabled: boolean

true if this observer is enabled, false otherwise.

refetch()

refetch: (options?) => Promise<QueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>

A function to manually refetch the query.

Parameters
options?

RefetchOptions

Returns

Promise<QueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>

fetchStatus

fetchStatus: FetchStatus

The fetch status of the query.

  • fetching: Is true whenever the queryFn is executing, which includes initial pending as well as background refetch.
  • paused: The query wanted to fetch, but has been paused.
  • idle: The query is not fetching.
  • See Network Mode  for more information.
promise

promise: Promise<InfiniteData<EventsListResponse, unknown>>

A stable promise that will be resolved with the data of the query. Requires the experimental_prefetchInRender feature flag to be enabled.

Example

Enabling the feature flag

const client = new QueryClient({
  defaultOptions: {
    queries: {
      experimental_prefetchInRender: true,
    },
  },
})

Usage

import { useQuery } from '@tanstack/react-query'
import React from 'react'
import { fetchTodos, type Todo } from './api'
 
function TodoList({ query }: { query: UseQueryResult<Todo[], Error> }) {
  const data = React.use(query.promise)
 
  return (
    <ul>
      {data.map(todo => (
        <li key={todo.id}>{todo.title}</li>
      ))}
    </ul>
  )
}
 
export function App() {
  const query = useQuery({ queryKey: ['todos'], queryFn: fetchTodos })
 
  return (
    <>
      <h1>Todos</h1>
      <React.Suspense fallback={<div>Loading...</div>}>
        <TodoList query={query} />
      </React.Suspense>
    </>
  )
}
fetchNextPage()

fetchNextPage: (options?) => Promise<InfiniteQueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>

This function allows you to fetch the next “page” of results.

Parameters
options?

FetchNextPageOptions

Returns

Promise<InfiniteQueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>

fetchPreviousPage()

fetchPreviousPage: (options?) => Promise<InfiniteQueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>

This function allows you to fetch the previous “page” of results.

Parameters
options?

FetchPreviousPageOptions

Returns

Promise<InfiniteQueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>

hasNextPage

hasNextPage: boolean

Will be true if there is a next page to be fetched (known via the getNextPageParam option).

hasPreviousPage

hasPreviousPage: boolean

Will be true if there is a previous page to be fetched (known via the getPreviousPageParam option).

isFetchingNextPage

isFetchingNextPage: boolean

Will be true while fetching the next page with fetchNextPage.

isFetchingPreviousPage

isFetchingPreviousPage: boolean

Will be true while fetching the previous page with fetchPreviousPage.

data

data: undefined

The last successfully resolved data for the query.

error

error: Error

The error object for the query, if an error was thrown.

  • Defaults to null.
isError

isError: true

A derived boolean from the status variable, provided for convenience.

  • true if the query attempt resulted in an error.
isPending

isPending: false

Will be pending if there’s no cached data and no query attempt was finished yet.

isLoading

isLoading: false

Is true whenever the first fetch for a query is in-flight.

  • Is the same as isFetching && isPending.
isLoadingError

isLoadingError: true

Will be true if the query failed while fetching for the first time.

isRefetchError

isRefetchError: false

Will be true if the query failed while refetching.

isFetchNextPageError

isFetchNextPageError: false

Will be true if the query failed while fetching the next page.

isFetchPreviousPageError

isFetchPreviousPageError: false

Will be true if the query failed while fetching the previous page.

isSuccess

isSuccess: false

A derived boolean from the status variable, provided for convenience.

  • true if the query has received a response with no errors and is ready to display its data.
isPlaceholderData

isPlaceholderData: false

Will be true if the data shown is the placeholder data.

status

status: "error"

The status of the query.

  • Will be:
    • pending if there’s no cached data and no query attempt was finished yet.
    • error if the query attempt resulted in an error.
    • success if the query has received a response with no errors and is ready to display its data.
events

events: object[]

total

total: number

loadedCount

loadedCount: number = events.length

{ dataUpdatedAt: number; errorUpdatedAt: number; failureCount: number; failureReason: Error \| null; errorUpdateCount: number; isFetched: boolean; isFetchedAfterMount: boolean; isFetching: boolean; isInitialLoading: boolean; isPaused: boolean; isRefetching: boolean; isStale: boolean; isEnabled: boolean; refetch: (options?) => Promise\<QueryObserverResult\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>, Error\>\>; fetchStatus: FetchStatus; promise: Promise\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>\>; fetchNextPage: (options?) => Promise\<InfiniteQueryObserverResult\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>, Error\>\>; fetchPreviousPage: (options?) => Promise\<InfiniteQueryObserverResult\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>, Error\>\>; hasNextPage: boolean; hasPreviousPage: boolean; isFetchingNextPage: boolean; isFetchingPreviousPage: boolean; data: undefined; error: null; isError: false; isPending: true; isLoading: true; isLoadingError: false; isRefetchError: false; isFetchNextPageError: false; isFetchPreviousPageError: false; isSuccess: false; isPlaceholderData: false; status: "pending"; events: object[]; total: number; loadedCount: number; }

dataUpdatedAt

dataUpdatedAt: number

The timestamp for when the query most recently returned the status as "success".

errorUpdatedAt

errorUpdatedAt: number

The timestamp for when the query most recently returned the status as "error".

failureCount

failureCount: number

The failure count for the query.

  • Incremented every time the query fails.
  • Reset to 0 when the query succeeds.
failureReason

failureReason: Error | null

The failure reason for the query retry.

  • Reset to null when the query succeeds.
errorUpdateCount

errorUpdateCount: number

The sum of all errors.

isFetched

isFetched: boolean

Will be true if the query has been fetched.

isFetchedAfterMount

isFetchedAfterMount: boolean

Will be true if the query has been fetched after the component mounted.

  • This property can be used to not show any previously cached data.
isFetching

isFetching: boolean

A derived boolean from the fetchStatus variable, provided for convenience.

  • true whenever the queryFn is executing, which includes initial pending as well as background refetch.
isInitialLoading

isInitialLoading: boolean

Deprecated

isInitialLoading is being deprecated in favor of isLoading and will be removed in the next major version.

isPaused

isPaused: boolean

A derived boolean from the fetchStatus variable, provided for convenience.

  • The query wanted to fetch, but has been paused.
isRefetching

isRefetching: boolean

Is true whenever a background refetch is in-flight, which does not include initial pending.

  • Is the same as isFetching && !isPending.
isStale

isStale: boolean

Will be true if the data in the cache is invalidated or if the data is older than the given staleTime.

isEnabled

isEnabled: boolean

true if this observer is enabled, false otherwise.

refetch()

refetch: (options?) => Promise<QueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>

A function to manually refetch the query.

Parameters
options?

RefetchOptions

Returns

Promise<QueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>

fetchStatus

fetchStatus: FetchStatus

The fetch status of the query.

  • fetching: Is true whenever the queryFn is executing, which includes initial pending as well as background refetch.
  • paused: The query wanted to fetch, but has been paused.
  • idle: The query is not fetching.
  • See Network Mode  for more information.
promise

promise: Promise<InfiniteData<EventsListResponse, unknown>>

A stable promise that will be resolved with the data of the query. Requires the experimental_prefetchInRender feature flag to be enabled.

Example

Enabling the feature flag

const client = new QueryClient({
  defaultOptions: {
    queries: {
      experimental_prefetchInRender: true,
    },
  },
})

Usage

import { useQuery } from '@tanstack/react-query'
import React from 'react'
import { fetchTodos, type Todo } from './api'
 
function TodoList({ query }: { query: UseQueryResult<Todo[], Error> }) {
  const data = React.use(query.promise)
 
  return (
    <ul>
      {data.map(todo => (
        <li key={todo.id}>{todo.title}</li>
      ))}
    </ul>
  )
}
 
export function App() {
  const query = useQuery({ queryKey: ['todos'], queryFn: fetchTodos })
 
  return (
    <>
      <h1>Todos</h1>
      <React.Suspense fallback={<div>Loading...</div>}>
        <TodoList query={query} />
      </React.Suspense>
    </>
  )
}
fetchNextPage()

fetchNextPage: (options?) => Promise<InfiniteQueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>

This function allows you to fetch the next “page” of results.

Parameters
options?

FetchNextPageOptions

Returns

Promise<InfiniteQueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>

fetchPreviousPage()

fetchPreviousPage: (options?) => Promise<InfiniteQueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>

This function allows you to fetch the previous “page” of results.

Parameters
options?

FetchPreviousPageOptions

Returns

Promise<InfiniteQueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>

hasNextPage

hasNextPage: boolean

Will be true if there is a next page to be fetched (known via the getNextPageParam option).

hasPreviousPage

hasPreviousPage: boolean

Will be true if there is a previous page to be fetched (known via the getPreviousPageParam option).

isFetchingNextPage

isFetchingNextPage: boolean

Will be true while fetching the next page with fetchNextPage.

isFetchingPreviousPage

isFetchingPreviousPage: boolean

Will be true while fetching the previous page with fetchPreviousPage.

data

data: undefined

The last successfully resolved data for the query.

error

error: null

The error object for the query, if an error was thrown.

  • Defaults to null.
isError

isError: false

A derived boolean from the status variable, provided for convenience.

  • true if the query attempt resulted in an error.
isPending

isPending: true

Will be pending if there’s no cached data and no query attempt was finished yet.

isLoading

isLoading: true

Is true whenever the first fetch for a query is in-flight.

  • Is the same as isFetching && isPending.
isLoadingError

isLoadingError: false

Will be true if the query failed while fetching for the first time.

isRefetchError

isRefetchError: false

Will be true if the query failed while refetching.

isFetchNextPageError

isFetchNextPageError: false

Will be true if the query failed while fetching the next page.

isFetchPreviousPageError

isFetchPreviousPageError: false

Will be true if the query failed while fetching the previous page.

isSuccess

isSuccess: false

A derived boolean from the status variable, provided for convenience.

  • true if the query has received a response with no errors and is ready to display its data.
isPlaceholderData

isPlaceholderData: false

Will be true if the data shown is the placeholder data.

status

status: "pending"

The status of the query.

  • Will be:
    • pending if there’s no cached data and no query attempt was finished yet.
    • error if the query attempt resulted in an error.
    • success if the query has received a response with no errors and is ready to display its data.
events

events: object[]

total

total: number

loadedCount

loadedCount: number = events.length

{ dataUpdatedAt: number; errorUpdatedAt: number; failureCount: number; failureReason: Error \| null; errorUpdateCount: number; isFetched: boolean; isFetchedAfterMount: boolean; isFetching: boolean; isLoading: boolean; isInitialLoading: boolean; isPaused: boolean; isRefetching: boolean; isStale: boolean; isEnabled: boolean; refetch: (options?) => Promise\<QueryObserverResult\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>, Error\>\>; fetchStatus: FetchStatus; promise: Promise\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>\>; fetchNextPage: (options?) => Promise\<InfiniteQueryObserverResult\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>, Error\>\>; fetchPreviousPage: (options?) => Promise\<InfiniteQueryObserverResult\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>, Error\>\>; hasNextPage: boolean; hasPreviousPage: boolean; isFetchingNextPage: boolean; isFetchingPreviousPage: boolean; data: undefined; error: null; isError: false; isPending: true; isLoadingError: false; isRefetchError: false; isFetchNextPageError: false; isFetchPreviousPageError: false; isSuccess: false; isPlaceholderData: false; status: "pending"; events: object[]; total: number; loadedCount: number; }

dataUpdatedAt

dataUpdatedAt: number

The timestamp for when the query most recently returned the status as "success".

errorUpdatedAt

errorUpdatedAt: number

The timestamp for when the query most recently returned the status as "error".

failureCount

failureCount: number

The failure count for the query.

  • Incremented every time the query fails.
  • Reset to 0 when the query succeeds.
failureReason

failureReason: Error | null

The failure reason for the query retry.

  • Reset to null when the query succeeds.
errorUpdateCount

errorUpdateCount: number

The sum of all errors.

isFetched

isFetched: boolean

Will be true if the query has been fetched.

isFetchedAfterMount

isFetchedAfterMount: boolean

Will be true if the query has been fetched after the component mounted.

  • This property can be used to not show any previously cached data.
isFetching

isFetching: boolean

A derived boolean from the fetchStatus variable, provided for convenience.

  • true whenever the queryFn is executing, which includes initial pending as well as background refetch.
isLoading

isLoading: boolean

Is true whenever the first fetch for a query is in-flight.

  • Is the same as isFetching && isPending.
isInitialLoading

isInitialLoading: boolean

Deprecated

isInitialLoading is being deprecated in favor of isLoading and will be removed in the next major version.

isPaused

isPaused: boolean

A derived boolean from the fetchStatus variable, provided for convenience.

  • The query wanted to fetch, but has been paused.
isRefetching

isRefetching: boolean

Is true whenever a background refetch is in-flight, which does not include initial pending.

  • Is the same as isFetching && !isPending.
isStale

isStale: boolean

Will be true if the data in the cache is invalidated or if the data is older than the given staleTime.

isEnabled

isEnabled: boolean

true if this observer is enabled, false otherwise.

refetch()

refetch: (options?) => Promise<QueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>

A function to manually refetch the query.

Parameters
options?

RefetchOptions

Returns

Promise<QueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>

fetchStatus

fetchStatus: FetchStatus

The fetch status of the query.

  • fetching: Is true whenever the queryFn is executing, which includes initial pending as well as background refetch.
  • paused: The query wanted to fetch, but has been paused.
  • idle: The query is not fetching.
  • See Network Mode  for more information.
promise

promise: Promise<InfiniteData<EventsListResponse, unknown>>

A stable promise that will be resolved with the data of the query. Requires the experimental_prefetchInRender feature flag to be enabled.

Example

Enabling the feature flag

const client = new QueryClient({
  defaultOptions: {
    queries: {
      experimental_prefetchInRender: true,
    },
  },
})

Usage

import { useQuery } from '@tanstack/react-query'
import React from 'react'
import { fetchTodos, type Todo } from './api'
 
function TodoList({ query }: { query: UseQueryResult<Todo[], Error> }) {
  const data = React.use(query.promise)
 
  return (
    <ul>
      {data.map(todo => (
        <li key={todo.id}>{todo.title}</li>
      ))}
    </ul>
  )
}
 
export function App() {
  const query = useQuery({ queryKey: ['todos'], queryFn: fetchTodos })
 
  return (
    <>
      <h1>Todos</h1>
      <React.Suspense fallback={<div>Loading...</div>}>
        <TodoList query={query} />
      </React.Suspense>
    </>
  )
}
fetchNextPage()

fetchNextPage: (options?) => Promise<InfiniteQueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>

This function allows you to fetch the next “page” of results.

Parameters
options?

FetchNextPageOptions

Returns

Promise<InfiniteQueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>

fetchPreviousPage()

fetchPreviousPage: (options?) => Promise<InfiniteQueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>

This function allows you to fetch the previous “page” of results.

Parameters
options?

FetchPreviousPageOptions

Returns

Promise<InfiniteQueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>

hasNextPage

hasNextPage: boolean

Will be true if there is a next page to be fetched (known via the getNextPageParam option).

hasPreviousPage

hasPreviousPage: boolean

Will be true if there is a previous page to be fetched (known via the getPreviousPageParam option).

isFetchingNextPage

isFetchingNextPage: boolean

Will be true while fetching the next page with fetchNextPage.

isFetchingPreviousPage

isFetchingPreviousPage: boolean

Will be true while fetching the previous page with fetchPreviousPage.

data

data: undefined

The last successfully resolved data for the query.

error

error: null

The error object for the query, if an error was thrown.

  • Defaults to null.
isError

isError: false

A derived boolean from the status variable, provided for convenience.

  • true if the query attempt resulted in an error.
isPending

isPending: true

Will be pending if there’s no cached data and no query attempt was finished yet.

isLoadingError

isLoadingError: false

Will be true if the query failed while fetching for the first time.

isRefetchError

isRefetchError: false

Will be true if the query failed while refetching.

isFetchNextPageError

isFetchNextPageError: false

Will be true if the query failed while fetching the next page.

isFetchPreviousPageError

isFetchPreviousPageError: false

Will be true if the query failed while fetching the previous page.

isSuccess

isSuccess: false

A derived boolean from the status variable, provided for convenience.

  • true if the query has received a response with no errors and is ready to display its data.
isPlaceholderData

isPlaceholderData: false

Will be true if the data shown is the placeholder data.

status

status: "pending"

The status of the query.

  • Will be:
    • pending if there’s no cached data and no query attempt was finished yet.
    • error if the query attempt resulted in an error.
    • success if the query has received a response with no errors and is ready to display its data.
events

events: object[]

total

total: number

loadedCount

loadedCount: number = events.length

{ dataUpdatedAt: number; errorUpdatedAt: number; failureCount: number; failureReason: Error \| null; errorUpdateCount: number; isFetched: boolean; isFetchedAfterMount: boolean; isFetching: boolean; isInitialLoading: boolean; isPaused: boolean; isRefetching: boolean; isStale: boolean; isEnabled: boolean; refetch: (options?) => Promise\<QueryObserverResult\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>, Error\>\>; fetchStatus: FetchStatus; promise: Promise\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>\>; fetchNextPage: (options?) => Promise\<InfiniteQueryObserverResult\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>, Error\>\>; fetchPreviousPage: (options?) => Promise\<InfiniteQueryObserverResult\<InfiniteData\<[EventsListResponse](#eventslistresponse), unknown\>, Error\>\>; hasNextPage: boolean; hasPreviousPage: boolean; isFetchingNextPage: boolean; isFetchingPreviousPage: boolean; data: InfiniteData; isError: false; error: null; isPending: false; isLoading: false; isLoadingError: false; isRefetchError: false; isSuccess: true; isPlaceholderData: true; isFetchNextPageError: false; isFetchPreviousPageError: false; status: "success"; events: object[]; total: number; loadedCount: number; }

dataUpdatedAt

dataUpdatedAt: number

The timestamp for when the query most recently returned the status as "success".

errorUpdatedAt

errorUpdatedAt: number

The timestamp for when the query most recently returned the status as "error".

failureCount

failureCount: number

The failure count for the query.

  • Incremented every time the query fails.
  • Reset to 0 when the query succeeds.
failureReason

failureReason: Error | null

The failure reason for the query retry.

  • Reset to null when the query succeeds.
errorUpdateCount

errorUpdateCount: number

The sum of all errors.

isFetched

isFetched: boolean

Will be true if the query has been fetched.

isFetchedAfterMount

isFetchedAfterMount: boolean

Will be true if the query has been fetched after the component mounted.

  • This property can be used to not show any previously cached data.
isFetching

isFetching: boolean

A derived boolean from the fetchStatus variable, provided for convenience.

  • true whenever the queryFn is executing, which includes initial pending as well as background refetch.
isInitialLoading

isInitialLoading: boolean

Deprecated

isInitialLoading is being deprecated in favor of isLoading and will be removed in the next major version.

isPaused

isPaused: boolean

A derived boolean from the fetchStatus variable, provided for convenience.

  • The query wanted to fetch, but has been paused.
isRefetching

isRefetching: boolean

Is true whenever a background refetch is in-flight, which does not include initial pending.

  • Is the same as isFetching && !isPending.
isStale

isStale: boolean

Will be true if the data in the cache is invalidated or if the data is older than the given staleTime.

isEnabled

isEnabled: boolean

true if this observer is enabled, false otherwise.

refetch()

refetch: (options?) => Promise<QueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>

A function to manually refetch the query.

Parameters
options?

RefetchOptions

Returns

Promise<QueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>

fetchStatus

fetchStatus: FetchStatus

The fetch status of the query.

  • fetching: Is true whenever the queryFn is executing, which includes initial pending as well as background refetch.
  • paused: The query wanted to fetch, but has been paused.
  • idle: The query is not fetching.
  • See Network Mode  for more information.
promise

promise: Promise<InfiniteData<EventsListResponse, unknown>>

A stable promise that will be resolved with the data of the query. Requires the experimental_prefetchInRender feature flag to be enabled.

Example

Enabling the feature flag

const client = new QueryClient({
  defaultOptions: {
    queries: {
      experimental_prefetchInRender: true,
    },
  },
})

Usage

import { useQuery } from '@tanstack/react-query'
import React from 'react'
import { fetchTodos, type Todo } from './api'
 
function TodoList({ query }: { query: UseQueryResult<Todo[], Error> }) {
  const data = React.use(query.promise)
 
  return (
    <ul>
      {data.map(todo => (
        <li key={todo.id}>{todo.title}</li>
      ))}
    </ul>
  )
}
 
export function App() {
  const query = useQuery({ queryKey: ['todos'], queryFn: fetchTodos })
 
  return (
    <>
      <h1>Todos</h1>
      <React.Suspense fallback={<div>Loading...</div>}>
        <TodoList query={query} />
      </React.Suspense>
    </>
  )
}
fetchNextPage()

fetchNextPage: (options?) => Promise<InfiniteQueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>

This function allows you to fetch the next “page” of results.

Parameters
options?

FetchNextPageOptions

Returns

Promise<InfiniteQueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>

fetchPreviousPage()

fetchPreviousPage: (options?) => Promise<InfiniteQueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>

This function allows you to fetch the previous “page” of results.

Parameters
options?

FetchPreviousPageOptions

Returns

Promise<InfiniteQueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>

hasNextPage

hasNextPage: boolean

Will be true if there is a next page to be fetched (known via the getNextPageParam option).

hasPreviousPage

hasPreviousPage: boolean

Will be true if there is a previous page to be fetched (known via the getPreviousPageParam option).

isFetchingNextPage

isFetchingNextPage: boolean

Will be true while fetching the next page with fetchNextPage.

isFetchingPreviousPage

isFetchingPreviousPage: boolean

Will be true while fetching the previous page with fetchPreviousPage.

data

data: InfiniteData

The last successfully resolved data for the query.

isError

isError: false

A derived boolean from the status variable, provided for convenience.

  • true if the query attempt resulted in an error.
error

error: null

The error object for the query, if an error was thrown.

  • Defaults to null.
isPending

isPending: false

Will be pending if there’s no cached data and no query attempt was finished yet.

isLoading

isLoading: false

Is true whenever the first fetch for a query is in-flight.

  • Is the same as isFetching && isPending.
isLoadingError

isLoadingError: false

Will be true if the query failed while fetching for the first time.

isRefetchError

isRefetchError: false

Will be true if the query failed while refetching.

isSuccess

isSuccess: true

A derived boolean from the status variable, provided for convenience.

  • true if the query has received a response with no errors and is ready to display its data.
isPlaceholderData

isPlaceholderData: true

Will be true if the data shown is the placeholder data.

isFetchNextPageError

isFetchNextPageError: false

Will be true if the query failed while fetching the next page.

isFetchPreviousPageError

isFetchPreviousPageError: false

Will be true if the query failed while fetching the previous page.

status

status: "success"

The status of the query.

  • Will be:
    • pending if there’s no cached data and no query attempt was finished yet.
    • error if the query attempt resulted in an error.
    • success if the query has received a response with no errors and is ready to display its data.
events

events: object[]

total

total: number

loadedCount

loadedCount: number = events.length

useEventDetailQuery()

useEventDetailQuery(eventId): UseQueryResult<Event, Error>

Hook to fetch a single event by ID.

Used by the event detail modal to fetch full event data when clicking on an event card.

Parameters

eventId

The event database ID to fetch

number | null

Returns

UseQueryResult<Event, Error>

React Query result with event data

Last updated on
Use DebounceUse Feature Flags