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.
• Polling for the progress of data import jobs.
• Handling file uploads for new imports.

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

Interfaces

EventsListResponse

Properties

events

events: Event[]

total

total: number

page

page: number

limit

limit: number

hasNextPage

hasNextPage: boolean

hasPrevPage

hasPrevPage: boolean

MapClustersResponse

Properties

features

features: ClusterFeature[]

HistogramData

Properties

date

date: string

dateEnd

dateEnd: string

count

count: number

HistogramResponse

Properties

histogram

histogram: HistogramData[]

metadata

metadata: object

total

total: number

dateRange

dateRange: object

dateRange.min

min: null | string

dateRange.max

max: null | string

bucketSizeSeconds

bucketSizeSeconds: null | number

bucketCount

bucketCount: number

counts

counts: object

counts.datasets

datasets: number

counts.catalogs

catalogs: number

topDatasets

topDatasets: unknown[]

topCatalogs

topCatalogs: unknown[]

AggregationItem

Properties

id

id: string | number

name

name: string

count

count: number

AggregationResponse

Properties

items

items: AggregationItem[]

total

total: number

groupedBy

groupedBy: string

ImportJobProgress

Properties

id

id: string

datasetId

datasetId: string

datasetName?

optional datasetName: string

stage

stage: string

progress

progress: number

rowsTotal

rowsTotal: number

rowsProcessed

rowsProcessed: number

batchNumber

batchNumber: number

errors

errors: number

duplicates

duplicates: object

internal

internal: number

external

external: number

schemaValidation?

optional schemaValidation: Record<string, unknown>

results?

optional results: Record<string, unknown>

ImportProgressResponse

Properties

type

type: "import-file"

id

id: string

status

status: string

originalName

originalName: string

datasetsCount

datasetsCount: number

datasetsProcessed

datasetsProcessed: number

overallProgress

overallProgress: number

jobs

jobs: ImportJobProgress[]

errorLog?

optional errorLog: string

completedAt?

optional completedAt: string

createdAt?

optional createdAt: string

ClusterStatsResponse

Properties

p20

p20: number

p40

p40: number

p60

p60: number

p80

p80: number

p100

p100: number

SimpleBounds

Properties

north

north: number

south

south: number

east

east: number

west

west: number

Variables

eventsQueryKeys

const eventsQueryKeys: object

Type declaration

all

all: readonly ["events"]

lists()

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

Returns

readonly ["events", "list"]

list()

list: (filters, bounds, limit) => readonly ["events", "list", { filters: FilterState; bounds: BoundsType; limit: number; }]

Parameters

filters

FilterState

bounds

BoundsType

limit

number

Returns

readonly ["events", "list", { filters: FilterState; bounds: BoundsType; limit: number; }]

infinite()

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

Returns

readonly ["events", "infinite"]

infiniteList()

infiniteList: (filters, bounds, limit) => readonly ["events", "infinite", { filters: FilterState; bounds: BoundsType; limit: number; }]

Parameters

filters

FilterState

bounds

BoundsType

limit

number

Returns

readonly ["events", "infinite", { filters: FilterState; bounds: BoundsType; limit: number; }]

clusters()

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

Returns

readonly ["events", "clusters"]

cluster()

cluster: (filters, bounds, zoom) => readonly ["events", "clusters", { filters: FilterState; bounds: BoundsType; zoom: number; }]

Parameters

filters

FilterState

bounds

BoundsType

zoom

number

Returns

readonly ["events", "clusters", { filters: FilterState; bounds: BoundsType; zoom: number; }]

clusterStats()

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

Returns

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

clusterStat()

clusterStat: (filters) => readonly ["events", "cluster-stats", { filters: FilterState; }]

Parameters

filters

FilterState

Returns

readonly ["events", "cluster-stats", { filters: FilterState; }]

histograms()

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

Returns

readonly ["events", "histogram"]

histogram()

histogram: (filters, bounds) => readonly ["events", "histogram", { filters: FilterState; bounds: BoundsType; }]

Parameters

filters

FilterState

bounds

BoundsType

