API
React
usePaginatedQuery

usePaginatedQuery

A query hook designed for paginated data, with helper functions and useful callbacks that helps you properly updates the cache and perform next fetch in response to the last fetch result.

function usePaginatedQuery(
  fn: QueryFunction,
  options?: Options
): PaginatedQueryState;

QueryFunction

function queryFunction(query: GeneratedSchema["query"], args?: TArgs): TData;

query

A cache proxy of the query type from the generated schema.

args

The value provided in initialArgs for the first time, and then subsequently the last args supplied in fetchMore().

Options

fetchPolicy

ValueDescription
cache-firstTranslates to the cache policy force-cache.
cache-and-networkTranslates to the cache policy default.
network-onlyTranslates to the cache policy no-cache.

Read more about Cache Policy.

initialArgs

Optional initial arguments to be supplied to the second parameter in the selection function.

merge

Optional callback to customize the merging behavior when a new page of data is fetched.

type MergeFn = (args: {
  data: {
    existing: TData;
    incoming: TData;
  };
  sortBy: <T>(arr: T[], fn: (item: T) => any) => T[];
  uniqBy: <T>(arr: T[], fn: (item: T) => any) => T[];
}) => TData | undefined;

operationName

Optional GraphQL operation name, useful for debugging and testing.

retry

Failing queries can be automatically retried, this option allows you to customize the retrying behavior, or disabling it altogether.

Retry PolicyDescription
trueEnables auto retry with the default options.
falseDisables auto retry.
numberEnables auto retry with the default options and a custom maxRetries count.
{ maxRetries, retryDelay }Enables auto retry with custom options.

When you specify retry as an object, the following properties are available.

maxRetries

The maximum number of times to retry a failed query, defaults to 3.

retryDelay

Retry DelayDescription
numberA fixed number of milliseconds to wait between retries.
(attempt: number) => numberA function that returns the number of milliseconds to wait between retries, the default is an exponential backoff function: min(2x,30)1000msmin({2^x}, 30) * 1000\text{ms}.

skip

Skips the initial call to the query function, defaults to false.

suspense

Use true to enable Suspense mode.

Return Value

data

Data returned from the query function, will be updated on every successful call to fetchMore.

args

The latest arguments used in fetchMore, defaults to initialArgs.

isLoading

Whether the query function is currently fetching.

fetchMore

function fetchMore(
  args:
    | TArgs
    | ((existing: { existingData: TData; existingArgs: TArgs }) => TArgs),
  fetchPolicy?: LegacyFetchPolicy
): TArgs;

args

Arguments to be supplied to the second parameter in the selection function, or a function that returns said arguments.

fetchPolicy

Optional value, overriding the fetchPolicy option.