queryOptions

Call Signature

function queryOptions<TQueryFnData, TError, TData, TQueryKey>(options): Omit<UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>, "queryFn"> & object & QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>;

Defined in: preact-query/src/queryOptions.ts:140

You can generally pass everything to queryOptions that you can also pass to useQuery. These options can be shared across hooks and imperative APIs such as queryClient.query. options.queryKey is required and is the query key to generate options for.

This overload is selected when initialData is set, so the resulting data is never undefined.

Type Parameters

TQueryFnData

TQueryFnData = unknown

TError

TError = Error

TData

TData = TQueryFnData

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

Parameters

options

DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>

The DefinedInitialDataOptions to use — everything you can pass to useQuery, with initialData set.

Returns

The same options object, typed so that queryKey carries the inferred data type.

See

useQuery to run a query with these options.

Example

tsx

import { queryOptions, useQuery } from '@tanstack/preact-query'

export const postsOptions = queryOptions({
  queryKey: ['posts'],
  queryFn: fetchPosts,
  initialData: [],
})

function Posts() {
  // `data` is `Post[]`, never `undefined`, thanks to `initialData` — even if a refetch fails,
  // so the list stays visible alongside the error.
  const { data, isError, error } = useQuery(postsOptions)

  return (
    <div>
      {isError ? <span>Error: {error.message}</span> : null}
      <ul>
        {data.map((post) => <li key={post.id}>{post.title}</li>)}
      </ul>
    </div>
  )
}

Call Signature

function queryOptions<TQueryFnData, TError, TData, TQueryKey>(options): OmitKeyof<UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>, "queryFn"> & object & QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>;

Defined in: preact-query/src/queryOptions.ts:213

Type Parameters

TQueryFnData

TQueryFnData = unknown

TError

TError = Error

TData

TData = TQueryFnData

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

Parameters

options

UnusedSkipTokenOptions<TQueryFnData, TError, TData, TQueryKey>

The UnusedSkipTokenOptions to use — everything you can pass to useQuery.

Returns

The same options object, typed so that queryKey carries the inferred data type.

See

useQuery to run a query with these options.

Examples

A parameterized factory, reused across a hook and an imperative call with the same cache entry:

tsx

import { noop, queryOptions, useQuery } from '@tanstack/preact-query'

export const postOptions = (id: string) =>
  queryOptions({
    queryKey: ['post', id],
    queryFn: () => fetchPost(id),
  })

function Post({ id }: { id: string }) {
  const { data, isPending, isError, error } = useQuery(postOptions(id))

  if (isPending) return 'Loading...'
  if (isError) return <span>Error: {error.message}</span>

  return <h1>{data.title}</h1>
}

// `postOptions` also works with imperative APIs like `queryClient.query` —
// see `useQuery` for an example that warms the cache this way before rendering `<Post>`.
const postId = '1'
queryClient.query(postOptions(postId)).catch(noop)

The same options object works with every API that accepts query options:

tsx

import { noop, queryOptions, useQuery } from '@tanstack/preact-query'

const todosOptions = queryOptions({
  queryKey: ['todos'],
  queryFn: fetchTodos,
})

function Todos() {
  const { data, isPending, isError, error } = useQuery(todosOptions)

  if (isPending) return 'Loading...'
  if (isError) return <span>Error: {error.message}</span>

  return (
    <ul>
      {data.map((todo) => <li key={todo.id}>{todo.title}</li>)}
    </ul>
  )
}

// The same options object works with the imperative APIs too:
queryClient.query(todosOptions).catch(noop)
queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefined

Call Signature

function queryOptions<TQueryFnData, TError, TData, TQueryKey>(options): UseQueryOptions<TQueryFnData, TError, TData, TQueryKey> & object & QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>;

Defined in: preact-query/src/queryOptions.ts:309

Type Parameters

TQueryFnData

TQueryFnData = unknown

TError

TError = Error

TData

TData = TQueryFnData

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

Parameters

options

UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>

The UndefinedInitialDataOptions to use — everything you can pass to useQuery.

Returns

The same options object, typed so that queryKey carries the inferred data type.

See

useQuery to run a query with these options.

Remarks

This is the only overload that accepts queryFn: skipToken, shown below.

Examples

A parameterized factory, reused across a hook and an imperative call with the same cache entry:

tsx

import { noop, queryOptions, useQuery } from '@tanstack/preact-query'

export const postOptions = (id: string) =>
  queryOptions({
    queryKey: ['post', id],
    queryFn: () => fetchPost(id),
  })

function Post({ id }: { id: string }) {
  const { data, isPending, isError, error } = useQuery(postOptions(id))

  if (isPending) return 'Loading...'
  if (isError) return <span>Error: {error.message}</span>

  return <h1>{data.title}</h1>
}

// `postOptions` also works with imperative APIs like `queryClient.query` —
// see `useQuery` for an example that warms the cache this way before rendering `<Post>`.
const postId = '1'
queryClient.query(postOptions(postId)).catch(noop)

The same options object works with every API that accepts query options:

tsx

import { noop, queryOptions, useQuery } from '@tanstack/preact-query'

const todosOptions = queryOptions({
  queryKey: ['todos'],
  queryFn: fetchTodos,
})

function Todos() {
  const { data, isPending, isError, error } = useQuery(todosOptions)

  if (isPending) return 'Loading...'
  if (isError) return <span>Error: {error.message}</span>

  return (
    <ul>
      {data.map((todo) => <li key={todo.id}>{todo.title}</li>)}
    </ul>
  )
}

// The same options object works with the imperative APIs too:
queryClient.query(todosOptions).catch(noop)
queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefined

A factory that disables the query, type safe, until postId is set:

tsx

import { queryOptions, skipToken, useQuery } from '@tanstack/preact-query'

export const postOptions = (postId: number | undefined) =>
  queryOptions({
    queryKey: ['post', postId],
    queryFn: postId != null ? () => fetchPost(postId) : skipToken,
  })

function Post({ postId }: { postId: number | undefined }) {
  const { data, isLoading, isError, error } = useQuery(postOptions(postId))

  if (postId == null) return 'Select a post'
  if (isLoading) return 'Loading...'
  if (isError) return <span>Error: {error.message}</span>

  return <h1>{data?.title}</h1>
}