Returns

readonly ["events", "histogram", { filters: FilterState; bounds: BoundsType; }]

aggregations()

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

Returns

readonly ["events", "aggregation"]

aggregation()

aggregation: (filters, bounds, groupBy) => readonly ["events", "aggregation", { filters: FilterState; bounds: BoundsType; groupBy: "catalog" | "dataset"; }]

Parameters

filters

FilterState

bounds

BoundsType

groupBy

"catalog" | "dataset"

Returns

readonly ["events", "aggregation", { filters: FilterState; bounds: BoundsType; groupBy: "catalog" | "dataset"; }]

imports()

imports: () => readonly ["imports"]

Returns

readonly ["imports"]

importProgress()

importProgress: (importId) => readonly ["imports", "progress", string]

Parameters

importId

string

Returns

readonly ["imports", "progress", string]

Functions

useEventsListQuery()

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

Parameters

filters

FilterState

bounds

BoundsType

limit

number = 1000

enabled

boolean = true

Returns

UseQueryResult<EventsListResponse, Error>

useEventsTotalQuery()

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

Parameters

filters

FilterState

enabled

boolean = true

Returns

UseQueryResult<EventsListResponse, Error>

useMapClustersQuery()

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

Parameters

filters

FilterState

bounds

BoundsType

zoom

number

enabled

boolean = true

Returns

UseQueryResult<MapClustersResponse, Error>

useHistogramQuery()

useHistogramQuery(filters, bounds, enabled): UseQueryResult<HistogramResponse, Error>

Parameters

filters

FilterState

bounds

BoundsType

enabled

boolean = true

Returns

UseQueryResult<HistogramResponse, Error>

useClusterStatsQuery()

useClusterStatsQuery(filters, enabled): UseQueryResult<ClusterStatsResponse, Error>

Parameters

filters

FilterState

enabled

boolean = true

Returns

UseQueryResult<ClusterStatsResponse, Error>

useImportProgressQuery()

useImportProgressQuery(importId): UseQueryResult<ImportProgressResponse, Error>

Parameters

importId

null | string

Returns

UseQueryResult<ImportProgressResponse, Error>

useImportUploadMutation()

useImportUploadMutation(): UseMutationResult<{ importId: string; success: boolean; }, Error, { formData: FormData; signal?: AbortSignal; }, unknown>

Returns

UseMutationResult<{ importId: string; success: boolean; }, Error, { formData: FormData; signal?: AbortSignal; }, unknown>

useInvalidateEventsQueries()

useInvalidateEventsQueries(): object

Returns

object

invalidateAll()

invalidateAll: () => void

Returns

void

invalidateLists()

invalidateLists: () => void

Returns

void

invalidateClusters()

invalidateClusters: () => void

Returns

void

invalidateHistograms()

invalidateHistograms: () => void

Returns

void

useEventsAggregationQuery()

useEventsAggregationQuery(filters, bounds, groupBy, enabled): UseQueryResult<AggregationResponse, Error>

Parameters

filters

FilterState

bounds

BoundsType

groupBy

"catalog" | "dataset"

enabled

boolean = true

Returns

UseQueryResult<AggregationResponse, Error>

useEventsInfiniteQuery()

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

Parameters

filters

FilterState

bounds

BoundsType

limit

number = 20

enabled

boolean = true

Returns

UseInfiniteQueryResult<InfiniteData<EventsListResponse, unknown>, Error>

useEventsInfiniteFlattened()

useEventsInfiniteFlattened(filters, bounds, limit, enabled): { dataUpdatedAt: number; errorUpdatedAt: number; failureCount: number; failureReason: null | Error; errorUpdateCount: number; isFetched: boolean; isFetchedAfterMount: boolean; isFetching: boolean; isInitialLoading: boolean; isPaused: boolean; isRefetching: boolean; isStale: boolean; isEnabled: boolean; refetch: (options?) => Promise<QueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>; fetchStatus: FetchStatus; promise: Promise<InfiniteData<EventsListResponse, unknown>>; fetchNextPage: (options?) => Promise<InfiniteQueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>; fetchPreviousPage: (options?) => Promise<InfiniteQueryObserverResult<InfiniteData<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: Event[]; total: number; loadedCount: number; } | { dataUpdatedAt: number; errorUpdatedAt: number; failureCount: number; failureReason: null | Error; errorUpdateCount: number; isFetched: boolean; isFetchedAfterMount: boolean; isFetching: boolean; isInitialLoading: boolean; isPaused: boolean; isRefetching: boolean; isStale: boolean; isEnabled: boolean; refetch: (options?) => Promise<QueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>; fetchStatus: FetchStatus; promise: Promise<InfiniteData<EventsListResponse, unknown>>; fetchNextPage: (options?) => Promise<InfiniteQueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>; fetchPreviousPage: (options?) => Promise<InfiniteQueryObserverResult<InfiniteData<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: Event[]; total: number; loadedCount: number; } | { dataUpdatedAt: number; errorUpdatedAt: number; failureCount: number; failureReason: null | Error; errorUpdateCount: number; isFetched: boolean; isFetchedAfterMount: boolean; isFetching: boolean; isInitialLoading: boolean; isPaused: boolean; isRefetching: boolean; isStale: boolean; isEnabled: boolean; refetch: (options?) => Promise<QueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>; fetchStatus: FetchStatus; promise: Promise<InfiniteData<EventsListResponse, unknown>>; fetchNextPage: (options?) => Promise<InfiniteQueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>; fetchPreviousPage: (options?) => Promise<InfiniteQueryObserverResult<InfiniteData<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: Event[]; total: number; loadedCount: number; } | { dataUpdatedAt: number; errorUpdatedAt: number; failureCount: number; failureReason: null | Error; errorUpdateCount: number; isFetched: boolean; isFetchedAfterMount: boolean; isFetching: boolean; isInitialLoading: boolean; isPaused: boolean; isRefetching: boolean; isStale: boolean; isEnabled: boolean; refetch: (options?) => Promise<QueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>; fetchStatus: FetchStatus; promise: Promise<InfiniteData<EventsListResponse, unknown>>; fetchNextPage: (options?) => Promise<InfiniteQueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>; fetchPreviousPage: (options?) => Promise<InfiniteQueryObserverResult<InfiniteData<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: Event[]; total: number; loadedCount: number; } | { dataUpdatedAt: number; errorUpdatedAt: number; failureCount: number; failureReason: null | Error; 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, unknown>, Error>>; fetchStatus: FetchStatus; promise: Promise<InfiniteData<EventsListResponse, unknown>>; fetchNextPage: (options?) => Promise<InfiniteQueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>; fetchPreviousPage: (options?) => Promise<InfiniteQueryObserverResult<InfiniteData<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: Event[]; total: number; loadedCount: number; } | { dataUpdatedAt: number; errorUpdatedAt: number; failureCount: number; failureReason: null | Error; errorUpdateCount: number; isFetched: boolean; isFetchedAfterMount: boolean; isFetching: boolean; isInitialLoading: boolean; isPaused: boolean; isRefetching: boolean; isStale: boolean; isEnabled: boolean; refetch: (options?) => Promise<QueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>; fetchStatus: FetchStatus; promise: Promise<InfiniteData<EventsListResponse, unknown>>; fetchNextPage: (options?) => Promise<InfiniteQueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>; fetchPreviousPage: (options?) => Promise<InfiniteQueryObserverResult<InfiniteData<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: Event[]; total: number; loadedCount: number; }

Parameters

filters

FilterState

bounds

BoundsType

limit

number = 20

enabled

boolean = true

Returns

{ dataUpdatedAt: number; errorUpdatedAt: number; failureCount: number; failureReason: null | Error; errorUpdateCount: number; isFetched: boolean; isFetchedAfterMount: boolean; isFetching: boolean; isInitialLoading: boolean; isPaused: boolean; isRefetching: boolean; isStale: boolean; isEnabled: boolean; refetch: (options?) => Promise<QueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>; fetchStatus: FetchStatus; promise: Promise<InfiniteData<EventsListResponse, unknown>>; fetchNextPage: (options?) => Promise<InfiniteQueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>; fetchPreviousPage: (options?) => Promise<InfiniteQueryObserverResult<InfiniteData<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: Event[]; 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: null | Error

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: Event[]

total

total: number

loadedCount

loadedCount: number = events.length

{ dataUpdatedAt: number; errorUpdatedAt: number; failureCount: number; failureReason: null | Error; errorUpdateCount: number; isFetched: boolean; isFetchedAfterMount: boolean; isFetching: boolean; isInitialLoading: boolean; isPaused: boolean; isRefetching: boolean; isStale: boolean; isEnabled: boolean; refetch: (options?) => Promise<QueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>; fetchStatus: FetchStatus; promise: Promise<InfiniteData<EventsListResponse, unknown>>; fetchNextPage: (options?) => Promise<InfiniteQueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>; fetchPreviousPage: (options?) => Promise<InfiniteQueryObserverResult<InfiniteData<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: Event[]; 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: null | Error

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: Event[]

total

total: number

loadedCount

loadedCount: number = events.length

{ dataUpdatedAt: number; errorUpdatedAt: number; failureCount: number; failureReason: null | Error; errorUpdateCount: number; isFetched: boolean; isFetchedAfterMount: boolean; isFetching: boolean; isInitialLoading: boolean; isPaused: boolean; isRefetching: boolean; isStale: boolean; isEnabled: boolean; refetch: (options?) => Promise<QueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>; fetchStatus: FetchStatus; promise: Promise<InfiniteData<EventsListResponse, unknown>>; fetchNextPage: (options?) => Promise<InfiniteQueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>; fetchPreviousPage: (options?) => Promise<InfiniteQueryObserverResult<InfiniteData<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: Event[]; 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: null | Error

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: Event[]

total

total: number

loadedCount

loadedCount: number = events.length

{ dataUpdatedAt: number; errorUpdatedAt: number; failureCount: number; failureReason: null | Error; errorUpdateCount: number; isFetched: boolean; isFetchedAfterMount: boolean; isFetching: boolean; isInitialLoading: boolean; isPaused: boolean; isRefetching: boolean; isStale: boolean; isEnabled: boolean; refetch: (options?) => Promise<QueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>; fetchStatus: FetchStatus; promise: Promise<InfiniteData<EventsListResponse, unknown>>; fetchNextPage: (options?) => Promise<InfiniteQueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>; fetchPreviousPage: (options?) => Promise<InfiniteQueryObserverResult<InfiniteData<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: Event[]; 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: null | Error

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: Event[]

total

total: number

loadedCount

loadedCount: number = events.length

{ dataUpdatedAt: number; errorUpdatedAt: number; failureCount: number; failureReason: null | Error; 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, unknown>, Error>>; fetchStatus: FetchStatus; promise: Promise<InfiniteData<EventsListResponse, unknown>>; fetchNextPage: (options?) => Promise<InfiniteQueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>; fetchPreviousPage: (options?) => Promise<InfiniteQueryObserverResult<InfiniteData<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: Event[]; 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: null | Error

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: Event[]

total

total: number

loadedCount

loadedCount: number = events.length

{ dataUpdatedAt: number; errorUpdatedAt: number; failureCount: number; failureReason: null | Error; errorUpdateCount: number; isFetched: boolean; isFetchedAfterMount: boolean; isFetching: boolean; isInitialLoading: boolean; isPaused: boolean; isRefetching: boolean; isStale: boolean; isEnabled: boolean; refetch: (options?) => Promise<QueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>; fetchStatus: FetchStatus; promise: Promise<InfiniteData<EventsListResponse, unknown>>; fetchNextPage: (options?) => Promise<InfiniteQueryObserverResult<InfiniteData<EventsListResponse, unknown>, Error>>; fetchPreviousPage: (options?) => Promise<InfiniteQueryObserverResult<InfiniteData<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: Event[]; 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: null | Error

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: Event[]

total

total: number

loadedCount

loadedCount: number = events.length