From b2f7d88f107cbfb58d6c2d90b55c7459295c7db0 Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Wed, 26 Aug 2026 16:44:21 +0900
Subject: [PATCH 01/30] docs(preact-query): wrap 'useIsFetching' example in a
 component

---
 .../preact/reference/functions/useIsFetching.md      | 12 +++++++-----
 packages/preact-query/src/useIsFetching.ts           | 10 ++++++----
 2 files changed, 13 insertions(+), 9 deletions(-)

diff --git a/docs/framework/preact/reference/functions/useIsFetching.md b/docs/framework/preact/reference/functions/useIsFetching.md
index 75aea1a394..915c55fab0 100644
--- a/docs/framework/preact/reference/functions/useIsFetching.md
+++ b/docs/framework/preact/reference/functions/useIsFetching.md
@@ -7,7 +7,7 @@ title: useIsFetching
 function useIsFetching(filters?, queryClient?): number;
 ```
 
-Defined in: [preact-query/src/useIsFetching.ts:42](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useIsFetching.ts#L42)
+Defined in: [preact-query/src/useIsFetching.ts:44](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useIsFetching.ts#L44)
 
 `useIsFetching` is an optional hook that returns the `number` of the queries that your application is loading or
 fetching in the background (useful for app-wide loading indicators).
@@ -39,10 +39,12 @@ background.
 ```tsx
 import { useIsFetching } from '@tanstack/preact-query'
 
-// How many queries are fetching?
-const isFetching = useIsFetching()
-// How many queries matching the posts prefix are fetching?
-const isFetchingPosts = useIsFetching({ queryKey: ['posts'] })
+function PostsFetchingIndicator() {
+  // How many queries matching the posts prefix are fetching?
+  const isFetchingPosts = useIsFetching({ queryKey: ['posts'] })
+
+  return isFetchingPosts ? <span>Refreshing posts...</span> : null
+}
 ```
 
 A global loading indicator for any query fetching in the background, not just the ones on screen:
diff --git a/packages/preact-query/src/useIsFetching.ts b/packages/preact-query/src/useIsFetching.ts
index 9deac24f6c..16c00bbf95 100644
--- a/packages/preact-query/src/useIsFetching.ts
+++ b/packages/preact-query/src/useIsFetching.ts
@@ -19,10 +19,12 @@ import { useSyncExternalStore } from './utils'
  * ```tsx
  * import { useIsFetching } from '@tanstack/preact-query'
  *
- * // How many queries are fetching?
- * const isFetching = useIsFetching()
- * // How many queries matching the posts prefix are fetching?
- * const isFetchingPosts = useIsFetching({ queryKey: ['posts'] })
+ * function PostsFetchingIndicator() {
+ *   // How many queries matching the posts prefix are fetching?
+ *   const isFetchingPosts = useIsFetching({ queryKey: ['posts'] })
+ *
+ *   return isFetchingPosts ? <span>Refreshing posts...</span> : null
+ * }
  * ```
  *
  * @example

From ce37641dce8a5191f0a0ca80ff4b9c83cdb6720c Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Wed, 26 Aug 2026 16:44:21 +0900
Subject: [PATCH 02/30] docs(preact-query): wrap 'useQueries' examples in
 components and add 'isError' handling

---
 .../preact/reference/functions/useQueries.md  | 70 +++++++++++++------
 packages/preact-query/src/useQueries.ts       | 68 ++++++++++++------
 2 files changed, 95 insertions(+), 43 deletions(-)

diff --git a/docs/framework/preact/reference/functions/useQueries.md b/docs/framework/preact/reference/functions/useQueries.md
index 154077759f..668211e1d3 100644
--- a/docs/framework/preact/reference/functions/useQueries.md
+++ b/docs/framework/preact/reference/functions/useQueries.md
@@ -7,7 +7,7 @@ title: useQueries
 function useQueries<T, TCombinedResult>(__namedParameters, queryClient?): TCombinedResult;
 ```
 
-Defined in: [preact-query/src/useQueries.ts:275](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQueries.ts#L275)
+Defined in: [preact-query/src/useQueries.ts:301](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQueries.ts#L301)
 
 The `useQueries` hook can be used to fetch a variable number of queries.
 
@@ -83,29 +83,55 @@ order as the input. When `combine` is provided, this is the value returned by `c
 ```tsx
 import { useQueries } from '@tanstack/preact-query'
 
-const ids = [1, 2, 3]
-const results = useQueries({
-  queries: ids.map((id) => ({
-    queryKey: ['post', id],
-    queryFn: () => fetchPost(id),
-    staleTime: Infinity,
-  })),
-})
+function Posts({ ids }: { ids: Array<number> }) {
+  const postQueries = useQueries({
+    queries: ids.map((id) => ({
+      queryKey: ['post', id],
+      queryFn: () => fetchPost(id),
+      staleTime: Infinity,
+    })),
+  })
+
+  return (
+    <ul>
+      {postQueries.map((query, index) => {
+        if (query.isPending) return <li key={ids[index]}>Loading...</li>
+        if (query.isError) return <li key={ids[index]}>Error: {query.error.message}</li>
+        return <li key={ids[index]}>{query.data.title}</li>
+      })}
+    </ul>
+  )
+}
 ```
 
 Combining results into a single value:
 ```tsx
-const ids = [1, 2, 3]
-const combinedQueries = useQueries({
-  queries: ids.map((id) => ({
-    queryKey: ['post', id],
-    queryFn: () => fetchPost(id),
-  })),
-  combine: (results) => {
-    return {
-      data: results.map((result) => result.data),
-      pending: results.some((result) => result.isPending),
-    }
-  },
-})
+import { useQueries } from '@tanstack/preact-query'
+
+function Posts({ ids }: { ids: Array<number> }) {
+  const { data, isPending, isError } = useQueries({
+    queries: ids.map((id) => ({
+      queryKey: ['post', id],
+      queryFn: () => fetchPost(id),
+    })),
+    combine: (postQueries) => {
+      return {
+        data: postQueries.map((query) => query.data),
+        isPending: postQueries.some((query) => query.isPending),
+        isError: postQueries.some((query) => query.isError),
+      }
+    },
+  })
+
+  if (isPending) return 'Loading...'
+  if (isError) return 'Error loading posts'
+
+  return (
+    <ul>
+      {data.map((post) => (
+        <li key={post?.id}>{post?.title}</li>
+      ))}
+    </ul>
+  )
+}
 ```
diff --git a/packages/preact-query/src/useQueries.ts b/packages/preact-query/src/useQueries.ts
index 39a3d04316..52d4b45090 100644
--- a/packages/preact-query/src/useQueries.ts
+++ b/packages/preact-query/src/useQueries.ts
@@ -244,32 +244,58 @@ export type QueriesResults<
  * ```tsx
  * import { useQueries } from '@tanstack/preact-query'
  *
- * const ids = [1, 2, 3]
- * const results = useQueries({
- *   queries: ids.map((id) => ({
- *     queryKey: ['post', id],
- *     queryFn: () => fetchPost(id),
- *     staleTime: Infinity,
- *   })),
- * })
+ * function Posts({ ids }: { ids: Array<number> }) {
+ *   const postQueries = useQueries({
+ *     queries: ids.map((id) => ({
+ *       queryKey: ['post', id],
+ *       queryFn: () => fetchPost(id),
+ *       staleTime: Infinity,
+ *     })),
+ *   })
+ *
+ *   return (
+ *     <ul>
+ *       {postQueries.map((query, index) => {
+ *         if (query.isPending) return <li key={ids[index]}>Loading...</li>
+ *         if (query.isError) return <li key={ids[index]}>Error: {query.error.message}</li>
+ *         return <li key={ids[index]}>{query.data.title}</li>
+ *       })}
+ *     </ul>
+ *   )
+ * }
  * ```
  *
  * @example
  * Combining results into a single value:
  * ```tsx
- * const ids = [1, 2, 3]
- * const combinedQueries = useQueries({
- *   queries: ids.map((id) => ({
- *     queryKey: ['post', id],
- *     queryFn: () => fetchPost(id),
- *   })),
- *   combine: (results) => {
- *     return {
- *       data: results.map((result) => result.data),
- *       pending: results.some((result) => result.isPending),
- *     }
- *   },
- * })
+ * import { useQueries } from '@tanstack/preact-query'
+ *
+ * function Posts({ ids }: { ids: Array<number> }) {
+ *   const { data, isPending, isError } = useQueries({
+ *     queries: ids.map((id) => ({
+ *       queryKey: ['post', id],
+ *       queryFn: () => fetchPost(id),
+ *     })),
+ *     combine: (postQueries) => {
+ *       return {
+ *         data: postQueries.map((query) => query.data),
+ *         isPending: postQueries.some((query) => query.isPending),
+ *         isError: postQueries.some((query) => query.isError),
+ *       }
+ *     },
+ *   })
+ *
+ *   if (isPending) return 'Loading...'
+ *   if (isError) return 'Error loading posts'
+ *
+ *   return (
+ *     <ul>
+ *       {data.map((post) => (
+ *         <li key={post?.id}>{post?.title}</li>
+ *       ))}
+ *     </ul>
+ *   )
+ * }
  * ```
  */
 export function useQueries<

From 52e8c76842c1a1bab3f777f4665aeb435c27154e Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Wed, 26 Aug 2026 16:44:21 +0900
Subject: [PATCH 03/30] docs(preact-query): wrap 'useIsMutating' and
 'useMutationState' examples in components

---
 .../reference/functions/useIsMutating.md      | 12 ++--
 .../reference/functions/useMutationState.md   | 60 ++++++++++------
 packages/preact-query/src/useMutationState.ts | 68 ++++++++++++-------
 3 files changed, 90 insertions(+), 50 deletions(-)

diff --git a/docs/framework/preact/reference/functions/useIsMutating.md b/docs/framework/preact/reference/functions/useIsMutating.md
index 941496a00b..8b4954ffba 100644
--- a/docs/framework/preact/reference/functions/useIsMutating.md
+++ b/docs/framework/preact/reference/functions/useIsMutating.md
@@ -7,7 +7,7 @@ title: useIsMutating
 function useIsMutating(filters?, queryClient?): number;
 ```
 
-Defined in: [preact-query/src/useMutationState.ts:33](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useMutationState.ts#L33)
+Defined in: [preact-query/src/useMutationState.ts:35](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useMutationState.ts#L35)
 
 `useIsMutating` is an optional hook that returns the `number` of mutations that your application is fetching
 (useful for app-wide loading indicators).
@@ -38,8 +38,10 @@ Will be the `number` of the mutations that your application is currently fetchin
 ```tsx
 import { useIsMutating } from '@tanstack/preact-query'
 
-// How many mutations are fetching?
-const isMutating = useIsMutating()
-// How many mutations matching the posts prefix are fetching?
-const isMutatingPosts = useIsMutating({ mutationKey: ['posts'] })
+function PostsMutatingIndicator() {
+  // How many mutations matching the posts prefix are fetching?
+  const isMutatingPosts = useIsMutating({ mutationKey: ['posts'] })
+
+  return isMutatingPosts ? <span>Saving posts...</span> : null
+}
 ```
diff --git a/docs/framework/preact/reference/functions/useMutationState.md b/docs/framework/preact/reference/functions/useMutationState.md
index 6288bff6ef..89a6e82959 100644
--- a/docs/framework/preact/reference/functions/useMutationState.md
+++ b/docs/framework/preact/reference/functions/useMutationState.md
@@ -7,7 +7,7 @@ title: useMutationState
 function useMutationState<TResult, TMutation>(options, queryClient?): TResult[];
 ```
 
-Defined in: [preact-query/src/useMutationState.ts:137](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useMutationState.ts#L137)
+Defined in: [preact-query/src/useMutationState.ts:157](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useMutationState.ts#L157)
 
 `useMutationState` is a hook that gives you access to all mutations in the `MutationCache`. You can pass
 `filters` (MutationFilters) to narrow down your mutations, and `select` to transform the mutation
@@ -51,10 +51,14 @@ Get all variables of all running mutations:
 ```tsx
 import { useMutationState } from '@tanstack/preact-query'
 
-const variables = useMutationState({
-  filters: { status: 'pending' },
-  select: (mutation) => mutation.state.variables,
-})
+function PendingPosts() {
+  const variables = useMutationState({
+    filters: { status: 'pending' },
+    select: (mutation) => mutation.state.variables,
+  })
+
+  return <>{variables.length} posts saving...</>
+}
 ```
 
 Get all data for specific mutations via the `mutationKey`:
@@ -63,27 +67,41 @@ import { useMutation, useMutationState } from '@tanstack/preact-query'
 
 const mutationKey = ['posts']
 
-// Some mutation that we want to get the state for
-const mutation = useMutation({
-  mutationKey,
-  mutationFn: createPosts,
-})
-
-const data = useMutationState({
-  // this mutation key needs to match the mutation key of the given mutation (see above)
-  filters: { mutationKey },
-  select: (mutation) => mutation.state.data,
-})
+function Posts() {
+  // Some mutation that we want to get the state for
+  const mutation = useMutation({
+    mutationKey,
+    mutationFn: createPosts,
+  })
+
+  const data = useMutationState({
+    // this mutation key needs to match the mutation key of the given mutation (see above)
+    filters: { mutationKey },
+    select: (mutation) => mutation.state.data,
+  })
+
+  return (
+    <button onClick={() => mutation.mutate(['New Post'])}>
+      Create post ({data.length} saved so far)
+    </button>
+  )
+}
 ```
 
 Access the latest mutation data via the `mutationKey`. Each invocation of `mutate` adds a new entry to the
 mutation cache for `gcTime` milliseconds — check the last item that `useMutationState` returns to get the
 latest invocation:
 ```tsx
-const data = useMutationState({
-  filters: { mutationKey: ['posts'] },
-  select: (mutation) => mutation.state.data,
-})
+import { useMutationState } from '@tanstack/preact-query'
+
+function LatestPost() {
+  const data = useMutationState({
+    filters: { mutationKey: ['posts'] },
+    select: (mutation) => mutation.state.data,
+  })
+
+  const latest = data[data.length - 1]
 
-const latest = data[data.length - 1]
+  return <>{latest ? 'Saved' : 'Nothing saved yet'}</>
+}
 ```
diff --git a/packages/preact-query/src/useMutationState.ts b/packages/preact-query/src/useMutationState.ts
index beb5318217..a3f483651a 100644
--- a/packages/preact-query/src/useMutationState.ts
+++ b/packages/preact-query/src/useMutationState.ts
@@ -24,10 +24,12 @@ import { useSyncExternalStore } from './utils'
  * ```tsx
  * import { useIsMutating } from '@tanstack/preact-query'
  *
- * // How many mutations are fetching?
- * const isMutating = useIsMutating()
- * // How many mutations matching the posts prefix are fetching?
- * const isMutatingPosts = useIsMutating({ mutationKey: ['posts'] })
+ * function PostsMutatingIndicator() {
+ *   // How many mutations matching the posts prefix are fetching?
+ *   const isMutatingPosts = useIsMutating({ mutationKey: ['posts'] })
+ *
+ *   return isMutatingPosts ? <span>Saving posts...</span> : null
+ * }
  * ```
  */
 export function useIsMutating(
@@ -95,10 +97,14 @@ function getResult<
  * ```tsx
  * import { useMutationState } from '@tanstack/preact-query'
  *
- * const variables = useMutationState({
- *   filters: { status: 'pending' },
- *   select: (mutation) => mutation.state.variables,
- * })
+ * function PendingPosts() {
+ *   const variables = useMutationState({
+ *     filters: { status: 'pending' },
+ *     select: (mutation) => mutation.state.variables,
+ *   })
+ *
+ *   return <>{variables.length} posts saving...</>
+ * }
  * ```
  *
  * @example
@@ -108,17 +114,25 @@ function getResult<
  *
  * const mutationKey = ['posts']
  *
- * // Some mutation that we want to get the state for
- * const mutation = useMutation({
- *   mutationKey,
- *   mutationFn: createPosts,
- * })
- *
- * const data = useMutationState({
- *   // this mutation key needs to match the mutation key of the given mutation (see above)
- *   filters: { mutationKey },
- *   select: (mutation) => mutation.state.data,
- * })
+ * function Posts() {
+ *   // Some mutation that we want to get the state for
+ *   const mutation = useMutation({
+ *     mutationKey,
+ *     mutationFn: createPosts,
+ *   })
+ *
+ *   const data = useMutationState({
+ *     // this mutation key needs to match the mutation key of the given mutation (see above)
+ *     filters: { mutationKey },
+ *     select: (mutation) => mutation.state.data,
+ *   })
+ *
+ *   return (
+ *     <button onClick={() => mutation.mutate(['New Post'])}>
+ *       Create post ({data.length} saved so far)
+ *     </button>
+ *   )
+ * }
  * ```
  *
  * @example
@@ -126,12 +140,18 @@ function getResult<
  * mutation cache for `gcTime` milliseconds — check the last item that `useMutationState` returns to get the
  * latest invocation:
  * ```tsx
- * const data = useMutationState({
- *   filters: { mutationKey: ['posts'] },
- *   select: (mutation) => mutation.state.data,
- * })
+ * import { useMutationState } from '@tanstack/preact-query'
+ *
+ * function LatestPost() {
+ *   const data = useMutationState({
+ *     filters: { mutationKey: ['posts'] },
+ *     select: (mutation) => mutation.state.data,
+ *   })
+ *
+ *   const latest = data[data.length - 1]
  *
- * const latest = data[data.length - 1]
+ *   return <>{latest ? 'Saved' : 'Nothing saved yet'}</>
+ * }
  * ```
  */
 export function useMutationState<

From 0685b2e215bf4ab712fa46cb3c7156b536c37a87 Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Wed, 26 Aug 2026 16:44:21 +0900
Subject: [PATCH 04/30] docs(preact-query): wrap 'queryOptions' examples in
 components

---
 .../reference/functions/queryOptions.md       | 48 +++++++++++--------
 packages/preact-query/src/queryOptions.ts     | 44 ++++++++++-------
 2 files changed, 54 insertions(+), 38 deletions(-)

diff --git a/docs/framework/preact/reference/functions/queryOptions.md b/docs/framework/preact/reference/functions/queryOptions.md
index 88e114030c..67ffd67b7e 100644
--- a/docs/framework/preact/reference/functions/queryOptions.md
+++ b/docs/framework/preact/reference/functions/queryOptions.md
@@ -75,7 +75,7 @@ function Posts() {
 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:201](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L201)
+Defined in: [preact-query/src/queryOptions.ts:205](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L205)
 
 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
@@ -118,12 +118,17 @@ The same options object, typed so that `queryKey` carries the inferred data type
 ### Examples
 
 ```tsx
-import { queryOptions } from '@tanstack/preact-query'
+import { queryOptions, useQuery } from '@tanstack/preact-query'
 
 export const postsOptions = queryOptions({
   queryKey: ['posts'],
   queryFn: fetchPosts,
 })
+
+function Posts() {
+  const { data } = useQuery(postsOptions)
+  return <>{data?.map((post) => <p key={post.id}>{post.title}</p>)}</>
+}
 ```
 
 A parameterized factory, reused across a hook and an imperative call with the same cache entry:
@@ -147,20 +152,19 @@ queryClient.query(postOptions(id)).catch(noop)
 
 The same options object works with every API that accepts query options:
 ```tsx
-import {
-  noop,
-  queryOptions,
-  useQuery,
-  useSuspenseQuery,
-} from '@tanstack/preact-query'
+import { noop, queryOptions, useQuery } from '@tanstack/preact-query'
 
 const todosOptions = queryOptions({
   queryKey: ['todos'],
   queryFn: fetchTodos,
 })
 
-useQuery(todosOptions)
-useSuspenseQuery(todosOptions)
+function Todos() {
+  const { data } = useQuery(todosOptions)
+  return <>{data?.map((todo) => <p key={todo.id}>{todo.title}</p>)}</>
+}
+
+// Elsewhere, e.g. to warm the cache before rendering `<Todos>`:
 queryClient.query(todosOptions).catch(noop)
 queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefined
 ```
@@ -171,7 +175,7 @@ queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefi
 function queryOptions<TQueryFnData, TError, TData, TQueryKey>(options): UseQueryOptions<TQueryFnData, TError, TData, TQueryKey> & object & QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>;
 ```
 
-Defined in: [preact-query/src/queryOptions.ts:271](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L271)
+Defined in: [preact-query/src/queryOptions.ts:279](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L279)
 
 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
@@ -214,12 +218,17 @@ The same options object, typed so that `queryKey` carries the inferred data type
 ### Examples
 
 ```tsx
-import { queryOptions } from '@tanstack/preact-query'
+import { queryOptions, useQuery } from '@tanstack/preact-query'
 
 export const postsOptions = queryOptions({
   queryKey: ['posts'],
   queryFn: fetchPosts,
 })
+
+function Posts() {
+  const { data } = useQuery(postsOptions)
+  return <>{data?.map((post) => <p key={post.id}>{post.title}</p>)}</>
+}
 ```
 
 A parameterized factory, reused across a hook and an imperative call with the same cache entry:
@@ -243,20 +252,19 @@ queryClient.query(postOptions(id)).catch(noop)
 
 The same options object works with every API that accepts query options:
 ```tsx
-import {
-  noop,
-  queryOptions,
-  useQuery,
-  useSuspenseQuery,
-} from '@tanstack/preact-query'
+import { noop, queryOptions, useQuery } from '@tanstack/preact-query'
 
 const todosOptions = queryOptions({
   queryKey: ['todos'],
   queryFn: fetchTodos,
 })
 
-useQuery(todosOptions)
-useSuspenseQuery(todosOptions)
+function Todos() {
+  const { data } = useQuery(todosOptions)
+  return <>{data?.map((todo) => <p key={todo.id}>{todo.title}</p>)}</>
+}
+
+// Elsewhere, e.g. to warm the cache before rendering `<Todos>`:
 queryClient.query(todosOptions).catch(noop)
 queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefined
 ```
diff --git a/packages/preact-query/src/queryOptions.ts b/packages/preact-query/src/queryOptions.ts
index 440306fce4..db8350dd53 100644
--- a/packages/preact-query/src/queryOptions.ts
+++ b/packages/preact-query/src/queryOptions.ts
@@ -149,12 +149,17 @@ export function queryOptions<
  *
  * @example
  * ```tsx
- * import { queryOptions } from '@tanstack/preact-query'
+ * import { queryOptions, useQuery } from '@tanstack/preact-query'
  *
  * export const postsOptions = queryOptions({
  *   queryKey: ['posts'],
  *   queryFn: fetchPosts,
  * })
+ *
+ * function Posts() {
+ *   const { data } = useQuery(postsOptions)
+ *   return <>{data?.map((post) => <p key={post.id}>{post.title}</p>)}</>
+ * }
  * ```
  *
  * @example
@@ -180,20 +185,19 @@ export function queryOptions<
  * @example
  * The same options object works with every API that accepts query options:
  * ```tsx
- * import {
- *   noop,
- *   queryOptions,
- *   useQuery,
- *   useSuspenseQuery,
- * } from '@tanstack/preact-query'
+ * import { noop, queryOptions, useQuery } from '@tanstack/preact-query'
  *
  * const todosOptions = queryOptions({
  *   queryKey: ['todos'],
  *   queryFn: fetchTodos,
  * })
  *
- * useQuery(todosOptions)
- * useSuspenseQuery(todosOptions)
+ * function Todos() {
+ *   const { data } = useQuery(todosOptions)
+ *   return <>{data?.map((todo) => <p key={todo.id}>{todo.title}</p>)}</>
+ * }
+ *
+ * // Elsewhere, e.g. to warm the cache before rendering `<Todos>`:
  * queryClient.query(todosOptions).catch(noop)
  * queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefined
  * ```
@@ -219,12 +223,17 @@ export function queryOptions<
  *
  * @example
  * ```tsx
- * import { queryOptions } from '@tanstack/preact-query'
+ * import { queryOptions, useQuery } from '@tanstack/preact-query'
  *
  * export const postsOptions = queryOptions({
  *   queryKey: ['posts'],
  *   queryFn: fetchPosts,
  * })
+ *
+ * function Posts() {
+ *   const { data } = useQuery(postsOptions)
+ *   return <>{data?.map((post) => <p key={post.id}>{post.title}</p>)}</>
+ * }
  * ```
  *
  * @example
@@ -250,20 +259,19 @@ export function queryOptions<
  * @example
  * The same options object works with every API that accepts query options:
  * ```tsx
- * import {
- *   noop,
- *   queryOptions,
- *   useQuery,
- *   useSuspenseQuery,
- * } from '@tanstack/preact-query'
+ * import { noop, queryOptions, useQuery } from '@tanstack/preact-query'
  *
  * const todosOptions = queryOptions({
  *   queryKey: ['todos'],
  *   queryFn: fetchTodos,
  * })
  *
- * useQuery(todosOptions)
- * useSuspenseQuery(todosOptions)
+ * function Todos() {
+ *   const { data } = useQuery(todosOptions)
+ *   return <>{data?.map((todo) => <p key={todo.id}>{todo.title}</p>)}</>
+ * }
+ *
+ * // Elsewhere, e.g. to warm the cache before rendering `<Todos>`:
  * queryClient.query(todosOptions).catch(noop)
  * queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefined
  * ```

From 28ca24c4a6b77937fe97ab4b97fcb4f643fdd47c Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Wed, 26 Aug 2026 16:44:21 +0900
Subject: [PATCH 05/30] docs(preact-query): wrap 'infiniteQueryOptions' example
 in a component

---
 .../functions/infiniteQueryOptions.md          | 18 ++++++++++++++----
 .../preact-query/src/infiniteQueryOptions.ts   | 14 ++++++++++++--
 2 files changed, 26 insertions(+), 6 deletions(-)

diff --git a/docs/framework/preact/reference/functions/infiniteQueryOptions.md b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
index d28fe91935..d0bc2d79d0 100644
--- a/docs/framework/preact/reference/functions/infiniteQueryOptions.md
+++ b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
@@ -80,7 +80,7 @@ function Projects() {
 function infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options): OmitKeyof<UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, "queryFn"> & object & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData, unknown>, TError>;
 ```
 
-Defined in: [preact-query/src/infiniteQueryOptions.ts:233](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L233)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:238](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L238)
 
 You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
 These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
@@ -123,7 +123,7 @@ The same options object, typed so that `queryKey` carries the inferred data type
 ### Examples
 
 ```tsx
-import { infiniteQueryOptions } from '@tanstack/preact-query'
+import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
 
 export const projectsOptions = infiniteQueryOptions({
   queryKey: ['projects'],
@@ -131,6 +131,11 @@ export const projectsOptions = infiniteQueryOptions({
   initialPageParam: 0,
   getNextPageParam: (lastPage) => lastPage.nextId,
 })
+
+function Projects() {
+  const { data } = useInfiniteQuery(projectsOptions)
+  return <>{data?.pages.map((page) => page.projects.map((p) => <p key={p.id}>{p.name}</p>))}</>
+}
 ```
 
 A parameterized factory, reused across a hook and an imperative call with the same cache entry:
@@ -173,7 +178,7 @@ queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
 function infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options): UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & object & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData, unknown>, TError>;
 ```
 
-Defined in: [preact-query/src/infiniteQueryOptions.ts:309](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L309)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:319](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L319)
 
 You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
 These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
@@ -216,7 +221,7 @@ The same options object, typed so that `queryKey` carries the inferred data type
 ### Examples
 
 ```tsx
-import { infiniteQueryOptions } from '@tanstack/preact-query'
+import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
 
 export const projectsOptions = infiniteQueryOptions({
   queryKey: ['projects'],
@@ -224,6 +229,11 @@ export const projectsOptions = infiniteQueryOptions({
   initialPageParam: 0,
   getNextPageParam: (lastPage) => lastPage.nextId,
 })
+
+function Projects() {
+  const { data } = useInfiniteQuery(projectsOptions)
+  return <>{data?.pages.map((page) => page.projects.map((p) => <p key={p.id}>{p.name}</p>))}</>
+}
 ```
 
 A parameterized factory, reused across a hook and an imperative call with the same cache entry:
diff --git a/packages/preact-query/src/infiniteQueryOptions.ts b/packages/preact-query/src/infiniteQueryOptions.ts
index bece80eeb6..918fd58c23 100644
--- a/packages/preact-query/src/infiniteQueryOptions.ts
+++ b/packages/preact-query/src/infiniteQueryOptions.ts
@@ -186,7 +186,7 @@ export function infiniteQueryOptions<
  *
  * @example
  * ```tsx
- * import { infiniteQueryOptions } from '@tanstack/preact-query'
+ * import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
  *
  * export const projectsOptions = infiniteQueryOptions({
  *   queryKey: ['projects'],
@@ -194,6 +194,11 @@ export function infiniteQueryOptions<
  *   initialPageParam: 0,
  *   getNextPageParam: (lastPage) => lastPage.nextId,
  * })
+ *
+ * function Projects() {
+ *   const { data } = useInfiniteQuery(projectsOptions)
+ *   return <>{data?.pages.map((page) => page.projects.map((p) => <p key={p.id}>{p.name}</p>))}</>
+ * }
  * ```
  *
  * @example
@@ -262,7 +267,7 @@ export function infiniteQueryOptions<
  *
  * @example
  * ```tsx
- * import { infiniteQueryOptions } from '@tanstack/preact-query'
+ * import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
  *
  * export const projectsOptions = infiniteQueryOptions({
  *   queryKey: ['projects'],
@@ -270,6 +275,11 @@ export function infiniteQueryOptions<
  *   initialPageParam: 0,
  *   getNextPageParam: (lastPage) => lastPage.nextId,
  * })
+ *
+ * function Projects() {
+ *   const { data } = useInfiniteQuery(projectsOptions)
+ *   return <>{data?.pages.map((page) => page.projects.map((p) => <p key={p.id}>{p.name}</p>))}</>
+ * }
  * ```
  *
  * @example

From e553284ad2356c42f82e7adfa6296c0588bcdfdd Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Wed, 26 Aug 2026 16:58:31 +0900
Subject: [PATCH 06/30] fix(preact-query): correctly distinguish error state
 from loading in 'infiniteQueryOptions' example

---
 .../preact/reference/functions/infiniteQueryOptions.md | 10 ++++++----
 packages/preact-query/src/infiniteQueryOptions.ts      |  6 ++++--
 2 files changed, 10 insertions(+), 6 deletions(-)

diff --git a/docs/framework/preact/reference/functions/infiniteQueryOptions.md b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
index d0bc2d79d0..f828e90cad 100644
--- a/docs/framework/preact/reference/functions/infiniteQueryOptions.md
+++ b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
@@ -80,7 +80,7 @@ function Projects() {
 function infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options): OmitKeyof<UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, "queryFn"> & object & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData, unknown>, TError>;
 ```
 
-Defined in: [preact-query/src/infiniteQueryOptions.ts:238](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L238)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:239](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L239)
 
 You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
 These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
@@ -156,7 +156,8 @@ export const commentsOptions = (postId: string) =>
 
 function Comments({ postId }: { postId: string }) {
   const result = useInfiniteQuery(commentsOptions(postId))
-  if (!result.isSuccess) return 'Loading...'
+  if (result.isPending) return 'Loading...'
+  if (result.isError) return <span>Error: {result.error.message}</span>
   return (
     <>
       {result.data.pages.map((page) => page.comments.map((c) => <p key={c.id}>{c.text}</p>))}
@@ -178,7 +179,7 @@ queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
 function infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options): UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & object & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData, unknown>, TError>;
 ```
 
-Defined in: [preact-query/src/infiniteQueryOptions.ts:319](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L319)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:321](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L321)
 
 You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
 These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
@@ -254,7 +255,8 @@ export const commentsOptions = (postId: string) =>
 
 function Comments({ postId }: { postId: string }) {
   const result = useInfiniteQuery(commentsOptions(postId))
-  if (!result.isSuccess) return 'Loading...'
+  if (result.isPending) return 'Loading...'
+  if (result.isError) return <span>Error: {result.error.message}</span>
   return (
     <>
       {result.data.pages.map((page) => page.comments.map((c) => <p key={c.id}>{c.text}</p>))}
diff --git a/packages/preact-query/src/infiniteQueryOptions.ts b/packages/preact-query/src/infiniteQueryOptions.ts
index 918fd58c23..0035bc4a7f 100644
--- a/packages/preact-query/src/infiniteQueryOptions.ts
+++ b/packages/preact-query/src/infiniteQueryOptions.ts
@@ -220,7 +220,8 @@ export function infiniteQueryOptions<
  *
  * function Comments({ postId }: { postId: string }) {
  *   const result = useInfiniteQuery(commentsOptions(postId))
- *   if (!result.isSuccess) return 'Loading...'
+ *   if (result.isPending) return 'Loading...'
+ *   if (result.isError) return <span>Error: {result.error.message}</span>
  *   return (
  *     <>
  *       {result.data.pages.map((page) => page.comments.map((c) => <p key={c.id}>{c.text}</p>))}
@@ -301,7 +302,8 @@ export function infiniteQueryOptions<
  *
  * function Comments({ postId }: { postId: string }) {
  *   const result = useInfiniteQuery(commentsOptions(postId))
- *   if (!result.isSuccess) return 'Loading...'
+ *   if (result.isPending) return 'Loading...'
+ *   if (result.isError) return <span>Error: {result.error.message}</span>
  *   return (
  *     <>
  *       {result.data.pages.map((page) => page.comments.map((c) => <p key={c.id}>{c.text}</p>))}

From 700ce6fed7c8adac360a198bcffc62cf711d4318 Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Wed, 26 Aug 2026 17:16:58 +0900
Subject: [PATCH 07/30] fix(preact-query): correct mutation terminology and
 filter by success status in 'useMutationState' examples

---
 docs/framework/preact/reference/functions/useIsMutating.md  | 2 +-
 .../preact/reference/functions/useMutationState.md          | 4 ++--
 packages/preact-query/src/useMutationState.ts               | 6 +++---
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/framework/preact/reference/functions/useIsMutating.md b/docs/framework/preact/reference/functions/useIsMutating.md
index 8b4954ffba..bfc97539bd 100644
--- a/docs/framework/preact/reference/functions/useIsMutating.md
+++ b/docs/framework/preact/reference/functions/useIsMutating.md
@@ -39,7 +39,7 @@ Will be the `number` of the mutations that your application is currently fetchin
 import { useIsMutating } from '@tanstack/preact-query'
 
 function PostsMutatingIndicator() {
-  // How many mutations matching the posts prefix are fetching?
+  // How many mutations matching the posts prefix are in progress?
   const isMutatingPosts = useIsMutating({ mutationKey: ['posts'] })
 
   return isMutatingPosts ? <span>Saving posts...</span> : null
diff --git a/docs/framework/preact/reference/functions/useMutationState.md b/docs/framework/preact/reference/functions/useMutationState.md
index 89a6e82959..93c2cb93e7 100644
--- a/docs/framework/preact/reference/functions/useMutationState.md
+++ b/docs/framework/preact/reference/functions/useMutationState.md
@@ -76,7 +76,7 @@ function Posts() {
 
   const data = useMutationState({
     // this mutation key needs to match the mutation key of the given mutation (see above)
-    filters: { mutationKey },
+    filters: { mutationKey, status: 'success' },
     select: (mutation) => mutation.state.data,
   })
 
@@ -96,7 +96,7 @@ import { useMutationState } from '@tanstack/preact-query'
 
 function LatestPost() {
   const data = useMutationState({
-    filters: { mutationKey: ['posts'] },
+    filters: { mutationKey: ['posts'], status: 'success' },
     select: (mutation) => mutation.state.data,
   })
 
diff --git a/packages/preact-query/src/useMutationState.ts b/packages/preact-query/src/useMutationState.ts
index a3f483651a..f6910d10a7 100644
--- a/packages/preact-query/src/useMutationState.ts
+++ b/packages/preact-query/src/useMutationState.ts
@@ -25,7 +25,7 @@ import { useSyncExternalStore } from './utils'
  * import { useIsMutating } from '@tanstack/preact-query'
  *
  * function PostsMutatingIndicator() {
- *   // How many mutations matching the posts prefix are fetching?
+ *   // How many mutations matching the posts prefix are in progress?
  *   const isMutatingPosts = useIsMutating({ mutationKey: ['posts'] })
  *
  *   return isMutatingPosts ? <span>Saving posts...</span> : null
@@ -123,7 +123,7 @@ function getResult<
  *
  *   const data = useMutationState({
  *     // this mutation key needs to match the mutation key of the given mutation (see above)
- *     filters: { mutationKey },
+ *     filters: { mutationKey, status: 'success' },
  *     select: (mutation) => mutation.state.data,
  *   })
  *
@@ -144,7 +144,7 @@ function getResult<
  *
  * function LatestPost() {
  *   const data = useMutationState({
- *     filters: { mutationKey: ['posts'] },
+ *     filters: { mutationKey: ['posts'], status: 'success' },
  *     select: (mutation) => mutation.state.data,
  *   })
  *

From 0c086bc07d5181fccf97f00d8f3c4dc28ccbd85b Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Wed, 26 Aug 2026 18:13:48 +0900
Subject: [PATCH 08/30] docs(preact-query): destructure useInfiniteQuery result
 in 'infiniteQueryOptions' example

---
 .../reference/functions/infiniteQueryOptions.md  | 16 ++++++++--------
 .../preact-query/src/infiniteQueryOptions.ts     | 16 ++++++++--------
 2 files changed, 16 insertions(+), 16 deletions(-)

diff --git a/docs/framework/preact/reference/functions/infiniteQueryOptions.md b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
index f828e90cad..e98e1daee4 100644
--- a/docs/framework/preact/reference/functions/infiniteQueryOptions.md
+++ b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
@@ -155,12 +155,12 @@ export const commentsOptions = (postId: string) =>
   })
 
 function Comments({ postId }: { postId: string }) {
-  const result = useInfiniteQuery(commentsOptions(postId))
-  if (result.isPending) return 'Loading...'
-  if (result.isError) return <span>Error: {result.error.message}</span>
+  const { data, isPending, isError, error } = useInfiniteQuery(commentsOptions(postId))
+  if (isPending) return 'Loading...'
+  if (isError) return <span>Error: {error.message}</span>
   return (
     <>
-      {result.data.pages.map((page) => page.comments.map((c) => <p key={c.id}>{c.text}</p>))}
+      {data.pages.map((page) => page.comments.map((c) => <p key={c.id}>{c.text}</p>))}
     </>
   )
 }
@@ -254,12 +254,12 @@ export const commentsOptions = (postId: string) =>
   })
 
 function Comments({ postId }: { postId: string }) {
-  const result = useInfiniteQuery(commentsOptions(postId))
-  if (result.isPending) return 'Loading...'
-  if (result.isError) return <span>Error: {result.error.message}</span>
+  const { data, isPending, isError, error } = useInfiniteQuery(commentsOptions(postId))
+  if (isPending) return 'Loading...'
+  if (isError) return <span>Error: {error.message}</span>
   return (
     <>
-      {result.data.pages.map((page) => page.comments.map((c) => <p key={c.id}>{c.text}</p>))}
+      {data.pages.map((page) => page.comments.map((c) => <p key={c.id}>{c.text}</p>))}
     </>
   )
 }
diff --git a/packages/preact-query/src/infiniteQueryOptions.ts b/packages/preact-query/src/infiniteQueryOptions.ts
index 0035bc4a7f..52945406d6 100644
--- a/packages/preact-query/src/infiniteQueryOptions.ts
+++ b/packages/preact-query/src/infiniteQueryOptions.ts
@@ -219,12 +219,12 @@ export function infiniteQueryOptions<
  *   })
  *
  * function Comments({ postId }: { postId: string }) {
- *   const result = useInfiniteQuery(commentsOptions(postId))
- *   if (result.isPending) return 'Loading...'
- *   if (result.isError) return <span>Error: {result.error.message}</span>
+ *   const { data, isPending, isError, error } = useInfiniteQuery(commentsOptions(postId))
+ *   if (isPending) return 'Loading...'
+ *   if (isError) return <span>Error: {error.message}</span>
  *   return (
  *     <>
- *       {result.data.pages.map((page) => page.comments.map((c) => <p key={c.id}>{c.text}</p>))}
+ *       {data.pages.map((page) => page.comments.map((c) => <p key={c.id}>{c.text}</p>))}
  *     </>
  *   )
  * }
@@ -301,12 +301,12 @@ export function infiniteQueryOptions<
  *   })
  *
  * function Comments({ postId }: { postId: string }) {
- *   const result = useInfiniteQuery(commentsOptions(postId))
- *   if (result.isPending) return 'Loading...'
- *   if (result.isError) return <span>Error: {result.error.message}</span>
+ *   const { data, isPending, isError, error } = useInfiniteQuery(commentsOptions(postId))
+ *   if (isPending) return 'Loading...'
+ *   if (isError) return <span>Error: {error.message}</span>
  *   return (
  *     <>
- *       {result.data.pages.map((page) => page.comments.map((c) => <p key={c.id}>{c.text}</p>))}
+ *       {data.pages.map((page) => page.comments.map((c) => <p key={c.id}>{c.text}</p>))}
  *     </>
  *   )
  * }

From 4ad73e09fbce2afdb58a2ce3788abdbaa60c97ad Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Wed, 26 Aug 2026 18:18:38 +0900
Subject: [PATCH 09/30] docs(preact-query): rename 'variables' to
 'pendingVariables' in 'useMutationState' example

---
 docs/framework/preact/reference/functions/useMutationState.md | 4 ++--
 packages/preact-query/src/useMutationState.ts                 | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/framework/preact/reference/functions/useMutationState.md b/docs/framework/preact/reference/functions/useMutationState.md
index 93c2cb93e7..432103c51e 100644
--- a/docs/framework/preact/reference/functions/useMutationState.md
+++ b/docs/framework/preact/reference/functions/useMutationState.md
@@ -52,12 +52,12 @@ Get all variables of all running mutations:
 import { useMutationState } from '@tanstack/preact-query'
 
 function PendingPosts() {
-  const variables = useMutationState({
+  const pendingVariables = useMutationState({
     filters: { status: 'pending' },
     select: (mutation) => mutation.state.variables,
   })
 
-  return <>{variables.length} posts saving...</>
+  return <>{pendingVariables.length} posts saving...</>
 }
 ```
 
diff --git a/packages/preact-query/src/useMutationState.ts b/packages/preact-query/src/useMutationState.ts
index f6910d10a7..cc17a71ba9 100644
--- a/packages/preact-query/src/useMutationState.ts
+++ b/packages/preact-query/src/useMutationState.ts
@@ -98,12 +98,12 @@ function getResult<
  * import { useMutationState } from '@tanstack/preact-query'
  *
  * function PendingPosts() {
- *   const variables = useMutationState({
+ *   const pendingVariables = useMutationState({
  *     filters: { status: 'pending' },
  *     select: (mutation) => mutation.state.variables,
  *   })
  *
- *   return <>{variables.length} posts saving...</>
+ *   return <>{pendingVariables.length} posts saving...</>
  * }
  * ```
  *

From 5d70bbe1c6d53ea73c1868d51077c394fead87b4 Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Wed, 26 Aug 2026 18:20:20 +0900
Subject: [PATCH 10/30] docs(preact-query): rename 'data' to 'savedPosts' in
 'useMutationState' examples

---
 .../preact/reference/functions/useMutationState.md        | 8 ++++----
 packages/preact-query/src/useMutationState.ts             | 8 ++++----
 2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/docs/framework/preact/reference/functions/useMutationState.md b/docs/framework/preact/reference/functions/useMutationState.md
index 432103c51e..e389a25451 100644
--- a/docs/framework/preact/reference/functions/useMutationState.md
+++ b/docs/framework/preact/reference/functions/useMutationState.md
@@ -74,7 +74,7 @@ function Posts() {
     mutationFn: createPosts,
   })
 
-  const data = useMutationState({
+  const savedPosts = useMutationState({
     // this mutation key needs to match the mutation key of the given mutation (see above)
     filters: { mutationKey, status: 'success' },
     select: (mutation) => mutation.state.data,
@@ -82,7 +82,7 @@ function Posts() {
 
   return (
     <button onClick={() => mutation.mutate(['New Post'])}>
-      Create post ({data.length} saved so far)
+      Create post ({savedPosts.length} saved so far)
     </button>
   )
 }
@@ -95,12 +95,12 @@ latest invocation:
 import { useMutationState } from '@tanstack/preact-query'
 
 function LatestPost() {
-  const data = useMutationState({
+  const savedPosts = useMutationState({
     filters: { mutationKey: ['posts'], status: 'success' },
     select: (mutation) => mutation.state.data,
   })
 
-  const latest = data[data.length - 1]
+  const latest = savedPosts[savedPosts.length - 1]
 
   return <>{latest ? 'Saved' : 'Nothing saved yet'}</>
 }
diff --git a/packages/preact-query/src/useMutationState.ts b/packages/preact-query/src/useMutationState.ts
index cc17a71ba9..58acc2414d 100644
--- a/packages/preact-query/src/useMutationState.ts
+++ b/packages/preact-query/src/useMutationState.ts
@@ -121,7 +121,7 @@ function getResult<
  *     mutationFn: createPosts,
  *   })
  *
- *   const data = useMutationState({
+ *   const savedPosts = useMutationState({
  *     // this mutation key needs to match the mutation key of the given mutation (see above)
  *     filters: { mutationKey, status: 'success' },
  *     select: (mutation) => mutation.state.data,
@@ -129,7 +129,7 @@ function getResult<
  *
  *   return (
  *     <button onClick={() => mutation.mutate(['New Post'])}>
- *       Create post ({data.length} saved so far)
+ *       Create post ({savedPosts.length} saved so far)
  *     </button>
  *   )
  * }
@@ -143,12 +143,12 @@ function getResult<
  * import { useMutationState } from '@tanstack/preact-query'
  *
  * function LatestPost() {
- *   const data = useMutationState({
+ *   const savedPosts = useMutationState({
  *     filters: { mutationKey: ['posts'], status: 'success' },
  *     select: (mutation) => mutation.state.data,
  *   })
  *
- *   const latest = data[data.length - 1]
+ *   const latest = savedPosts[savedPosts.length - 1]
  *
  *   return <>{latest ? 'Saved' : 'Nothing saved yet'}</>
  * }

From d64829fb2e7aee2bfa903eed2be8b6d36282e9a6 Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Wed, 26 Aug 2026 18:23:16 +0900
Subject: [PATCH 11/30] docs(preact-query): rename 'results'/'result' to
 'addResults'/'addResult' in 'useMutation' Promise.allSettled example

---
 docs/framework/preact/reference/functions/useMutation.md | 8 ++++----
 packages/preact-query/src/useMutation.ts                 | 8 ++++----
 2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/docs/framework/preact/reference/functions/useMutation.md b/docs/framework/preact/reference/functions/useMutation.md
index f01293841b..a5c6fe1939 100644
--- a/docs/framework/preact/reference/functions/useMutation.md
+++ b/docs/framework/preact/reference/functions/useMutation.md
@@ -193,13 +193,13 @@ function AddTodos() {
   })
 
   async function handleAddAll(todos: Array<string>) {
-    const results = await Promise.allSettled(
+    const addResults = await Promise.allSettled(
       todos.map((todo) => addMutation.mutateAsync(todo)),
     )
 
-    results.forEach((result, index) => {
-      if (result.status === 'rejected') {
-        console.error(`Failed to add "${todos[index]}":`, result.reason)
+    addResults.forEach((addResult, index) => {
+      if (addResult.status === 'rejected') {
+        console.error(`Failed to add "${todos[index]}":`, addResult.reason)
       }
     })
   }
diff --git a/packages/preact-query/src/useMutation.ts b/packages/preact-query/src/useMutation.ts
index 68a3759d93..bd4baf0326 100644
--- a/packages/preact-query/src/useMutation.ts
+++ b/packages/preact-query/src/useMutation.ts
@@ -168,13 +168,13 @@ import { useSyncExternalStore } from './utils'
  *   })
  *
  *   async function handleAddAll(todos: Array<string>) {
- *     const results = await Promise.allSettled(
+ *     const addResults = await Promise.allSettled(
  *       todos.map((todo) => addMutation.mutateAsync(todo)),
  *     )
  *
- *     results.forEach((result, index) => {
- *       if (result.status === 'rejected') {
- *         console.error(`Failed to add "${todos[index]}":`, result.reason)
+ *     addResults.forEach((addResult, index) => {
+ *       if (addResult.status === 'rejected') {
+ *         console.error(`Failed to add "${todos[index]}":`, addResult.reason)
  *       }
  *     })
  *   }

From 64b10ce7ed477a8d6b18ba3e4b03a957e24eda44 Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Wed, 26 Aug 2026 18:23:16 +0900
Subject: [PATCH 12/30] docs(preact-query): rename 'latest' to
 'latestSavedPost' in 'useMutationState' example

---
 docs/framework/preact/reference/functions/useMutationState.md | 4 ++--
 packages/preact-query/src/useMutationState.ts                 | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/framework/preact/reference/functions/useMutationState.md b/docs/framework/preact/reference/functions/useMutationState.md
index e389a25451..37bee7a2f6 100644
--- a/docs/framework/preact/reference/functions/useMutationState.md
+++ b/docs/framework/preact/reference/functions/useMutationState.md
@@ -100,8 +100,8 @@ function LatestPost() {
     select: (mutation) => mutation.state.data,
   })
 
-  const latest = savedPosts[savedPosts.length - 1]
+  const latestSavedPost = savedPosts[savedPosts.length - 1]
 
-  return <>{latest ? 'Saved' : 'Nothing saved yet'}</>
+  return <>{latestSavedPost ? 'Saved' : 'Nothing saved yet'}</>
 }
 ```
diff --git a/packages/preact-query/src/useMutationState.ts b/packages/preact-query/src/useMutationState.ts
index 58acc2414d..58e154a394 100644
--- a/packages/preact-query/src/useMutationState.ts
+++ b/packages/preact-query/src/useMutationState.ts
@@ -148,9 +148,9 @@ function getResult<
  *     select: (mutation) => mutation.state.data,
  *   })
  *
- *   const latest = savedPosts[savedPosts.length - 1]
+ *   const latestSavedPost = savedPosts[savedPosts.length - 1]
  *
- *   return <>{latest ? 'Saved' : 'Nothing saved yet'}</>
+ *   return <>{latestSavedPost ? 'Saved' : 'Nothing saved yet'}</>
  * }
  * ```
  */

From ec6828a351ea337124f2f65d88f4f20c22c2d251 Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Wed, 26 Aug 2026 21:25:55 +0900
Subject: [PATCH 13/30] docs(preact-query): render fetched pages and handle
 loading/error states in 'useInfiniteQuery' examples

---
 .../reference/functions/useInfiniteQuery.md   | 104 ++++++++++++------
 packages/preact-query/src/useInfiniteQuery.ts | 100 +++++++++++------
 2 files changed, 134 insertions(+), 70 deletions(-)

diff --git a/docs/framework/preact/reference/functions/useInfiniteQuery.md b/docs/framework/preact/reference/functions/useInfiniteQuery.md
index 3eaadf977b..e777d17e06 100644
--- a/docs/framework/preact/reference/functions/useInfiniteQuery.md
+++ b/docs/framework/preact/reference/functions/useInfiniteQuery.md
@@ -95,7 +95,7 @@ function Projects() {
 function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): UseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useInfiniteQuery.ts:115](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L115)
+Defined in: [preact-query/src/useInfiniteQuery.ts:131](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L131)
 
 The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
 `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
@@ -161,25 +161,41 @@ actions, or add conditions like `hasNextPage && !isFetching`.
 import { useInfiniteQuery } from '@tanstack/preact-query'
 
 function Projects() {
-  const { data, fetchNextPage, hasNextPage, isFetching, isFetchingNextPage } =
-    useInfiniteQuery({
-      queryKey: ['projects'],
-      queryFn: ({ pageParam }) => fetchProjects(pageParam),
-      initialPageParam: 0,
-      getNextPageParam: (lastPage) => lastPage.nextId,
-    })
+  const {
+    data,
+    isPending,
+    isError,
+    error,
+    fetchNextPage,
+    hasNextPage,
+    isFetching,
+    isFetchingNextPage,
+  } = useInfiniteQuery({
+    queryKey: ['projects'],
+    queryFn: ({ pageParam }) => fetchProjects(pageParam),
+    initialPageParam: 0,
+    getNextPageParam: (lastPage) => lastPage.nextId,
+  })
+
+  if (isPending) return 'Loading...'
+  if (isError) return <span>Error: {error.message}</span>
 
   return (
-    <button
-      onClick={() => fetchNextPage()}
-      disabled={!hasNextPage || isFetching}
-    >
-      {isFetchingNextPage
-        ? 'Loading more...'
-        : hasNextPage
-          ? 'Load More'
-          : 'Nothing more to load'}
-    </button>
+    <>
+      {data.pages.map((page) =>
+        page.projects.map((project) => <p key={project.id}>{project.name}</p>),
+      )}
+      <button
+        onClick={() => fetchNextPage()}
+        disabled={!hasNextPage || isFetching}
+      >
+        {isFetchingNextPage
+          ? 'Loading more...'
+          : hasNextPage
+            ? 'Load More'
+            : 'Nothing more to load'}
+      </button>
+    </>
   )
 }
 ```
@@ -190,7 +206,7 @@ function Projects() {
 function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): UseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useInfiniteQuery.ts:175](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L175)
+Defined in: [preact-query/src/useInfiniteQuery.ts:207](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L207)
 
 The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
 `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
@@ -256,25 +272,41 @@ actions, or add conditions like `hasNextPage && !isFetching`.
 import { useInfiniteQuery } from '@tanstack/preact-query'
 
 function Projects() {
-  const { data, fetchNextPage, hasNextPage, isFetching, isFetchingNextPage } =
-    useInfiniteQuery({
-      queryKey: ['projects'],
-      queryFn: ({ pageParam }) => fetchProjects(pageParam),
-      initialPageParam: 0,
-      getNextPageParam: (lastPage) => lastPage.nextId,
-    })
+  const {
+    data,
+    isPending,
+    isError,
+    error,
+    fetchNextPage,
+    hasNextPage,
+    isFetching,
+    isFetchingNextPage,
+  } = useInfiniteQuery({
+    queryKey: ['projects'],
+    queryFn: ({ pageParam }) => fetchProjects(pageParam),
+    initialPageParam: 0,
+    getNextPageParam: (lastPage) => lastPage.nextId,
+  })
+
+  if (isPending) return 'Loading...'
+  if (isError) return <span>Error: {error.message}</span>
 
   return (
-    <button
-      onClick={() => fetchNextPage()}
-      disabled={!hasNextPage || isFetching}
-    >
-      {isFetchingNextPage
-        ? 'Loading more...'
-        : hasNextPage
-          ? 'Load More'
-          : 'Nothing more to load'}
-    </button>
+    <>
+      {data.pages.map((page) =>
+        page.projects.map((project) => <p key={project.id}>{project.name}</p>),
+      )}
+      <button
+        onClick={() => fetchNextPage()}
+        disabled={!hasNextPage || isFetching}
+      >
+        {isFetchingNextPage
+          ? 'Loading more...'
+          : hasNextPage
+            ? 'Load More'
+            : 'Nothing more to load'}
+      </button>
+    </>
   )
 }
 ```
diff --git a/packages/preact-query/src/useInfiniteQuery.ts b/packages/preact-query/src/useInfiniteQuery.ts
index a525029ca7..49276bcd72 100644
--- a/packages/preact-query/src/useInfiniteQuery.ts
+++ b/packages/preact-query/src/useInfiniteQuery.ts
@@ -89,25 +89,41 @@ export function useInfiniteQuery<
  * import { useInfiniteQuery } from '@tanstack/preact-query'
  *
  * function Projects() {
- *   const { data, fetchNextPage, hasNextPage, isFetching, isFetchingNextPage } =
- *     useInfiniteQuery({
- *       queryKey: ['projects'],
- *       queryFn: ({ pageParam }) => fetchProjects(pageParam),
- *       initialPageParam: 0,
- *       getNextPageParam: (lastPage) => lastPage.nextId,
- *     })
+ *   const {
+ *     data,
+ *     isPending,
+ *     isError,
+ *     error,
+ *     fetchNextPage,
+ *     hasNextPage,
+ *     isFetching,
+ *     isFetchingNextPage,
+ *   } = useInfiniteQuery({
+ *     queryKey: ['projects'],
+ *     queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *     initialPageParam: 0,
+ *     getNextPageParam: (lastPage) => lastPage.nextId,
+ *   })
+ *
+ *   if (isPending) return 'Loading...'
+ *   if (isError) return <span>Error: {error.message}</span>
  *
  *   return (
- *     <button
- *       onClick={() => fetchNextPage()}
- *       disabled={!hasNextPage || isFetching}
- *     >
- *       {isFetchingNextPage
- *         ? 'Loading more...'
- *         : hasNextPage
- *           ? 'Load More'
- *           : 'Nothing more to load'}
- *     </button>
+ *     <>
+ *       {data.pages.map((page) =>
+ *         page.projects.map((project) => <p key={project.id}>{project.name}</p>),
+ *       )}
+ *       <button
+ *         onClick={() => fetchNextPage()}
+ *         disabled={!hasNextPage || isFetching}
+ *       >
+ *         {isFetchingNextPage
+ *           ? 'Loading more...'
+ *           : hasNextPage
+ *             ? 'Load More'
+ *             : 'Nothing more to load'}
+ *       </button>
+ *     </>
  *   )
  * }
  * ```
@@ -149,25 +165,41 @@ export function useInfiniteQuery<
  * import { useInfiniteQuery } from '@tanstack/preact-query'
  *
  * function Projects() {
- *   const { data, fetchNextPage, hasNextPage, isFetching, isFetchingNextPage } =
- *     useInfiniteQuery({
- *       queryKey: ['projects'],
- *       queryFn: ({ pageParam }) => fetchProjects(pageParam),
- *       initialPageParam: 0,
- *       getNextPageParam: (lastPage) => lastPage.nextId,
- *     })
+ *   const {
+ *     data,
+ *     isPending,
+ *     isError,
+ *     error,
+ *     fetchNextPage,
+ *     hasNextPage,
+ *     isFetching,
+ *     isFetchingNextPage,
+ *   } = useInfiniteQuery({
+ *     queryKey: ['projects'],
+ *     queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *     initialPageParam: 0,
+ *     getNextPageParam: (lastPage) => lastPage.nextId,
+ *   })
+ *
+ *   if (isPending) return 'Loading...'
+ *   if (isError) return <span>Error: {error.message}</span>
  *
  *   return (
- *     <button
- *       onClick={() => fetchNextPage()}
- *       disabled={!hasNextPage || isFetching}
- *     >
- *       {isFetchingNextPage
- *         ? 'Loading more...'
- *         : hasNextPage
- *           ? 'Load More'
- *           : 'Nothing more to load'}
- *     </button>
+ *     <>
+ *       {data.pages.map((page) =>
+ *         page.projects.map((project) => <p key={project.id}>{project.name}</p>),
+ *       )}
+ *       <button
+ *         onClick={() => fetchNextPage()}
+ *         disabled={!hasNextPage || isFetching}
+ *       >
+ *         {isFetchingNextPage
+ *           ? 'Loading more...'
+ *           : hasNextPage
+ *             ? 'Load More'
+ *             : 'Nothing more to load'}
+ *       </button>
+ *     </>
  *   )
  * }
  * ```

From 1c8408016f3cd3bba65a1dfb3767cdb5e6c35eb2 Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Sat, 29 Aug 2026 10:58:20 +0900
Subject: [PATCH 14/30] docs(preact-query): render infinite query lists as
 '<ul>'/'<li>' instead of flat '<p>' tags

---
 .../functions/infiniteQueryOptions.md         | 36 ++++++++++++-------
 .../reference/functions/useInfiniteQuery.md   | 20 ++++++-----
 .../preact-query/src/infiniteQueryOptions.ts  | 30 +++++++++++-----
 packages/preact-query/src/useInfiniteQuery.ts | 16 +++++----
 4 files changed, 67 insertions(+), 35 deletions(-)

diff --git a/docs/framework/preact/reference/functions/infiniteQueryOptions.md b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
index e98e1daee4..1b3f9e42f7 100644
--- a/docs/framework/preact/reference/functions/infiniteQueryOptions.md
+++ b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
@@ -9,7 +9,7 @@ title: infiniteQueryOptions
 function infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options): UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & object & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData, unknown>, TError>;
 ```
 
-Defined in: [preact-query/src/infiniteQueryOptions.ts:157](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L157)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:161](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L161)
 
 You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
 These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
@@ -70,7 +70,11 @@ export const projectsOptions = infiniteQueryOptions({
 
 function Projects() {
   const { data } = useInfiniteQuery(projectsOptions)
-  return <>{data.pages.map((page) => page.projects.map((p) => <p key={p.id}>{p.name}</p>))}</>
+  return (
+    <ul>
+      {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
+    </ul>
+  )
 }
 ```
 
@@ -80,7 +84,7 @@ function Projects() {
 function infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options): OmitKeyof<UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, "queryFn"> & object & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData, unknown>, TError>;
 ```
 
-Defined in: [preact-query/src/infiniteQueryOptions.ts:239](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L239)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:247](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L247)
 
 You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
 These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
@@ -134,7 +138,11 @@ export const projectsOptions = infiniteQueryOptions({
 
 function Projects() {
   const { data } = useInfiniteQuery(projectsOptions)
-  return <>{data?.pages.map((page) => page.projects.map((p) => <p key={p.id}>{p.name}</p>))}</>
+  return (
+    <ul>
+      {data?.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
+    </ul>
+  )
 }
 ```
 
@@ -159,9 +167,9 @@ function Comments({ postId }: { postId: string }) {
   if (isPending) return 'Loading...'
   if (isError) return <span>Error: {error.message}</span>
   return (
-    <>
-      {data.pages.map((page) => page.comments.map((c) => <p key={c.id}>{c.text}</p>))}
-    </>
+    <ul>
+      {data.pages.map((page) => page.comments.map((c) => <li key={c.id}>{c.text}</li>))}
+    </ul>
   )
 }
 
@@ -179,7 +187,7 @@ queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
 function infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options): UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & object & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData, unknown>, TError>;
 ```
 
-Defined in: [preact-query/src/infiniteQueryOptions.ts:321](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L321)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:333](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L333)
 
 You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
 These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
@@ -233,7 +241,11 @@ export const projectsOptions = infiniteQueryOptions({
 
 function Projects() {
   const { data } = useInfiniteQuery(projectsOptions)
-  return <>{data?.pages.map((page) => page.projects.map((p) => <p key={p.id}>{p.name}</p>))}</>
+  return (
+    <ul>
+      {data?.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
+    </ul>
+  )
 }
 ```
 
@@ -258,9 +270,9 @@ function Comments({ postId }: { postId: string }) {
   if (isPending) return 'Loading...'
   if (isError) return <span>Error: {error.message}</span>
   return (
-    <>
-      {data.pages.map((page) => page.comments.map((c) => <p key={c.id}>{c.text}</p>))}
-    </>
+    <ul>
+      {data.pages.map((page) => page.comments.map((c) => <li key={c.id}>{c.text}</li>))}
+    </ul>
   )
 }
 
diff --git a/docs/framework/preact/reference/functions/useInfiniteQuery.md b/docs/framework/preact/reference/functions/useInfiniteQuery.md
index e777d17e06..3cc3febe0a 100644
--- a/docs/framework/preact/reference/functions/useInfiniteQuery.md
+++ b/docs/framework/preact/reference/functions/useInfiniteQuery.md
@@ -95,7 +95,7 @@ function Projects() {
 function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): UseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useInfiniteQuery.ts:131](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L131)
+Defined in: [preact-query/src/useInfiniteQuery.ts:133](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L133)
 
 The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
 `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
@@ -182,9 +182,11 @@ function Projects() {
 
   return (
     <>
-      {data.pages.map((page) =>
-        page.projects.map((project) => <p key={project.id}>{project.name}</p>),
-      )}
+      <ul>
+        {data.pages.map((page) =>
+          page.projects.map((project) => <li key={project.id}>{project.name}</li>),
+        )}
+      </ul>
       <button
         onClick={() => fetchNextPage()}
         disabled={!hasNextPage || isFetching}
@@ -206,7 +208,7 @@ function Projects() {
 function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): UseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useInfiniteQuery.ts:207](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L207)
+Defined in: [preact-query/src/useInfiniteQuery.ts:211](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L211)
 
 The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
 `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
@@ -293,9 +295,11 @@ function Projects() {
 
   return (
     <>
-      {data.pages.map((page) =>
-        page.projects.map((project) => <p key={project.id}>{project.name}</p>),
-      )}
+      <ul>
+        {data.pages.map((page) =>
+          page.projects.map((project) => <li key={project.id}>{project.name}</li>),
+        )}
+      </ul>
       <button
         onClick={() => fetchNextPage()}
         disabled={!hasNextPage || isFetching}
diff --git a/packages/preact-query/src/infiniteQueryOptions.ts b/packages/preact-query/src/infiniteQueryOptions.ts
index 52945406d6..9920ebdb9f 100644
--- a/packages/preact-query/src/infiniteQueryOptions.ts
+++ b/packages/preact-query/src/infiniteQueryOptions.ts
@@ -150,7 +150,11 @@ export type DefinedInitialDataInfiniteOptions<
  *
  * function Projects() {
  *   const { data } = useInfiniteQuery(projectsOptions)
- *   return <>{data.pages.map((page) => page.projects.map((p) => <p key={p.id}>{p.name}</p>))}</>
+ *   return (
+ *     <ul>
+ *       {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
+ *     </ul>
+ *   )
  * }
  * ```
  */
@@ -197,7 +201,11 @@ export function infiniteQueryOptions<
  *
  * function Projects() {
  *   const { data } = useInfiniteQuery(projectsOptions)
- *   return <>{data?.pages.map((page) => page.projects.map((p) => <p key={p.id}>{p.name}</p>))}</>
+ *   return (
+ *     <ul>
+ *       {data?.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
+ *     </ul>
+ *   )
  * }
  * ```
  *
@@ -223,9 +231,9 @@ export function infiniteQueryOptions<
  *   if (isPending) return 'Loading...'
  *   if (isError) return <span>Error: {error.message}</span>
  *   return (
- *     <>
- *       {data.pages.map((page) => page.comments.map((c) => <p key={c.id}>{c.text}</p>))}
- *     </>
+ *     <ul>
+ *       {data.pages.map((page) => page.comments.map((c) => <li key={c.id}>{c.text}</li>))}
+ *     </ul>
  *   )
  * }
  *
@@ -279,7 +287,11 @@ export function infiniteQueryOptions<
  *
  * function Projects() {
  *   const { data } = useInfiniteQuery(projectsOptions)
- *   return <>{data?.pages.map((page) => page.projects.map((p) => <p key={p.id}>{p.name}</p>))}</>
+ *   return (
+ *     <ul>
+ *       {data?.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
+ *     </ul>
+ *   )
  * }
  * ```
  *
@@ -305,9 +317,9 @@ export function infiniteQueryOptions<
  *   if (isPending) return 'Loading...'
  *   if (isError) return <span>Error: {error.message}</span>
  *   return (
- *     <>
- *       {data.pages.map((page) => page.comments.map((c) => <p key={c.id}>{c.text}</p>))}
- *     </>
+ *     <ul>
+ *       {data.pages.map((page) => page.comments.map((c) => <li key={c.id}>{c.text}</li>))}
+ *     </ul>
  *   )
  * }
  *
diff --git a/packages/preact-query/src/useInfiniteQuery.ts b/packages/preact-query/src/useInfiniteQuery.ts
index 49276bcd72..47848f9cca 100644
--- a/packages/preact-query/src/useInfiniteQuery.ts
+++ b/packages/preact-query/src/useInfiniteQuery.ts
@@ -110,9 +110,11 @@ export function useInfiniteQuery<
  *
  *   return (
  *     <>
- *       {data.pages.map((page) =>
- *         page.projects.map((project) => <p key={project.id}>{project.name}</p>),
- *       )}
+ *       <ul>
+ *         {data.pages.map((page) =>
+ *           page.projects.map((project) => <li key={project.id}>{project.name}</li>),
+ *         )}
+ *       </ul>
  *       <button
  *         onClick={() => fetchNextPage()}
  *         disabled={!hasNextPage || isFetching}
@@ -186,9 +188,11 @@ export function useInfiniteQuery<
  *
  *   return (
  *     <>
- *       {data.pages.map((page) =>
- *         page.projects.map((project) => <p key={project.id}>{project.name}</p>),
- *       )}
+ *       <ul>
+ *         {data.pages.map((page) =>
+ *           page.projects.map((project) => <li key={project.id}>{project.name}</li>),
+ *         )}
+ *       </ul>
  *       <button
  *         onClick={() => fetchNextPage()}
  *         disabled={!hasNextPage || isFetching}

From 7bc2b99a6f6360bca1f5ece9793470d37a6c8207 Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Sat, 29 Aug 2026 11:05:37 +0900
Subject: [PATCH 15/30] docs(preact-query): show hover-triggered prefetch
 instead of an unlocated 'Elsewhere' comment in
 'queryOptions'/'infiniteQueryOptions' examples

---
 .../functions/infiniteQueryOptions.md         | 30 ++++++++--
 .../reference/functions/queryOptions.md       | 58 +++++++++++++++----
 .../preact-query/src/infiniteQueryOptions.ts  | 26 +++++++--
 packages/preact-query/src/queryOptions.ts     | 54 +++++++++++++----
 4 files changed, 136 insertions(+), 32 deletions(-)

diff --git a/docs/framework/preact/reference/functions/infiniteQueryOptions.md b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
index 1b3f9e42f7..b09e62e6d5 100644
--- a/docs/framework/preact/reference/functions/infiniteQueryOptions.md
+++ b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
@@ -84,7 +84,7 @@ function Projects() {
 function infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options): OmitKeyof<UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, "queryFn"> & object & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData, unknown>, TError>;
 ```
 
-Defined in: [preact-query/src/infiniteQueryOptions.ts:247](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L247)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:256](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L256)
 
 You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
 These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
@@ -173,8 +173,17 @@ function Comments({ postId }: { postId: string }) {
   )
 }
 
-// Elsewhere, e.g. to warm the cache before rendering `<Comments>`:
-queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
+function PostLink({ postId, title }: { postId: string; title: string }) {
+  return (
+    <a
+      href={`/posts/${postId}`}
+      // Warm the cache on hover, so `<Comments>` has data as soon as it's clicked.
+      onMouseEnter={() => queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)}
+    >
+      {title}
+    </a>
+  )
+}
 ```
 
 ### See
@@ -187,7 +196,7 @@ queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
 function infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options): UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & object & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData, unknown>, TError>;
 ```
 
-Defined in: [preact-query/src/infiniteQueryOptions.ts:333](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L333)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:351](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L351)
 
 You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
 These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
@@ -276,8 +285,17 @@ function Comments({ postId }: { postId: string }) {
   )
 }
 
-// Elsewhere, e.g. to warm the cache before rendering `<Comments>`:
-queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
+function PostLink({ postId, title }: { postId: string; title: string }) {
+  return (
+    <a
+      href={`/posts/${postId}`}
+      // Warm the cache on hover, so `<Comments>` has data as soon as it's clicked.
+      onMouseEnter={() => queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)}
+    >
+      {title}
+    </a>
+  )
+}
 ```
 
 ### See
diff --git a/docs/framework/preact/reference/functions/queryOptions.md b/docs/framework/preact/reference/functions/queryOptions.md
index 67ffd67b7e..d3c981b0ec 100644
--- a/docs/framework/preact/reference/functions/queryOptions.md
+++ b/docs/framework/preact/reference/functions/queryOptions.md
@@ -75,7 +75,7 @@ function Posts() {
 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:205](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L205)
+Defined in: [preact-query/src/queryOptions.ts:222](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L222)
 
 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
@@ -146,8 +146,17 @@ function Post({ id }: { id: string }) {
   return <h1>{data?.title}</h1>
 }
 
-// Elsewhere, e.g. to warm the cache before rendering `<Post>`:
-queryClient.query(postOptions(id)).catch(noop)
+function PostLink({ id, title }: { id: string; title: string }) {
+  return (
+    <a
+      href={`/posts/${id}`}
+      // Warm the cache on hover, so `<Post>` has data as soon as it's clicked.
+      onMouseEnter={() => queryClient.query(postOptions(id)).catch(noop)}
+    >
+      {title}
+    </a>
+  )
+}
 ```
 
 The same options object works with every API that accepts query options:
@@ -164,9 +173,17 @@ function Todos() {
   return <>{data?.map((todo) => <p key={todo.id}>{todo.title}</p>)}</>
 }
 
-// Elsewhere, e.g. to warm the cache before rendering `<Todos>`:
-queryClient.query(todosOptions).catch(noop)
-queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefined
+function TodosLink() {
+  return (
+    <a
+      href="/todos"
+      // Warm the cache on hover, so `<Todos>` has data as soon as it's clicked.
+      onMouseEnter={() => queryClient.query(todosOptions).catch(noop)}
+    >
+      Todos ({queryClient.getQueryData(todosOptions.queryKey)?.length ?? '...'})
+    </a>
+  )
+}
 ```
 
 ## Call Signature
@@ -175,7 +192,7 @@ queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefi
 function queryOptions<TQueryFnData, TError, TData, TQueryKey>(options): UseQueryOptions<TQueryFnData, TError, TData, TQueryKey> & object & QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>;
 ```
 
-Defined in: [preact-query/src/queryOptions.ts:279](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L279)
+Defined in: [preact-query/src/queryOptions.ts:313](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L313)
 
 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
@@ -246,8 +263,17 @@ function Post({ id }: { id: string }) {
   return <h1>{data?.title}</h1>
 }
 
-// Elsewhere, e.g. to warm the cache before rendering `<Post>`:
-queryClient.query(postOptions(id)).catch(noop)
+function PostLink({ id, title }: { id: string; title: string }) {
+  return (
+    <a
+      href={`/posts/${id}`}
+      // Warm the cache on hover, so `<Post>` has data as soon as it's clicked.
+      onMouseEnter={() => queryClient.query(postOptions(id)).catch(noop)}
+    >
+      {title}
+    </a>
+  )
+}
 ```
 
 The same options object works with every API that accepts query options:
@@ -264,7 +290,15 @@ function Todos() {
   return <>{data?.map((todo) => <p key={todo.id}>{todo.title}</p>)}</>
 }
 
-// Elsewhere, e.g. to warm the cache before rendering `<Todos>`:
-queryClient.query(todosOptions).catch(noop)
-queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefined
+function TodosLink() {
+  return (
+    <a
+      href="/todos"
+      // Warm the cache on hover, so `<Todos>` has data as soon as it's clicked.
+      onMouseEnter={() => queryClient.query(todosOptions).catch(noop)}
+    >
+      Todos ({queryClient.getQueryData(todosOptions.queryKey)?.length ?? '...'})
+    </a>
+  )
+}
 ```
diff --git a/packages/preact-query/src/infiniteQueryOptions.ts b/packages/preact-query/src/infiniteQueryOptions.ts
index 9920ebdb9f..e0191c183b 100644
--- a/packages/preact-query/src/infiniteQueryOptions.ts
+++ b/packages/preact-query/src/infiniteQueryOptions.ts
@@ -237,8 +237,17 @@ export function infiniteQueryOptions<
  *   )
  * }
  *
- * // Elsewhere, e.g. to warm the cache before rendering `<Comments>`:
- * queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
+ * function PostLink({ postId, title }: { postId: string; title: string }) {
+ *   return (
+ *     <a
+ *       href={`/posts/${postId}`}
+ *       // Warm the cache on hover, so `<Comments>` has data as soon as it's clicked.
+ *       onMouseEnter={() => queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)}
+ *     >
+ *       {title}
+ *     </a>
+ *   )
+ * }
  * ```
  *
  * @see {@link useInfiniteQuery} to run an infinite query with these options.
@@ -323,8 +332,17 @@ export function infiniteQueryOptions<
  *   )
  * }
  *
- * // Elsewhere, e.g. to warm the cache before rendering `<Comments>`:
- * queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
+ * function PostLink({ postId, title }: { postId: string; title: string }) {
+ *   return (
+ *     <a
+ *       href={`/posts/${postId}`}
+ *       // Warm the cache on hover, so `<Comments>` has data as soon as it's clicked.
+ *       onMouseEnter={() => queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)}
+ *     >
+ *       {title}
+ *     </a>
+ *   )
+ * }
  * ```
  *
  * @see {@link useInfiniteQuery} to run an infinite query with these options.
diff --git a/packages/preact-query/src/queryOptions.ts b/packages/preact-query/src/queryOptions.ts
index db8350dd53..c10f8fb70d 100644
--- a/packages/preact-query/src/queryOptions.ts
+++ b/packages/preact-query/src/queryOptions.ts
@@ -178,8 +178,17 @@ export function queryOptions<
  *   return <h1>{data?.title}</h1>
  * }
  *
- * // Elsewhere, e.g. to warm the cache before rendering `<Post>`:
- * queryClient.query(postOptions(id)).catch(noop)
+ * function PostLink({ id, title }: { id: string; title: string }) {
+ *   return (
+ *     <a
+ *       href={`/posts/${id}`}
+ *       // Warm the cache on hover, so `<Post>` has data as soon as it's clicked.
+ *       onMouseEnter={() => queryClient.query(postOptions(id)).catch(noop)}
+ *     >
+ *       {title}
+ *     </a>
+ *   )
+ * }
  * ```
  *
  * @example
@@ -197,9 +206,17 @@ export function queryOptions<
  *   return <>{data?.map((todo) => <p key={todo.id}>{todo.title}</p>)}</>
  * }
  *
- * // Elsewhere, e.g. to warm the cache before rendering `<Todos>`:
- * queryClient.query(todosOptions).catch(noop)
- * queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefined
+ * function TodosLink() {
+ *   return (
+ *     <a
+ *       href="/todos"
+ *       // Warm the cache on hover, so `<Todos>` has data as soon as it's clicked.
+ *       onMouseEnter={() => queryClient.query(todosOptions).catch(noop)}
+ *     >
+ *       Todos ({queryClient.getQueryData(todosOptions.queryKey)?.length ?? '...'})
+ *     </a>
+ *   )
+ * }
  * ```
  */
 export function queryOptions<
@@ -252,8 +269,17 @@ export function queryOptions<
  *   return <h1>{data?.title}</h1>
  * }
  *
- * // Elsewhere, e.g. to warm the cache before rendering `<Post>`:
- * queryClient.query(postOptions(id)).catch(noop)
+ * function PostLink({ id, title }: { id: string; title: string }) {
+ *   return (
+ *     <a
+ *       href={`/posts/${id}`}
+ *       // Warm the cache on hover, so `<Post>` has data as soon as it's clicked.
+ *       onMouseEnter={() => queryClient.query(postOptions(id)).catch(noop)}
+ *     >
+ *       {title}
+ *     </a>
+ *   )
+ * }
  * ```
  *
  * @example
@@ -271,9 +297,17 @@ export function queryOptions<
  *   return <>{data?.map((todo) => <p key={todo.id}>{todo.title}</p>)}</>
  * }
  *
- * // Elsewhere, e.g. to warm the cache before rendering `<Todos>`:
- * queryClient.query(todosOptions).catch(noop)
- * queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefined
+ * function TodosLink() {
+ *   return (
+ *     <a
+ *       href="/todos"
+ *       // Warm the cache on hover, so `<Todos>` has data as soon as it's clicked.
+ *       onMouseEnter={() => queryClient.query(todosOptions).catch(noop)}
+ *     >
+ *       Todos ({queryClient.getQueryData(todosOptions.queryKey)?.length ?? '...'})
+ *     </a>
+ *   )
+ * }
  * ```
  */
 export function queryOptions<

From 0516c2ea065e8e82a2de31461b5239253c8e3a3b Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Sat, 29 Aug 2026 11:08:52 +0900
Subject: [PATCH 16/30] docs(preact-query): move hover-prefetch examples from
 'queryOptions'/'infiniteQueryOptions' to 'useQuery'/'useInfiniteQuery'

---
 .../functions/infiniteQueryOptions.md         | 32 +++-------
 .../reference/functions/queryOptions.md       | 60 +++++--------------
 .../reference/functions/useInfiniteQuery.md   | 47 ++++++++++++++-
 .../preact/reference/functions/useQuery.md    | 32 +++++++++-
 .../preact-query/src/infiniteQueryOptions.ts  | 28 ++-------
 packages/preact-query/src/queryOptions.ts     | 56 ++++-------------
 packages/preact-query/src/useInfiniteQuery.ts | 44 ++++++++++++++
 packages/preact-query/src/useQuery.ts         | 31 ++++++++++
 8 files changed, 191 insertions(+), 139 deletions(-)

diff --git a/docs/framework/preact/reference/functions/infiniteQueryOptions.md b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
index b09e62e6d5..af839473ab 100644
--- a/docs/framework/preact/reference/functions/infiniteQueryOptions.md
+++ b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
@@ -84,7 +84,7 @@ function Projects() {
 function infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options): OmitKeyof<UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, "queryFn"> & object & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData, unknown>, TError>;
 ```
 
-Defined in: [preact-query/src/infiniteQueryOptions.ts:256](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L256)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:248](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L248)
 
 You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
 These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
@@ -173,17 +173,9 @@ function Comments({ postId }: { postId: string }) {
   )
 }
 
-function PostLink({ postId, title }: { postId: string; title: string }) {
-  return (
-    <a
-      href={`/posts/${postId}`}
-      // Warm the cache on hover, so `<Comments>` has data as soon as it's clicked.
-      onMouseEnter={() => queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)}
-    >
-      {title}
-    </a>
-  )
-}
+// `commentsOptions` also works with imperative APIs like `queryClient.infiniteQuery` —
+// see `useInfiniteQuery` for an example that warms the cache this way before rendering `<Comments>`.
+queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
 ```
 
 ### See
@@ -196,7 +188,7 @@ function PostLink({ postId, title }: { postId: string; title: string }) {
 function infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options): UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & object & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData, unknown>, TError>;
 ```
 
-Defined in: [preact-query/src/infiniteQueryOptions.ts:351](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L351)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:335](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L335)
 
 You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
 These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
@@ -285,17 +277,9 @@ function Comments({ postId }: { postId: string }) {
   )
 }
 
-function PostLink({ postId, title }: { postId: string; title: string }) {
-  return (
-    <a
-      href={`/posts/${postId}`}
-      // Warm the cache on hover, so `<Comments>` has data as soon as it's clicked.
-      onMouseEnter={() => queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)}
-    >
-      {title}
-    </a>
-  )
-}
+// `commentsOptions` also works with imperative APIs like `queryClient.infiniteQuery` —
+// see `useInfiniteQuery` for an example that warms the cache this way before rendering `<Comments>`.
+queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
 ```
 
 ### See
diff --git a/docs/framework/preact/reference/functions/queryOptions.md b/docs/framework/preact/reference/functions/queryOptions.md
index d3c981b0ec..e8cf70e228 100644
--- a/docs/framework/preact/reference/functions/queryOptions.md
+++ b/docs/framework/preact/reference/functions/queryOptions.md
@@ -75,7 +75,7 @@ function Posts() {
 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:222](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L222)
+Defined in: [preact-query/src/queryOptions.ts:206](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L206)
 
 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
@@ -146,17 +146,9 @@ function Post({ id }: { id: string }) {
   return <h1>{data?.title}</h1>
 }
 
-function PostLink({ id, title }: { id: string; title: string }) {
-  return (
-    <a
-      href={`/posts/${id}`}
-      // Warm the cache on hover, so `<Post>` has data as soon as it's clicked.
-      onMouseEnter={() => queryClient.query(postOptions(id)).catch(noop)}
-    >
-      {title}
-    </a>
-  )
-}
+// `postOptions` also works with imperative APIs like `queryClient.query` —
+// see `useQuery` for an example that warms the cache this way before rendering `<Post>`.
+queryClient.query(postOptions(id)).catch(noop)
 ```
 
 The same options object works with every API that accepts query options:
@@ -173,17 +165,9 @@ function Todos() {
   return <>{data?.map((todo) => <p key={todo.id}>{todo.title}</p>)}</>
 }
 
-function TodosLink() {
-  return (
-    <a
-      href="/todos"
-      // Warm the cache on hover, so `<Todos>` has data as soon as it's clicked.
-      onMouseEnter={() => queryClient.query(todosOptions).catch(noop)}
-    >
-      Todos ({queryClient.getQueryData(todosOptions.queryKey)?.length ?? '...'})
-    </a>
-  )
-}
+// 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
@@ -192,7 +176,7 @@ function TodosLink() {
 function queryOptions<TQueryFnData, TError, TData, TQueryKey>(options): UseQueryOptions<TQueryFnData, TError, TData, TQueryKey> & object & QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>;
 ```
 
-Defined in: [preact-query/src/queryOptions.ts:313](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L313)
+Defined in: [preact-query/src/queryOptions.ts:281](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L281)
 
 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
@@ -263,17 +247,9 @@ function Post({ id }: { id: string }) {
   return <h1>{data?.title}</h1>
 }
 
-function PostLink({ id, title }: { id: string; title: string }) {
-  return (
-    <a
-      href={`/posts/${id}`}
-      // Warm the cache on hover, so `<Post>` has data as soon as it's clicked.
-      onMouseEnter={() => queryClient.query(postOptions(id)).catch(noop)}
-    >
-      {title}
-    </a>
-  )
-}
+// `postOptions` also works with imperative APIs like `queryClient.query` —
+// see `useQuery` for an example that warms the cache this way before rendering `<Post>`.
+queryClient.query(postOptions(id)).catch(noop)
 ```
 
 The same options object works with every API that accepts query options:
@@ -290,15 +266,7 @@ function Todos() {
   return <>{data?.map((todo) => <p key={todo.id}>{todo.title}</p>)}</>
 }
 
-function TodosLink() {
-  return (
-    <a
-      href="/todos"
-      // Warm the cache on hover, so `<Todos>` has data as soon as it's clicked.
-      onMouseEnter={() => queryClient.query(todosOptions).catch(noop)}
-    >
-      Todos ({queryClient.getQueryData(todosOptions.queryKey)?.length ?? '...'})
-    </a>
-  )
-}
+// The same options object works with the imperative APIs too:
+queryClient.query(todosOptions).catch(noop)
+queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefined
 ```
diff --git a/docs/framework/preact/reference/functions/useInfiniteQuery.md b/docs/framework/preact/reference/functions/useInfiniteQuery.md
index 3cc3febe0a..623396fa78 100644
--- a/docs/framework/preact/reference/functions/useInfiniteQuery.md
+++ b/docs/framework/preact/reference/functions/useInfiniteQuery.md
@@ -208,7 +208,7 @@ function Projects() {
 function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): UseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useInfiniteQuery.ts:211](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L211)
+Defined in: [preact-query/src/useInfiniteQuery.ts:255](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L255)
 
 The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
 `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
@@ -268,7 +268,7 @@ actions, or add conditions like `hasNextPage && !isFetching`.
 
 [infiniteQueryOptions](infiniteQueryOptions.md) to share these options between `useInfiniteQuery` and imperative APIs like `queryClient.infiniteQuery`.
 
-### Example
+### Examples
 
 ```tsx
 import { useInfiniteQuery } from '@tanstack/preact-query'
@@ -314,3 +314,46 @@ function Projects() {
   )
 }
 ```
+
+Warming the cache on hover, so `<Comments>` has data as soon as it's clicked. Requires an
+[infiniteQueryOptions](infiniteQueryOptions.md) factory, so the hook and the imperative call share the same cache entry:
+```tsx
+import {
+  infiniteQueryOptions,
+  noop,
+  useInfiniteQuery,
+  useQueryClient,
+} from '@tanstack/preact-query'
+
+const commentsOptions = (postId: string) =>
+  infiniteQueryOptions({
+    queryKey: ['post', postId, 'comments'],
+    queryFn: ({ pageParam }) => fetchComments(postId, pageParam),
+    initialPageParam: 0,
+    getNextPageParam: (lastPage) => lastPage.nextId,
+  })
+
+function Comments({ postId }: { postId: string }) {
+  const { data, isPending, isError, error } = useInfiniteQuery(commentsOptions(postId))
+  if (isPending) return 'Loading...'
+  if (isError) return <span>Error: {error.message}</span>
+  return (
+    <ul>
+      {data.pages.map((page) => page.comments.map((c) => <li key={c.id}>{c.text}</li>))}
+    </ul>
+  )
+}
+
+function PostLink({ postId, title }: { postId: string; title: string }) {
+  const queryClient = useQueryClient()
+
+  return (
+    <a
+      href={`/posts/${postId}`}
+      onMouseEnter={() => queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)}
+    >
+      {title}
+    </a>
+  )
+}
+```
diff --git a/docs/framework/preact/reference/functions/useQuery.md b/docs/framework/preact/reference/functions/useQuery.md
index c9d8c943d1..126d9488c8 100644
--- a/docs/framework/preact/reference/functions/useQuery.md
+++ b/docs/framework/preact/reference/functions/useQuery.md
@@ -178,7 +178,7 @@ function Posts() {
 function useQuery<TQueryFnData, TError, TData, TQueryKey>(options, queryClient?): UseQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useQuery.ts:221](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L221)
+Defined in: [preact-query/src/useQuery.ts:252](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L252)
 
 ### Type Parameters
 
@@ -319,3 +319,33 @@ function Posts() {
   )
 }
 ```
+
+Warming the cache on hover, so `<Post>` has data as soon as it's clicked. Requires a
+[queryOptions](queryOptions.md) factory, so the hook and the imperative call share the same cache entry:
+```tsx
+import { noop, queryOptions, useQuery, useQueryClient } from '@tanstack/preact-query'
+
+const postOptions = (id: string) =>
+  queryOptions({
+    queryKey: ['post', id],
+    queryFn: () => fetchPost(id),
+  })
+
+function Post({ id }: { id: string }) {
+  const { data } = useQuery(postOptions(id))
+  return <h1>{data?.title}</h1>
+}
+
+function PostLink({ id, title }: { id: string; title: string }) {
+  const queryClient = useQueryClient()
+
+  return (
+    <a
+      href={`/posts/${id}`}
+      onMouseEnter={() => queryClient.query(postOptions(id)).catch(noop)}
+    >
+      {title}
+    </a>
+  )
+}
+```
diff --git a/packages/preact-query/src/infiniteQueryOptions.ts b/packages/preact-query/src/infiniteQueryOptions.ts
index e0191c183b..673271c525 100644
--- a/packages/preact-query/src/infiniteQueryOptions.ts
+++ b/packages/preact-query/src/infiniteQueryOptions.ts
@@ -237,17 +237,9 @@ export function infiniteQueryOptions<
  *   )
  * }
  *
- * function PostLink({ postId, title }: { postId: string; title: string }) {
- *   return (
- *     <a
- *       href={`/posts/${postId}`}
- *       // Warm the cache on hover, so `<Comments>` has data as soon as it's clicked.
- *       onMouseEnter={() => queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)}
- *     >
- *       {title}
- *     </a>
- *   )
- * }
+ * // `commentsOptions` also works with imperative APIs like `queryClient.infiniteQuery` —
+ * // see `useInfiniteQuery` for an example that warms the cache this way before rendering `<Comments>`.
+ * queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
  * ```
  *
  * @see {@link useInfiniteQuery} to run an infinite query with these options.
@@ -332,17 +324,9 @@ export function infiniteQueryOptions<
  *   )
  * }
  *
- * function PostLink({ postId, title }: { postId: string; title: string }) {
- *   return (
- *     <a
- *       href={`/posts/${postId}`}
- *       // Warm the cache on hover, so `<Comments>` has data as soon as it's clicked.
- *       onMouseEnter={() => queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)}
- *     >
- *       {title}
- *     </a>
- *   )
- * }
+ * // `commentsOptions` also works with imperative APIs like `queryClient.infiniteQuery` —
+ * // see `useInfiniteQuery` for an example that warms the cache this way before rendering `<Comments>`.
+ * queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
  * ```
  *
  * @see {@link useInfiniteQuery} to run an infinite query with these options.
diff --git a/packages/preact-query/src/queryOptions.ts b/packages/preact-query/src/queryOptions.ts
index c10f8fb70d..e5331c8d0a 100644
--- a/packages/preact-query/src/queryOptions.ts
+++ b/packages/preact-query/src/queryOptions.ts
@@ -178,17 +178,9 @@ export function queryOptions<
  *   return <h1>{data?.title}</h1>
  * }
  *
- * function PostLink({ id, title }: { id: string; title: string }) {
- *   return (
- *     <a
- *       href={`/posts/${id}`}
- *       // Warm the cache on hover, so `<Post>` has data as soon as it's clicked.
- *       onMouseEnter={() => queryClient.query(postOptions(id)).catch(noop)}
- *     >
- *       {title}
- *     </a>
- *   )
- * }
+ * // `postOptions` also works with imperative APIs like `queryClient.query` —
+ * // see `useQuery` for an example that warms the cache this way before rendering `<Post>`.
+ * queryClient.query(postOptions(id)).catch(noop)
  * ```
  *
  * @example
@@ -206,17 +198,9 @@ export function queryOptions<
  *   return <>{data?.map((todo) => <p key={todo.id}>{todo.title}</p>)}</>
  * }
  *
- * function TodosLink() {
- *   return (
- *     <a
- *       href="/todos"
- *       // Warm the cache on hover, so `<Todos>` has data as soon as it's clicked.
- *       onMouseEnter={() => queryClient.query(todosOptions).catch(noop)}
- *     >
- *       Todos ({queryClient.getQueryData(todosOptions.queryKey)?.length ?? '...'})
- *     </a>
- *   )
- * }
+ * // The same options object works with the imperative APIs too:
+ * queryClient.query(todosOptions).catch(noop)
+ * queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefined
  * ```
  */
 export function queryOptions<
@@ -269,17 +253,9 @@ export function queryOptions<
  *   return <h1>{data?.title}</h1>
  * }
  *
- * function PostLink({ id, title }: { id: string; title: string }) {
- *   return (
- *     <a
- *       href={`/posts/${id}`}
- *       // Warm the cache on hover, so `<Post>` has data as soon as it's clicked.
- *       onMouseEnter={() => queryClient.query(postOptions(id)).catch(noop)}
- *     >
- *       {title}
- *     </a>
- *   )
- * }
+ * // `postOptions` also works with imperative APIs like `queryClient.query` —
+ * // see `useQuery` for an example that warms the cache this way before rendering `<Post>`.
+ * queryClient.query(postOptions(id)).catch(noop)
  * ```
  *
  * @example
@@ -297,17 +273,9 @@ export function queryOptions<
  *   return <>{data?.map((todo) => <p key={todo.id}>{todo.title}</p>)}</>
  * }
  *
- * function TodosLink() {
- *   return (
- *     <a
- *       href="/todos"
- *       // Warm the cache on hover, so `<Todos>` has data as soon as it's clicked.
- *       onMouseEnter={() => queryClient.query(todosOptions).catch(noop)}
- *     >
- *       Todos ({queryClient.getQueryData(todosOptions.queryKey)?.length ?? '...'})
- *     </a>
- *   )
- * }
+ * // The same options object works with the imperative APIs too:
+ * queryClient.query(todosOptions).catch(noop)
+ * queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefined
  * ```
  */
 export function queryOptions<
diff --git a/packages/preact-query/src/useInfiniteQuery.ts b/packages/preact-query/src/useInfiniteQuery.ts
index 47848f9cca..92e7e4acbc 100644
--- a/packages/preact-query/src/useInfiniteQuery.ts
+++ b/packages/preact-query/src/useInfiniteQuery.ts
@@ -207,6 +207,50 @@ export function useInfiniteQuery<
  *   )
  * }
  * ```
+ *
+ * @example
+ * Warming the cache on hover, so `<Comments>` has data as soon as it's clicked. Requires an
+ * {@link infiniteQueryOptions} factory, so the hook and the imperative call share the same cache entry:
+ * ```tsx
+ * import {
+ *   infiniteQueryOptions,
+ *   noop,
+ *   useInfiniteQuery,
+ *   useQueryClient,
+ * } from '@tanstack/preact-query'
+ *
+ * const commentsOptions = (postId: string) =>
+ *   infiniteQueryOptions({
+ *     queryKey: ['post', postId, 'comments'],
+ *     queryFn: ({ pageParam }) => fetchComments(postId, pageParam),
+ *     initialPageParam: 0,
+ *     getNextPageParam: (lastPage) => lastPage.nextId,
+ *   })
+ *
+ * function Comments({ postId }: { postId: string }) {
+ *   const { data, isPending, isError, error } = useInfiniteQuery(commentsOptions(postId))
+ *   if (isPending) return 'Loading...'
+ *   if (isError) return <span>Error: {error.message}</span>
+ *   return (
+ *     <ul>
+ *       {data.pages.map((page) => page.comments.map((c) => <li key={c.id}>{c.text}</li>))}
+ *     </ul>
+ *   )
+ * }
+ *
+ * function PostLink({ postId, title }: { postId: string; title: string }) {
+ *   const queryClient = useQueryClient()
+ *
+ *   return (
+ *     <a
+ *       href={`/posts/${postId}`}
+ *       onMouseEnter={() => queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)}
+ *     >
+ *       {title}
+ *     </a>
+ *   )
+ * }
+ * ```
  */
 export function useInfiniteQuery<
   TQueryFnData,
diff --git a/packages/preact-query/src/useQuery.ts b/packages/preact-query/src/useQuery.ts
index 0f417095aa..ce035e9e5d 100644
--- a/packages/preact-query/src/useQuery.ts
+++ b/packages/preact-query/src/useQuery.ts
@@ -217,6 +217,37 @@ export function useQuery<
  *   )
  * }
  * ```
+ *
+ * @example
+ * Warming the cache on hover, so `<Post>` has data as soon as it's clicked. Requires a
+ * {@link queryOptions} factory, so the hook and the imperative call share the same cache entry:
+ * ```tsx
+ * import { noop, queryOptions, useQuery, useQueryClient } from '@tanstack/preact-query'
+ *
+ * const postOptions = (id: string) =>
+ *   queryOptions({
+ *     queryKey: ['post', id],
+ *     queryFn: () => fetchPost(id),
+ *   })
+ *
+ * function Post({ id }: { id: string }) {
+ *   const { data } = useQuery(postOptions(id))
+ *   return <h1>{data?.title}</h1>
+ * }
+ *
+ * function PostLink({ id, title }: { id: string; title: string }) {
+ *   const queryClient = useQueryClient()
+ *
+ *   return (
+ *     <a
+ *       href={`/posts/${id}`}
+ *       onMouseEnter={() => queryClient.query(postOptions(id)).catch(noop)}
+ *     >
+ *       {title}
+ *     </a>
+ *   )
+ * }
+ * ```
  */
 export function useQuery<
   TQueryFnData = unknown,

From 50f74369bb06a2e53b7a3a3c3000530430ab3f7c Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Sat, 29 Aug 2026 11:14:06 +0900
Subject: [PATCH 17/30] docs(preact-query): render list examples as
 '<ul>'/'<li>' and fix undefined refs across remaining hooks

---
 .../functions/infiniteQueryOptions.md         |  4 +-
 .../reference/functions/queryOptions.md       | 40 ++++++++++++++-----
 .../reference/functions/useInfiniteQuery.md   | 12 ++++--
 .../preact/reference/functions/useQuery.md    | 38 ++++++++++++------
 .../functions/useSuspenseInfiniteQuery.md     | 10 +++--
 .../reference/functions/useSuspenseQuery.md   | 12 +++---
 .../preact-query/src/infiniteQueryOptions.ts  |  4 +-
 packages/preact-query/src/queryOptions.ts     | 34 ++++++++++++----
 packages/preact-query/src/useInfiniteQuery.ts |  6 ++-
 packages/preact-query/src/useQuery.ts         | 32 ++++++++++-----
 .../src/useSuspenseInfiniteQuery.ts           |  8 ++--
 packages/preact-query/src/useSuspenseQuery.ts | 10 +++--
 12 files changed, 147 insertions(+), 63 deletions(-)

diff --git a/docs/framework/preact/reference/functions/infiniteQueryOptions.md b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
index af839473ab..0bf75108c8 100644
--- a/docs/framework/preact/reference/functions/infiniteQueryOptions.md
+++ b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
@@ -175,7 +175,7 @@ function Comments({ postId }: { postId: string }) {
 
 // `commentsOptions` also works with imperative APIs like `queryClient.infiniteQuery` —
 // see `useInfiniteQuery` for an example that warms the cache this way before rendering `<Comments>`.
-queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
+queryClient.infiniteQuery(commentsOptions('123')).catch(noop)
 ```
 
 ### See
@@ -279,7 +279,7 @@ function Comments({ postId }: { postId: string }) {
 
 // `commentsOptions` also works with imperative APIs like `queryClient.infiniteQuery` —
 // see `useInfiniteQuery` for an example that warms the cache this way before rendering `<Comments>`.
-queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
+queryClient.infiniteQuery(commentsOptions('123')).catch(noop)
 ```
 
 ### See
diff --git a/docs/framework/preact/reference/functions/queryOptions.md b/docs/framework/preact/reference/functions/queryOptions.md
index e8cf70e228..f8d87eefe3 100644
--- a/docs/framework/preact/reference/functions/queryOptions.md
+++ b/docs/framework/preact/reference/functions/queryOptions.md
@@ -9,7 +9,7 @@ title: queryOptions
 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:131](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L131)
+Defined in: [preact-query/src/queryOptions.ts:135](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L135)
 
 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
@@ -65,7 +65,11 @@ export const postsOptions = queryOptions({
 function Posts() {
   // `data` is `Post[]`, never `undefined`, thanks to `initialData`.
   const { data } = useQuery(postsOptions)
-  return <>{data.map((post) => <p key={post.id}>{post.title}</p>)}</>
+  return (
+    <ul>
+      {data.map((post) => <li key={post.id}>{post.title}</li>)}
+    </ul>
+  )
 }
 ```
 
@@ -75,7 +79,7 @@ function Posts() {
 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:206](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L206)
+Defined in: [preact-query/src/queryOptions.ts:218](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L218)
 
 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
@@ -127,7 +131,11 @@ export const postsOptions = queryOptions({
 
 function Posts() {
   const { data } = useQuery(postsOptions)
-  return <>{data?.map((post) => <p key={post.id}>{post.title}</p>)}</>
+  return (
+    <ul>
+      {data?.map((post) => <li key={post.id}>{post.title}</li>)}
+    </ul>
+  )
 }
 ```
 
@@ -148,7 +156,7 @@ function Post({ id }: { id: string }) {
 
 // `postOptions` also works with imperative APIs like `queryClient.query` —
 // see `useQuery` for an example that warms the cache this way before rendering `<Post>`.
-queryClient.query(postOptions(id)).catch(noop)
+queryClient.query(postOptions('123')).catch(noop)
 ```
 
 The same options object works with every API that accepts query options:
@@ -162,7 +170,11 @@ const todosOptions = queryOptions({
 
 function Todos() {
   const { data } = useQuery(todosOptions)
-  return <>{data?.map((todo) => <p key={todo.id}>{todo.title}</p>)}</>
+  return (
+    <ul>
+      {data?.map((todo) => <li key={todo.id}>{todo.title}</li>)}
+    </ul>
+  )
 }
 
 // The same options object works with the imperative APIs too:
@@ -176,7 +188,7 @@ queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefi
 function queryOptions<TQueryFnData, TError, TData, TQueryKey>(options): UseQueryOptions<TQueryFnData, TError, TData, TQueryKey> & object & QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>;
 ```
 
-Defined in: [preact-query/src/queryOptions.ts:281](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L281)
+Defined in: [preact-query/src/queryOptions.ts:301](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L301)
 
 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
@@ -228,7 +240,11 @@ export const postsOptions = queryOptions({
 
 function Posts() {
   const { data } = useQuery(postsOptions)
-  return <>{data?.map((post) => <p key={post.id}>{post.title}</p>)}</>
+  return (
+    <ul>
+      {data?.map((post) => <li key={post.id}>{post.title}</li>)}
+    </ul>
+  )
 }
 ```
 
@@ -249,7 +265,7 @@ function Post({ id }: { id: string }) {
 
 // `postOptions` also works with imperative APIs like `queryClient.query` —
 // see `useQuery` for an example that warms the cache this way before rendering `<Post>`.
-queryClient.query(postOptions(id)).catch(noop)
+queryClient.query(postOptions('123')).catch(noop)
 ```
 
 The same options object works with every API that accepts query options:
@@ -263,7 +279,11 @@ const todosOptions = queryOptions({
 
 function Todos() {
   const { data } = useQuery(todosOptions)
-  return <>{data?.map((todo) => <p key={todo.id}>{todo.title}</p>)}</>
+  return (
+    <ul>
+      {data?.map((todo) => <li key={todo.id}>{todo.title}</li>)}
+    </ul>
+  )
 }
 
 // The same options object works with the imperative APIs too:
diff --git a/docs/framework/preact/reference/functions/useInfiniteQuery.md b/docs/framework/preact/reference/functions/useInfiniteQuery.md
index 623396fa78..6bee8c30f2 100644
--- a/docs/framework/preact/reference/functions/useInfiniteQuery.md
+++ b/docs/framework/preact/reference/functions/useInfiniteQuery.md
@@ -9,7 +9,7 @@ title: useInfiniteQuery
 function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): DefinedUseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useInfiniteQuery.ts:55](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L55)
+Defined in: [preact-query/src/useInfiniteQuery.ts:59](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L59)
 
 The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
 `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
@@ -85,7 +85,11 @@ function Projects() {
     initialData: { pages: [], pageParams: [] },
   })
 
-  return <>{data.pages.map((page) => page.projects.map((p) => <p key={p.id}>{p.name}</p>))}</>
+  return (
+    <ul>
+      {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
+    </ul>
+  )
 }
 ```
 
@@ -95,7 +99,7 @@ function Projects() {
 function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): UseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useInfiniteQuery.ts:133](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L133)
+Defined in: [preact-query/src/useInfiniteQuery.ts:137](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L137)
 
 The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
 `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
@@ -208,7 +212,7 @@ function Projects() {
 function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): UseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useInfiniteQuery.ts:255](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L255)
+Defined in: [preact-query/src/useInfiniteQuery.ts:259](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L259)
 
 The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
 `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
diff --git a/docs/framework/preact/reference/functions/useQuery.md b/docs/framework/preact/reference/functions/useQuery.md
index 126d9488c8..28bccddb50 100644
--- a/docs/framework/preact/reference/functions/useQuery.md
+++ b/docs/framework/preact/reference/functions/useQuery.md
@@ -9,7 +9,7 @@ title: useQuery
 function useQuery<TQueryFnData, TError, TData, TQueryKey>(options, queryClient?): DefinedUseQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useQuery.ts:42](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L42)
+Defined in: [preact-query/src/useQuery.ts:46](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L46)
 
 This overload is selected when `initialData` is set, so the resulting `data` is never `undefined`.
 
@@ -71,7 +71,11 @@ function Posts() {
     initialData: [],
   })
 
-  return <>{data.map((post) => <p key={post.id}>{post.title}</p>)}</>
+  return (
+    <ul>
+      {data.map((post) => <li key={post.id}>{post.title}</li>)}
+    </ul>
+  )
 }
 ```
 
@@ -81,7 +85,7 @@ function Posts() {
 function useQuery<TQueryFnData, TError, TData, TQueryKey>(options, queryClient?): UseQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useQuery.ts:105](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L105)
+Defined in: [preact-query/src/useQuery.ts:115](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L115)
 
 ### Type Parameters
 
@@ -146,9 +150,11 @@ function Posts() {
 
   return (
     <div>
-      {data.map((post) => (
-        <p key={post.id}>{post.title}</p>
-      ))}
+      <ul>
+        {data.map((post) => (
+          <li key={post.id}>{post.title}</li>
+        ))}
+      </ul>
       <div>{isFetching ? 'Background Updating...' : ' '}</div>
     </div>
   )
@@ -168,7 +174,11 @@ function Posts() {
   if (isPending) return 'Loading...'
   if (isError) return <span>Error: {error.message}</span>
 
-  return <>{data.map((post) => <p key={post.id}>{post.title}</p>)}</>
+  return (
+    <ul>
+      {data.map((post) => <li key={post.id}>{post.title}</li>)}
+    </ul>
+  )
 }
 ```
 
@@ -178,7 +188,7 @@ function Posts() {
 function useQuery<TQueryFnData, TError, TData, TQueryKey>(options, queryClient?): UseQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useQuery.ts:252](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L252)
+Defined in: [preact-query/src/useQuery.ts:266](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L266)
 
 ### Type Parameters
 
@@ -243,9 +253,11 @@ function Posts() {
 
   return (
     <div>
-      {data.map((post) => (
-        <p key={post.id}>{post.title}</p>
-      ))}
+      <ul>
+        {data.map((post) => (
+          <li key={post.id}>{post.title}</li>
+        ))}
+      </ul>
       <div>{isFetching ? 'Background Updating...' : ' '}</div>
     </div>
   )
@@ -308,7 +320,9 @@ function Posts() {
 
   return (
     <div>
-      {data?.map((post) => <p key={post.id}>{post.title}</p>)}
+      <ul>
+        {data?.map((post) => <li key={post.id}>{post.title}</li>)}
+      </ul>
       <button
         disabled={isPlaceholderData}
         onClick={() => setPage((old) => old + 1)}
diff --git a/docs/framework/preact/reference/functions/useSuspenseInfiniteQuery.md b/docs/framework/preact/reference/functions/useSuspenseInfiniteQuery.md
index be6b299df0..571dc5b14d 100644
--- a/docs/framework/preact/reference/functions/useSuspenseInfiniteQuery.md
+++ b/docs/framework/preact/reference/functions/useSuspenseInfiniteQuery.md
@@ -7,7 +7,7 @@ title: useSuspenseInfiniteQuery
 function useSuspenseInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): UseSuspenseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useSuspenseInfiniteQuery.ts:74](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseInfiniteQuery.ts#L74)
+Defined in: [preact-query/src/useSuspenseInfiniteQuery.ts:76](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseInfiniteQuery.ts#L76)
 
 The options for `useSuspenseInfiniteQuery` are the same as for `useInfiniteQuery`, except for `throwOnError`,
 `enabled`, and `placeholderData`.
@@ -77,9 +77,11 @@ function Projects() {
 
   return (
     <div>
-      {data.pages.map((page) =>
-        page.projects.map((project) => <p key={project.id}>{project.name}</p>),
-      )}
+      <ul>
+        {data.pages.map((page) =>
+          page.projects.map((project) => <li key={project.id}>{project.name}</li>),
+        )}
+      </ul>
       <button
         onClick={() => fetchNextPage()}
         disabled={!hasNextPage || isFetching}
diff --git a/docs/framework/preact/reference/functions/useSuspenseQuery.md b/docs/framework/preact/reference/functions/useSuspenseQuery.md
index 44a4a503a8..d37614138f 100644
--- a/docs/framework/preact/reference/functions/useSuspenseQuery.md
+++ b/docs/framework/preact/reference/functions/useSuspenseQuery.md
@@ -7,7 +7,7 @@ title: useSuspenseQuery
 function useSuspenseQuery<TQueryFnData, TError, TData, TQueryKey>(options, queryClient?): UseSuspenseQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useSuspenseQuery.ts:55](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseQuery.ts#L55)
+Defined in: [preact-query/src/useSuspenseQuery.ts:57](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseQuery.ts#L57)
 
 The options for `useSuspenseQuery` are the same as for `useQuery`, except for `throwOnError`, `enabled`, and
 `placeholderData`.
@@ -76,10 +76,12 @@ function Posts() {
 
   return (
     <div>
-      <h1>Posts {isFetching ? <Spinner /> : null}</h1>
-      {data.map((post) => (
-        <p key={post.id}>{post.title}</p>
-      ))}
+      <h1>Posts {isFetching ? '(refreshing...)' : null}</h1>
+      <ul>
+        {data.map((post) => (
+          <li key={post.id}>{post.title}</li>
+        ))}
+      </ul>
     </div>
   )
 }
diff --git a/packages/preact-query/src/infiniteQueryOptions.ts b/packages/preact-query/src/infiniteQueryOptions.ts
index 673271c525..982c64d208 100644
--- a/packages/preact-query/src/infiniteQueryOptions.ts
+++ b/packages/preact-query/src/infiniteQueryOptions.ts
@@ -239,7 +239,7 @@ export function infiniteQueryOptions<
  *
  * // `commentsOptions` also works with imperative APIs like `queryClient.infiniteQuery` —
  * // see `useInfiniteQuery` for an example that warms the cache this way before rendering `<Comments>`.
- * queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
+ * queryClient.infiniteQuery(commentsOptions('123')).catch(noop)
  * ```
  *
  * @see {@link useInfiniteQuery} to run an infinite query with these options.
@@ -326,7 +326,7 @@ export function infiniteQueryOptions<
  *
  * // `commentsOptions` also works with imperative APIs like `queryClient.infiniteQuery` —
  * // see `useInfiniteQuery` for an example that warms the cache this way before rendering `<Comments>`.
- * queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
+ * queryClient.infiniteQuery(commentsOptions('123')).catch(noop)
  * ```
  *
  * @see {@link useInfiniteQuery} to run an infinite query with these options.
diff --git a/packages/preact-query/src/queryOptions.ts b/packages/preact-query/src/queryOptions.ts
index e5331c8d0a..10de493ea4 100644
--- a/packages/preact-query/src/queryOptions.ts
+++ b/packages/preact-query/src/queryOptions.ts
@@ -124,7 +124,11 @@ export type DefinedInitialDataOptions<
  * function Posts() {
  *   // `data` is `Post[]`, never `undefined`, thanks to `initialData`.
  *   const { data } = useQuery(postsOptions)
- *   return <>{data.map((post) => <p key={post.id}>{post.title}</p>)}</>
+ *   return (
+ *     <ul>
+ *       {data.map((post) => <li key={post.id}>{post.title}</li>)}
+ *     </ul>
+ *   )
  * }
  * ```
  */
@@ -158,7 +162,11 @@ export function queryOptions<
  *
  * function Posts() {
  *   const { data } = useQuery(postsOptions)
- *   return <>{data?.map((post) => <p key={post.id}>{post.title}</p>)}</>
+ *   return (
+ *     <ul>
+ *       {data?.map((post) => <li key={post.id}>{post.title}</li>)}
+ *     </ul>
+ *   )
  * }
  * ```
  *
@@ -180,7 +188,7 @@ export function queryOptions<
  *
  * // `postOptions` also works with imperative APIs like `queryClient.query` —
  * // see `useQuery` for an example that warms the cache this way before rendering `<Post>`.
- * queryClient.query(postOptions(id)).catch(noop)
+ * queryClient.query(postOptions('123')).catch(noop)
  * ```
  *
  * @example
@@ -195,7 +203,11 @@ export function queryOptions<
  *
  * function Todos() {
  *   const { data } = useQuery(todosOptions)
- *   return <>{data?.map((todo) => <p key={todo.id}>{todo.title}</p>)}</>
+ *   return (
+ *     <ul>
+ *       {data?.map((todo) => <li key={todo.id}>{todo.title}</li>)}
+ *     </ul>
+ *   )
  * }
  *
  * // The same options object works with the imperative APIs too:
@@ -233,7 +245,11 @@ export function queryOptions<
  *
  * function Posts() {
  *   const { data } = useQuery(postsOptions)
- *   return <>{data?.map((post) => <p key={post.id}>{post.title}</p>)}</>
+ *   return (
+ *     <ul>
+ *       {data?.map((post) => <li key={post.id}>{post.title}</li>)}
+ *     </ul>
+ *   )
  * }
  * ```
  *
@@ -255,7 +271,7 @@ export function queryOptions<
  *
  * // `postOptions` also works with imperative APIs like `queryClient.query` —
  * // see `useQuery` for an example that warms the cache this way before rendering `<Post>`.
- * queryClient.query(postOptions(id)).catch(noop)
+ * queryClient.query(postOptions('123')).catch(noop)
  * ```
  *
  * @example
@@ -270,7 +286,11 @@ export function queryOptions<
  *
  * function Todos() {
  *   const { data } = useQuery(todosOptions)
- *   return <>{data?.map((todo) => <p key={todo.id}>{todo.title}</p>)}</>
+ *   return (
+ *     <ul>
+ *       {data?.map((todo) => <li key={todo.id}>{todo.title}</li>)}
+ *     </ul>
+ *   )
  * }
  *
  * // The same options object works with the imperative APIs too:
diff --git a/packages/preact-query/src/useInfiniteQuery.ts b/packages/preact-query/src/useInfiniteQuery.ts
index 92e7e4acbc..e206246167 100644
--- a/packages/preact-query/src/useInfiniteQuery.ts
+++ b/packages/preact-query/src/useInfiniteQuery.ts
@@ -48,7 +48,11 @@ import { useBaseQuery } from './useBaseQuery'
  *     initialData: { pages: [], pageParams: [] },
  *   })
  *
- *   return <>{data.pages.map((page) => page.projects.map((p) => <p key={p.id}>{p.name}</p>))}</>
+ *   return (
+ *     <ul>
+ *       {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
+ *     </ul>
+ *   )
  * }
  * ```
  */
diff --git a/packages/preact-query/src/useQuery.ts b/packages/preact-query/src/useQuery.ts
index ce035e9e5d..c1fb847657 100644
--- a/packages/preact-query/src/useQuery.ts
+++ b/packages/preact-query/src/useQuery.ts
@@ -35,7 +35,11 @@ import { useBaseQuery } from './useBaseQuery'
  *     initialData: [],
  *   })
  *
- *   return <>{data.map((post) => <p key={post.id}>{post.title}</p>)}</>
+ *   return (
+ *     <ul>
+ *       {data.map((post) => <li key={post.id}>{post.title}</li>)}
+ *     </ul>
+ *   )
  * }
  * ```
  */
@@ -75,9 +79,11 @@ export function useQuery<
  *
  *   return (
  *     <div>
- *       {data.map((post) => (
- *         <p key={post.id}>{post.title}</p>
- *       ))}
+ *       <ul>
+ *         {data.map((post) => (
+ *           <li key={post.id}>{post.title}</li>
+ *         ))}
+ *       </ul>
  *       <div>{isFetching ? 'Background Updating...' : ' '}</div>
  *     </div>
  *   )
@@ -98,7 +104,11 @@ export function useQuery<
  *   if (isPending) return 'Loading...'
  *   if (isError) return <span>Error: {error.message}</span>
  *
- *   return <>{data.map((post) => <p key={post.id}>{post.title}</p>)}</>
+ *   return (
+ *     <ul>
+ *       {data.map((post) => <li key={post.id}>{post.title}</li>)}
+ *     </ul>
+ *   )
  * }
  * ```
  */
@@ -138,9 +148,11 @@ export function useQuery<
  *
  *   return (
  *     <div>
- *       {data.map((post) => (
- *         <p key={post.id}>{post.title}</p>
- *       ))}
+ *       <ul>
+ *         {data.map((post) => (
+ *           <li key={post.id}>{post.title}</li>
+ *         ))}
+ *       </ul>
  *       <div>{isFetching ? 'Background Updating...' : ' '}</div>
  *     </div>
  *   )
@@ -206,7 +218,9 @@ export function useQuery<
  *
  *   return (
  *     <div>
- *       {data?.map((post) => <p key={post.id}>{post.title}</p>)}
+ *       <ul>
+ *         {data?.map((post) => <li key={post.id}>{post.title}</li>)}
+ *       </ul>
  *       <button
  *         disabled={isPlaceholderData}
  *         onClick={() => setPage((old) => old + 1)}
diff --git a/packages/preact-query/src/useSuspenseInfiniteQuery.ts b/packages/preact-query/src/useSuspenseInfiniteQuery.ts
index 89def87ac4..8e193936d3 100644
--- a/packages/preact-query/src/useSuspenseInfiniteQuery.ts
+++ b/packages/preact-query/src/useSuspenseInfiniteQuery.ts
@@ -45,9 +45,11 @@ import { useBaseQuery } from './useBaseQuery'
  *
  *   return (
  *     <div>
- *       {data.pages.map((page) =>
- *         page.projects.map((project) => <p key={project.id}>{project.name}</p>),
- *       )}
+ *       <ul>
+ *         {data.pages.map((page) =>
+ *           page.projects.map((project) => <li key={project.id}>{project.name}</li>),
+ *         )}
+ *       </ul>
  *       <button
  *         onClick={() => fetchNextPage()}
  *         disabled={!hasNextPage || isFetching}
diff --git a/packages/preact-query/src/useSuspenseQuery.ts b/packages/preact-query/src/useSuspenseQuery.ts
index 806268a1dc..711807dfa4 100644
--- a/packages/preact-query/src/useSuspenseQuery.ts
+++ b/packages/preact-query/src/useSuspenseQuery.ts
@@ -35,10 +35,12 @@ import { useBaseQuery } from './useBaseQuery'
  *
  *   return (
  *     <div>
- *       <h1>Posts {isFetching ? <Spinner /> : null}</h1>
- *       {data.map((post) => (
- *         <p key={post.id}>{post.title}</p>
- *       ))}
+ *       <h1>Posts {isFetching ? '(refreshing...)' : null}</h1>
+ *       <ul>
+ *         {data.map((post) => (
+ *           <li key={post.id}>{post.title}</li>
+ *         ))}
+ *       </ul>
  *     </div>
  *   )
  * }

From cef13e7d838822941bde767693199c44a55247bf Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Sat, 29 Aug 2026 11:21:18 +0900
Subject: [PATCH 18/30] docs(preact-query): name the prefetch id in
 'queryOptions'/'infiniteQueryOptions' examples instead of an unexplained
 literal

---
 .../preact/reference/functions/infiniteQueryOptions.md | 10 ++++++----
 .../preact/reference/functions/queryOptions.md         | 10 ++++++----
 packages/preact-query/src/infiniteQueryOptions.ts      |  6 ++++--
 packages/preact-query/src/queryOptions.ts              |  6 ++++--
 4 files changed, 20 insertions(+), 12 deletions(-)

diff --git a/docs/framework/preact/reference/functions/infiniteQueryOptions.md b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
index 0bf75108c8..2008518618 100644
--- a/docs/framework/preact/reference/functions/infiniteQueryOptions.md
+++ b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
@@ -84,7 +84,7 @@ function Projects() {
 function infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options): OmitKeyof<UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, "queryFn"> & object & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData, unknown>, TError>;
 ```
 
-Defined in: [preact-query/src/infiniteQueryOptions.ts:248](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L248)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:249](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L249)
 
 You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
 These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
@@ -175,7 +175,8 @@ function Comments({ postId }: { postId: string }) {
 
 // `commentsOptions` also works with imperative APIs like `queryClient.infiniteQuery` —
 // see `useInfiniteQuery` for an example that warms the cache this way before rendering `<Comments>`.
-queryClient.infiniteQuery(commentsOptions('123')).catch(noop)
+const postId = '1'
+queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
 ```
 
 ### See
@@ -188,7 +189,7 @@ queryClient.infiniteQuery(commentsOptions('123')).catch(noop)
 function infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options): UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & object & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData, unknown>, TError>;
 ```
 
-Defined in: [preact-query/src/infiniteQueryOptions.ts:335](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L335)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:337](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L337)
 
 You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
 These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
@@ -279,7 +280,8 @@ function Comments({ postId }: { postId: string }) {
 
 // `commentsOptions` also works with imperative APIs like `queryClient.infiniteQuery` —
 // see `useInfiniteQuery` for an example that warms the cache this way before rendering `<Comments>`.
-queryClient.infiniteQuery(commentsOptions('123')).catch(noop)
+const postId = '1'
+queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
 ```
 
 ### See
diff --git a/docs/framework/preact/reference/functions/queryOptions.md b/docs/framework/preact/reference/functions/queryOptions.md
index f8d87eefe3..8f4a6c8df1 100644
--- a/docs/framework/preact/reference/functions/queryOptions.md
+++ b/docs/framework/preact/reference/functions/queryOptions.md
@@ -79,7 +79,7 @@ function Posts() {
 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:218](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L218)
+Defined in: [preact-query/src/queryOptions.ts:219](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L219)
 
 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
@@ -156,7 +156,8 @@ function Post({ id }: { id: string }) {
 
 // `postOptions` also works with imperative APIs like `queryClient.query` —
 // see `useQuery` for an example that warms the cache this way before rendering `<Post>`.
-queryClient.query(postOptions('123')).catch(noop)
+const postId = '1'
+queryClient.query(postOptions(postId)).catch(noop)
 ```
 
 The same options object works with every API that accepts query options:
@@ -188,7 +189,7 @@ queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefi
 function queryOptions<TQueryFnData, TError, TData, TQueryKey>(options): UseQueryOptions<TQueryFnData, TError, TData, TQueryKey> & object & QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>;
 ```
 
-Defined in: [preact-query/src/queryOptions.ts:301](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L301)
+Defined in: [preact-query/src/queryOptions.ts:303](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L303)
 
 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
@@ -265,7 +266,8 @@ function Post({ id }: { id: string }) {
 
 // `postOptions` also works with imperative APIs like `queryClient.query` —
 // see `useQuery` for an example that warms the cache this way before rendering `<Post>`.
-queryClient.query(postOptions('123')).catch(noop)
+const postId = '1'
+queryClient.query(postOptions(postId)).catch(noop)
 ```
 
 The same options object works with every API that accepts query options:
diff --git a/packages/preact-query/src/infiniteQueryOptions.ts b/packages/preact-query/src/infiniteQueryOptions.ts
index 982c64d208..8766b60d33 100644
--- a/packages/preact-query/src/infiniteQueryOptions.ts
+++ b/packages/preact-query/src/infiniteQueryOptions.ts
@@ -239,7 +239,8 @@ export function infiniteQueryOptions<
  *
  * // `commentsOptions` also works with imperative APIs like `queryClient.infiniteQuery` —
  * // see `useInfiniteQuery` for an example that warms the cache this way before rendering `<Comments>`.
- * queryClient.infiniteQuery(commentsOptions('123')).catch(noop)
+ * const postId = '1'
+ * queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
  * ```
  *
  * @see {@link useInfiniteQuery} to run an infinite query with these options.
@@ -326,7 +327,8 @@ export function infiniteQueryOptions<
  *
  * // `commentsOptions` also works with imperative APIs like `queryClient.infiniteQuery` —
  * // see `useInfiniteQuery` for an example that warms the cache this way before rendering `<Comments>`.
- * queryClient.infiniteQuery(commentsOptions('123')).catch(noop)
+ * const postId = '1'
+ * queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
  * ```
  *
  * @see {@link useInfiniteQuery} to run an infinite query with these options.
diff --git a/packages/preact-query/src/queryOptions.ts b/packages/preact-query/src/queryOptions.ts
index 10de493ea4..68454473d8 100644
--- a/packages/preact-query/src/queryOptions.ts
+++ b/packages/preact-query/src/queryOptions.ts
@@ -188,7 +188,8 @@ export function queryOptions<
  *
  * // `postOptions` also works with imperative APIs like `queryClient.query` —
  * // see `useQuery` for an example that warms the cache this way before rendering `<Post>`.
- * queryClient.query(postOptions('123')).catch(noop)
+ * const postId = '1'
+ * queryClient.query(postOptions(postId)).catch(noop)
  * ```
  *
  * @example
@@ -271,7 +272,8 @@ export function queryOptions<
  *
  * // `postOptions` also works with imperative APIs like `queryClient.query` —
  * // see `useQuery` for an example that warms the cache this way before rendering `<Post>`.
- * queryClient.query(postOptions('123')).catch(noop)
+ * const postId = '1'
+ * queryClient.query(postOptions(postId)).catch(noop)
  * ```
  *
  * @example

From 5e1eb15b6c4c4b2d0a5672293ebf2bd5a8335211 Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Sat, 29 Aug 2026 11:42:54 +0900
Subject: [PATCH 19/30] docs(preact-query): add 'skipToken' examples for
 type-safe conditional disabling

---
 .../functions/infiniteQueryOptions.md         | 36 ++++++++++++++++++-
 .../reference/functions/queryOptions.md       | 22 +++++++++++-
 .../reference/functions/useInfiniteQuery.md   | 30 +++++++++++++++-
 .../preact/reference/functions/useQuery.md    | 23 +++++++++++-
 .../preact-query/src/infiniteQueryOptions.ts  | 35 ++++++++++++++++++
 packages/preact-query/src/queryOptions.ts     | 21 +++++++++++
 packages/preact-query/src/useInfiniteQuery.ts | 29 +++++++++++++++
 packages/preact-query/src/useQuery.ts         | 22 ++++++++++++
 8 files changed, 214 insertions(+), 4 deletions(-)

diff --git a/docs/framework/preact/reference/functions/infiniteQueryOptions.md b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
index 2008518618..241d600645 100644
--- a/docs/framework/preact/reference/functions/infiniteQueryOptions.md
+++ b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
@@ -189,7 +189,7 @@ queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
 function infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options): UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & object & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData, unknown>, TError>;
 ```
 
-Defined in: [preact-query/src/infiniteQueryOptions.ts:337](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L337)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:372](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L372)
 
 You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
 These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
@@ -284,6 +284,40 @@ const postId = '1'
 queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
 ```
 
+A factory that disables the query, type safe, until `postId` is set:
+```tsx
+import {
+  infiniteQueryOptions,
+  skipToken,
+  useInfiniteQuery,
+} from '@tanstack/preact-query'
+
+export const commentsOptions = (postId: string | undefined) =>
+  infiniteQueryOptions({
+    queryKey: ['post', postId, 'comments'],
+    queryFn:
+      postId != null
+        ? ({ pageParam }) => fetchComments(postId, pageParam)
+        : skipToken,
+    initialPageParam: 0,
+    getNextPageParam: (lastPage) => lastPage.nextId,
+  })
+
+function Comments({ postId }: { postId: string | undefined }) {
+  const { data, isPending, isError, error } = useInfiniteQuery(commentsOptions(postId))
+
+  if (postId == null) return 'Select a post'
+  if (isPending) return 'Loading...'
+  if (isError) return <span>Error: {error.message}</span>
+
+  return (
+    <ul>
+      {data.pages.map((page) => page.comments.map((c) => <li key={c.id}>{c.text}</li>))}
+    </ul>
+  )
+}
+```
+
 ### See
 
 [useInfiniteQuery](useInfiniteQuery.md) to run an infinite query with these options.
diff --git a/docs/framework/preact/reference/functions/queryOptions.md b/docs/framework/preact/reference/functions/queryOptions.md
index 8f4a6c8df1..4af286b8bb 100644
--- a/docs/framework/preact/reference/functions/queryOptions.md
+++ b/docs/framework/preact/reference/functions/queryOptions.md
@@ -189,7 +189,7 @@ queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefi
 function queryOptions<TQueryFnData, TError, TData, TQueryKey>(options): UseQueryOptions<TQueryFnData, TError, TData, TQueryKey> & object & QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>;
 ```
 
-Defined in: [preact-query/src/queryOptions.ts:303](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L303)
+Defined in: [preact-query/src/queryOptions.ts:324](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L324)
 
 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
@@ -292,3 +292,23 @@ function Todos() {
 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 } = useQuery(postOptions(postId))
+
+  if (postId == null) return 'Select a post'
+  if (isLoading) return 'Loading...'
+
+  return <h1>{data?.title}</h1>
+}
+```
diff --git a/docs/framework/preact/reference/functions/useInfiniteQuery.md b/docs/framework/preact/reference/functions/useInfiniteQuery.md
index 6bee8c30f2..071497a33d 100644
--- a/docs/framework/preact/reference/functions/useInfiniteQuery.md
+++ b/docs/framework/preact/reference/functions/useInfiniteQuery.md
@@ -212,7 +212,7 @@ function Projects() {
 function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): UseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useInfiniteQuery.ts:259](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L259)
+Defined in: [preact-query/src/useInfiniteQuery.ts:288](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L288)
 
 The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
 `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
@@ -361,3 +361,31 @@ function PostLink({ postId, title }: { postId: string; title: string }) {
   )
 }
 ```
+
+A query that's disabled, type safe, until `postId` is set — pass `skipToken` as `queryFn`
+instead of setting `enabled: false`:
+```tsx
+import { skipToken, useInfiniteQuery } from '@tanstack/preact-query'
+
+function Comments({ postId }: { postId: string | undefined }) {
+  const { data, isPending, isError, error } = useInfiniteQuery({
+    queryKey: ['post', postId, 'comments'],
+    queryFn:
+      postId != null
+        ? ({ pageParam }) => fetchComments(postId, pageParam)
+        : skipToken,
+    initialPageParam: 0,
+    getNextPageParam: (lastPage) => lastPage.nextId,
+  })
+
+  if (postId == null) return 'Select a post'
+  if (isPending) return 'Loading...'
+  if (isError) return <span>Error: {error.message}</span>
+
+  return (
+    <ul>
+      {data.pages.map((page) => page.comments.map((c) => <li key={c.id}>{c.text}</li>))}
+    </ul>
+  )
+}
+```
diff --git a/docs/framework/preact/reference/functions/useQuery.md b/docs/framework/preact/reference/functions/useQuery.md
index 28bccddb50..2652e6664d 100644
--- a/docs/framework/preact/reference/functions/useQuery.md
+++ b/docs/framework/preact/reference/functions/useQuery.md
@@ -188,7 +188,7 @@ function Posts() {
 function useQuery<TQueryFnData, TError, TData, TQueryKey>(options, queryClient?): UseQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useQuery.ts:266](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L266)
+Defined in: [preact-query/src/useQuery.ts:288](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L288)
 
 ### Type Parameters
 
@@ -284,6 +284,27 @@ function Post({ postId }: { postId: number | undefined }) {
 }
 ```
 
+The same dependent query, type safe: `skipToken` disables the query without needing the
+non-null assertion above, since `queryFn` is only ever called when `postId` is defined.
+`refetch` doesn't work while `queryFn` is `skipToken` — use `enabled: false` instead if you
+need to trigger the query manually:
+```tsx
+import { skipToken, useQuery } from '@tanstack/preact-query'
+
+function Post({ postId }: { postId: number | undefined }) {
+  const { data, isLoading, isError, error } = useQuery({
+    queryKey: ['post', postId],
+    queryFn: postId != null ? () => fetchPost(postId) : skipToken,
+  })
+
+  if (postId == null) return 'Select a post'
+  if (isLoading) return 'Loading...'
+  if (isError) return <span>Error: {error.message}</span>
+
+  return <h1>{data?.title}</h1>
+}
+```
+
 Seeding a detail query from an already-cached list, to skip the loading state:
 ```tsx
 import { useQuery, useQueryClient } from '@tanstack/preact-query'
diff --git a/packages/preact-query/src/infiniteQueryOptions.ts b/packages/preact-query/src/infiniteQueryOptions.ts
index 8766b60d33..72070b45c6 100644
--- a/packages/preact-query/src/infiniteQueryOptions.ts
+++ b/packages/preact-query/src/infiniteQueryOptions.ts
@@ -331,6 +331,41 @@ export function infiniteQueryOptions<
  * queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
  * ```
  *
+ * @example
+ * A factory that disables the query, type safe, until `postId` is set:
+ * ```tsx
+ * import {
+ *   infiniteQueryOptions,
+ *   skipToken,
+ *   useInfiniteQuery,
+ * } from '@tanstack/preact-query'
+ *
+ * export const commentsOptions = (postId: string | undefined) =>
+ *   infiniteQueryOptions({
+ *     queryKey: ['post', postId, 'comments'],
+ *     queryFn:
+ *       postId != null
+ *         ? ({ pageParam }) => fetchComments(postId, pageParam)
+ *         : skipToken,
+ *     initialPageParam: 0,
+ *     getNextPageParam: (lastPage) => lastPage.nextId,
+ *   })
+ *
+ * function Comments({ postId }: { postId: string | undefined }) {
+ *   const { data, isPending, isError, error } = useInfiniteQuery(commentsOptions(postId))
+ *
+ *   if (postId == null) return 'Select a post'
+ *   if (isPending) return 'Loading...'
+ *   if (isError) return <span>Error: {error.message}</span>
+ *
+ *   return (
+ *     <ul>
+ *       {data.pages.map((page) => page.comments.map((c) => <li key={c.id}>{c.text}</li>))}
+ *     </ul>
+ *   )
+ * }
+ * ```
+ *
  * @see {@link useInfiniteQuery} to run an infinite query with these options.
  * @param options - The {@link UndefinedInitialDataInfiniteOptions} to use — everything you can pass to `useInfiniteQuery`.
  */
diff --git a/packages/preact-query/src/queryOptions.ts b/packages/preact-query/src/queryOptions.ts
index 68454473d8..90f3d00c20 100644
--- a/packages/preact-query/src/queryOptions.ts
+++ b/packages/preact-query/src/queryOptions.ts
@@ -299,6 +299,27 @@ export function queryOptions<
  * queryClient.query(todosOptions).catch(noop)
  * queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefined
  * ```
+ *
+ * @example
+ * 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 } = useQuery(postOptions(postId))
+ *
+ *   if (postId == null) return 'Select a post'
+ *   if (isLoading) return 'Loading...'
+ *
+ *   return <h1>{data?.title}</h1>
+ * }
+ * ```
  */
 export function queryOptions<
   TQueryFnData = unknown,
diff --git a/packages/preact-query/src/useInfiniteQuery.ts b/packages/preact-query/src/useInfiniteQuery.ts
index e206246167..b7305eea9e 100644
--- a/packages/preact-query/src/useInfiniteQuery.ts
+++ b/packages/preact-query/src/useInfiniteQuery.ts
@@ -255,6 +255,35 @@ export function useInfiniteQuery<
  *   )
  * }
  * ```
+ *
+ * @example
+ * A query that's disabled, type safe, until `postId` is set — pass `skipToken` as `queryFn`
+ * instead of setting `enabled: false`:
+ * ```tsx
+ * import { skipToken, useInfiniteQuery } from '@tanstack/preact-query'
+ *
+ * function Comments({ postId }: { postId: string | undefined }) {
+ *   const { data, isPending, isError, error } = useInfiniteQuery({
+ *     queryKey: ['post', postId, 'comments'],
+ *     queryFn:
+ *       postId != null
+ *         ? ({ pageParam }) => fetchComments(postId, pageParam)
+ *         : skipToken,
+ *     initialPageParam: 0,
+ *     getNextPageParam: (lastPage) => lastPage.nextId,
+ *   })
+ *
+ *   if (postId == null) return 'Select a post'
+ *   if (isPending) return 'Loading...'
+ *   if (isError) return <span>Error: {error.message}</span>
+ *
+ *   return (
+ *     <ul>
+ *       {data.pages.map((page) => page.comments.map((c) => <li key={c.id}>{c.text}</li>))}
+ *     </ul>
+ *   )
+ * }
+ * ```
  */
 export function useInfiniteQuery<
   TQueryFnData,
diff --git a/packages/preact-query/src/useQuery.ts b/packages/preact-query/src/useQuery.ts
index c1fb847657..8736ed9e5b 100644
--- a/packages/preact-query/src/useQuery.ts
+++ b/packages/preact-query/src/useQuery.ts
@@ -181,6 +181,28 @@ export function useQuery<
  * ```
  *
  * @example
+ * The same dependent query, type safe: `skipToken` disables the query without needing the
+ * non-null assertion above, since `queryFn` is only ever called when `postId` is defined.
+ * `refetch` doesn't work while `queryFn` is `skipToken` — use `enabled: false` instead if you
+ * need to trigger the query manually:
+ * ```tsx
+ * import { skipToken, useQuery } from '@tanstack/preact-query'
+ *
+ * function Post({ postId }: { postId: number | undefined }) {
+ *   const { data, isLoading, isError, error } = useQuery({
+ *     queryKey: ['post', postId],
+ *     queryFn: postId != null ? () => fetchPost(postId) : skipToken,
+ *   })
+ *
+ *   if (postId == null) return 'Select a post'
+ *   if (isLoading) return 'Loading...'
+ *   if (isError) return <span>Error: {error.message}</span>
+ *
+ *   return <h1>{data?.title}</h1>
+ * }
+ * ```
+ *
+ * @example
  * Seeding a detail query from an already-cached list, to skip the loading state:
  * ```tsx
  * import { useQuery, useQueryClient } from '@tanstack/preact-query'

From 286c85169f8a8c729b6b57896b9e666d337d4798 Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Sat, 29 Aug 2026 11:57:21 +0900
Subject: [PATCH 20/30] docs(preact-query): use 'isLoading' with optional
 chaining in the infinite-query 'skipToken' examples

---
 .../preact/reference/functions/infiniteQueryOptions.md   | 9 +++++----
 .../preact/reference/functions/useInfiniteQuery.md       | 9 +++++----
 packages/preact-query/src/infiniteQueryOptions.ts        | 7 ++++---
 packages/preact-query/src/useInfiniteQuery.ts            | 7 ++++---
 4 files changed, 18 insertions(+), 14 deletions(-)

diff --git a/docs/framework/preact/reference/functions/infiniteQueryOptions.md b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
index 241d600645..7e5eafa1a3 100644
--- a/docs/framework/preact/reference/functions/infiniteQueryOptions.md
+++ b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
@@ -189,7 +189,7 @@ queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
 function infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options): UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & object & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData, unknown>, TError>;
 ```
 
-Defined in: [preact-query/src/infiniteQueryOptions.ts:372](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L372)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:373](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L373)
 
 You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
 These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
@@ -304,15 +304,16 @@ export const commentsOptions = (postId: string | undefined) =>
   })
 
 function Comments({ postId }: { postId: string | undefined }) {
-  const { data, isPending, isError, error } = useInfiniteQuery(commentsOptions(postId))
+  // Use `isLoading`, not `isPending`, so the loading state doesn't show while the query is disabled.
+  const { data, isLoading, isError, error } = useInfiniteQuery(commentsOptions(postId))
 
   if (postId == null) return 'Select a post'
-  if (isPending) return 'Loading...'
+  if (isLoading) return 'Loading...'
   if (isError) return <span>Error: {error.message}</span>
 
   return (
     <ul>
-      {data.pages.map((page) => page.comments.map((c) => <li key={c.id}>{c.text}</li>))}
+      {data?.pages.map((page) => page.comments.map((c) => <li key={c.id}>{c.text}</li>))}
     </ul>
   )
 }
diff --git a/docs/framework/preact/reference/functions/useInfiniteQuery.md b/docs/framework/preact/reference/functions/useInfiniteQuery.md
index 071497a33d..8172194f93 100644
--- a/docs/framework/preact/reference/functions/useInfiniteQuery.md
+++ b/docs/framework/preact/reference/functions/useInfiniteQuery.md
@@ -212,7 +212,7 @@ function Projects() {
 function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): UseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useInfiniteQuery.ts:288](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L288)
+Defined in: [preact-query/src/useInfiniteQuery.ts:289](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L289)
 
 The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
 `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
@@ -368,7 +368,8 @@ instead of setting `enabled: false`:
 import { skipToken, useInfiniteQuery } from '@tanstack/preact-query'
 
 function Comments({ postId }: { postId: string | undefined }) {
-  const { data, isPending, isError, error } = useInfiniteQuery({
+  // Use `isLoading`, not `isPending`, so the loading state doesn't show while the query is disabled.
+  const { data, isLoading, isError, error } = useInfiniteQuery({
     queryKey: ['post', postId, 'comments'],
     queryFn:
       postId != null
@@ -379,12 +380,12 @@ function Comments({ postId }: { postId: string | undefined }) {
   })
 
   if (postId == null) return 'Select a post'
-  if (isPending) return 'Loading...'
+  if (isLoading) return 'Loading...'
   if (isError) return <span>Error: {error.message}</span>
 
   return (
     <ul>
-      {data.pages.map((page) => page.comments.map((c) => <li key={c.id}>{c.text}</li>))}
+      {data?.pages.map((page) => page.comments.map((c) => <li key={c.id}>{c.text}</li>))}
     </ul>
   )
 }
diff --git a/packages/preact-query/src/infiniteQueryOptions.ts b/packages/preact-query/src/infiniteQueryOptions.ts
index 72070b45c6..cd825586f6 100644
--- a/packages/preact-query/src/infiniteQueryOptions.ts
+++ b/packages/preact-query/src/infiniteQueryOptions.ts
@@ -352,15 +352,16 @@ export function infiniteQueryOptions<
  *   })
  *
  * function Comments({ postId }: { postId: string | undefined }) {
- *   const { data, isPending, isError, error } = useInfiniteQuery(commentsOptions(postId))
+ *   // Use `isLoading`, not `isPending`, so the loading state doesn't show while the query is disabled.
+ *   const { data, isLoading, isError, error } = useInfiniteQuery(commentsOptions(postId))
  *
  *   if (postId == null) return 'Select a post'
- *   if (isPending) return 'Loading...'
+ *   if (isLoading) return 'Loading...'
  *   if (isError) return <span>Error: {error.message}</span>
  *
  *   return (
  *     <ul>
- *       {data.pages.map((page) => page.comments.map((c) => <li key={c.id}>{c.text}</li>))}
+ *       {data?.pages.map((page) => page.comments.map((c) => <li key={c.id}>{c.text}</li>))}
  *     </ul>
  *   )
  * }
diff --git a/packages/preact-query/src/useInfiniteQuery.ts b/packages/preact-query/src/useInfiniteQuery.ts
index b7305eea9e..2b48140ee2 100644
--- a/packages/preact-query/src/useInfiniteQuery.ts
+++ b/packages/preact-query/src/useInfiniteQuery.ts
@@ -263,7 +263,8 @@ export function useInfiniteQuery<
  * import { skipToken, useInfiniteQuery } from '@tanstack/preact-query'
  *
  * function Comments({ postId }: { postId: string | undefined }) {
- *   const { data, isPending, isError, error } = useInfiniteQuery({
+ *   // Use `isLoading`, not `isPending`, so the loading state doesn't show while the query is disabled.
+ *   const { data, isLoading, isError, error } = useInfiniteQuery({
  *     queryKey: ['post', postId, 'comments'],
  *     queryFn:
  *       postId != null
@@ -274,12 +275,12 @@ export function useInfiniteQuery<
  *   })
  *
  *   if (postId == null) return 'Select a post'
- *   if (isPending) return 'Loading...'
+ *   if (isLoading) return 'Loading...'
  *   if (isError) return <span>Error: {error.message}</span>
  *
  *   return (
  *     <ul>
- *       {data.pages.map((page) => page.comments.map((c) => <li key={c.id}>{c.text}</li>))}
+ *       {data?.pages.map((page) => page.comments.map((c) => <li key={c.id}>{c.text}</li>))}
  *     </ul>
  *   )
  * }

From 2bae845611665a0bb2c5692e125833c4107ee0f6 Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Sat, 29 Aug 2026 12:04:24 +0900
Subject: [PATCH 21/30] docs(preact-query): add missing 'isPending'/'isError'
 handling across
 'queryOptions'/'useQuery'/'infiniteQueryOptions'/'useInfiniteQuery' examples

---
 .../functions/infiniteQueryOptions.md         | 27 ++++++---
 .../reference/functions/queryOptions.md       | 58 +++++++++++++------
 .../reference/functions/useInfiniteQuery.md   | 10 ++--
 .../preact/reference/functions/useQuery.md    | 13 +++--
 .../preact-query/src/infiniteQueryOptions.ts  | 21 +++++--
 packages/preact-query/src/queryOptions.ts     | 52 ++++++++++++-----
 packages/preact-query/src/useInfiniteQuery.ts |  4 +-
 packages/preact-query/src/useQuery.ts         | 11 +++-
 8 files changed, 140 insertions(+), 56 deletions(-)

diff --git a/docs/framework/preact/reference/functions/infiniteQueryOptions.md b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
index 7e5eafa1a3..7d6d9983ea 100644
--- a/docs/framework/preact/reference/functions/infiniteQueryOptions.md
+++ b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
@@ -9,7 +9,7 @@ title: infiniteQueryOptions
 function infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options): UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & object & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData, unknown>, TError>;
 ```
 
-Defined in: [preact-query/src/infiniteQueryOptions.ts:161](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L161)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:164](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L164)
 
 You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
 These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
@@ -69,7 +69,10 @@ export const projectsOptions = infiniteQueryOptions({
 })
 
 function Projects() {
-  const { data } = useInfiniteQuery(projectsOptions)
+  const { data, isError, error } = useInfiniteQuery(projectsOptions)
+
+  if (isError) return <span>Error: {error.message}</span>
+
   return (
     <ul>
       {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
@@ -84,7 +87,7 @@ function Projects() {
 function infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options): OmitKeyof<UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, "queryFn"> & object & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData, unknown>, TError>;
 ```
 
-Defined in: [preact-query/src/infiniteQueryOptions.ts:249](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L249)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:256](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L256)
 
 You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
 These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
@@ -137,10 +140,14 @@ export const projectsOptions = infiniteQueryOptions({
 })
 
 function Projects() {
-  const { data } = useInfiniteQuery(projectsOptions)
+  const { data, isPending, isError, error } = useInfiniteQuery(projectsOptions)
+
+  if (isPending) return 'Loading...'
+  if (isError) return <span>Error: {error.message}</span>
+
   return (
     <ul>
-      {data?.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
+      {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
     </ul>
   )
 }
@@ -189,7 +196,7 @@ queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
 function infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options): UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & object & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData, unknown>, TError>;
 ```
 
-Defined in: [preact-query/src/infiniteQueryOptions.ts:373](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L373)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:384](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L384)
 
 You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
 These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
@@ -242,10 +249,14 @@ export const projectsOptions = infiniteQueryOptions({
 })
 
 function Projects() {
-  const { data } = useInfiniteQuery(projectsOptions)
+  const { data, isPending, isError, error } = useInfiniteQuery(projectsOptions)
+
+  if (isPending) return 'Loading...'
+  if (isError) return <span>Error: {error.message}</span>
+
   return (
     <ul>
-      {data?.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
+      {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
     </ul>
   )
 }
diff --git a/docs/framework/preact/reference/functions/queryOptions.md b/docs/framework/preact/reference/functions/queryOptions.md
index 4af286b8bb..03cbda3916 100644
--- a/docs/framework/preact/reference/functions/queryOptions.md
+++ b/docs/framework/preact/reference/functions/queryOptions.md
@@ -9,7 +9,7 @@ title: queryOptions
 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:135](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L135)
+Defined in: [preact-query/src/queryOptions.ts:138](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L138)
 
 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
@@ -64,7 +64,10 @@ export const postsOptions = queryOptions({
 
 function Posts() {
   // `data` is `Post[]`, never `undefined`, thanks to `initialData`.
-  const { data } = useQuery(postsOptions)
+  const { data, isError, error } = useQuery(postsOptions)
+
+  if (isError) return <span>Error: {error.message}</span>
+
   return (
     <ul>
       {data.map((post) => <li key={post.id}>{post.title}</li>)}
@@ -79,7 +82,7 @@ function Posts() {
 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:219](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L219)
+Defined in: [preact-query/src/queryOptions.ts:232](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L232)
 
 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
@@ -130,10 +133,14 @@ export const postsOptions = queryOptions({
 })
 
 function Posts() {
-  const { data } = useQuery(postsOptions)
+  const { data, isPending, isError, error } = useQuery(postsOptions)
+
+  if (isPending) return 'Loading...'
+  if (isError) return <span>Error: {error.message}</span>
+
   return (
     <ul>
-      {data?.map((post) => <li key={post.id}>{post.title}</li>)}
+      {data.map((post) => <li key={post.id}>{post.title}</li>)}
     </ul>
   )
 }
@@ -150,8 +157,10 @@ export const postOptions = (id: string) =>
   })
 
 function Post({ id }: { id: string }) {
-  const { data } = useQuery(postOptions(id))
-  return <h1>{data?.title}</h1>
+  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` —
@@ -170,10 +179,14 @@ const todosOptions = queryOptions({
 })
 
 function Todos() {
-  const { data } = useQuery(todosOptions)
+  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>)}
+      {data.map((todo) => <li key={todo.id}>{todo.title}</li>)}
     </ul>
   )
 }
@@ -189,7 +202,7 @@ queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefi
 function queryOptions<TQueryFnData, TError, TData, TQueryKey>(options): UseQueryOptions<TQueryFnData, TError, TData, TQueryKey> & object & QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>;
 ```
 
-Defined in: [preact-query/src/queryOptions.ts:324](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L324)
+Defined in: [preact-query/src/queryOptions.ts:348](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L348)
 
 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
@@ -240,10 +253,14 @@ export const postsOptions = queryOptions({
 })
 
 function Posts() {
-  const { data } = useQuery(postsOptions)
+  const { data, isPending, isError, error } = useQuery(postsOptions)
+
+  if (isPending) return 'Loading...'
+  if (isError) return <span>Error: {error.message}</span>
+
   return (
     <ul>
-      {data?.map((post) => <li key={post.id}>{post.title}</li>)}
+      {data.map((post) => <li key={post.id}>{post.title}</li>)}
     </ul>
   )
 }
@@ -260,8 +277,10 @@ export const postOptions = (id: string) =>
   })
 
 function Post({ id }: { id: string }) {
-  const { data } = useQuery(postOptions(id))
-  return <h1>{data?.title}</h1>
+  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` —
@@ -280,10 +299,14 @@ const todosOptions = queryOptions({
 })
 
 function Todos() {
-  const { data } = useQuery(todosOptions)
+  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>)}
+      {data.map((todo) => <li key={todo.id}>{todo.title}</li>)}
     </ul>
   )
 }
@@ -304,10 +327,11 @@ export const postOptions = (postId: number | undefined) =>
   })
 
 function Post({ postId }: { postId: number | undefined }) {
-  const { data, isLoading } = useQuery(postOptions(postId))
+  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>
 }
diff --git a/docs/framework/preact/reference/functions/useInfiniteQuery.md b/docs/framework/preact/reference/functions/useInfiniteQuery.md
index 8172194f93..7fcc20d4d6 100644
--- a/docs/framework/preact/reference/functions/useInfiniteQuery.md
+++ b/docs/framework/preact/reference/functions/useInfiniteQuery.md
@@ -9,7 +9,7 @@ title: useInfiniteQuery
 function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): DefinedUseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useInfiniteQuery.ts:59](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L59)
+Defined in: [preact-query/src/useInfiniteQuery.ts:61](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L61)
 
 The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
 `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
@@ -77,7 +77,7 @@ actions, or add conditions like `hasNextPage && !isFetching`.
 import { useInfiniteQuery } from '@tanstack/preact-query'
 
 function Projects() {
-  const { data } = useInfiniteQuery({
+  const { data, isError, error } = useInfiniteQuery({
     queryKey: ['projects'],
     queryFn: ({ pageParam }) => fetchProjects(pageParam),
     initialPageParam: 0,
@@ -85,6 +85,8 @@ function Projects() {
     initialData: { pages: [], pageParams: [] },
   })
 
+  if (isError) return <span>Error: {error.message}</span>
+
   return (
     <ul>
       {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
@@ -99,7 +101,7 @@ function Projects() {
 function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): UseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useInfiniteQuery.ts:137](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L137)
+Defined in: [preact-query/src/useInfiniteQuery.ts:139](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L139)
 
 The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
 `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
@@ -212,7 +214,7 @@ function Projects() {
 function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): UseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useInfiniteQuery.ts:289](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L289)
+Defined in: [preact-query/src/useInfiniteQuery.ts:291](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L291)
 
 The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
 `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
diff --git a/docs/framework/preact/reference/functions/useQuery.md b/docs/framework/preact/reference/functions/useQuery.md
index 2652e6664d..1e89c1eb72 100644
--- a/docs/framework/preact/reference/functions/useQuery.md
+++ b/docs/framework/preact/reference/functions/useQuery.md
@@ -188,7 +188,7 @@ function Posts() {
 function useQuery<TQueryFnData, TError, TData, TQueryKey>(options, queryClient?): UseQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useQuery.ts:288](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L288)
+Defined in: [preact-query/src/useQuery.ts:293](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L293)
 
 ### Type Parameters
 
@@ -312,7 +312,7 @@ import { useQuery, useQueryClient } from '@tanstack/preact-query'
 function Post({ postId }: { postId: number }) {
   const queryClient = useQueryClient()
 
-  const { data } = useQuery({
+  const { data, isError, error } = useQuery({
     queryKey: ['post', postId],
     queryFn: () => fetchPost(postId),
     initialData: () =>
@@ -321,6 +321,8 @@ function Post({ postId }: { postId: number }) {
         ?.find((post) => post.id === postId),
   })
 
+  if (isError) return <span>Error: {error.message}</span>
+
   return <h1>{data?.title}</h1>
 }
 ```
@@ -333,12 +335,14 @@ import { useState } from 'preact/hooks'
 function Posts() {
   const [page, setPage] = useState(0)
 
-  const { data, isPlaceholderData } = useQuery({
+  const { data, isPlaceholderData, isError, error } = useQuery({
     queryKey: ['posts', page],
     queryFn: () => fetchPosts(page),
     placeholderData: keepPreviousData,
   })
 
+  if (isError) return <span>Error: {error.message}</span>
+
   return (
     <div>
       <ul>
@@ -367,7 +371,8 @@ const postOptions = (id: string) =>
   })
 
 function Post({ id }: { id: string }) {
-  const { data } = useQuery(postOptions(id))
+  const { data, isError, error } = useQuery(postOptions(id))
+  if (isError) return <span>Error: {error.message}</span>
   return <h1>{data?.title}</h1>
 }
 
diff --git a/packages/preact-query/src/infiniteQueryOptions.ts b/packages/preact-query/src/infiniteQueryOptions.ts
index cd825586f6..fe04a67e6f 100644
--- a/packages/preact-query/src/infiniteQueryOptions.ts
+++ b/packages/preact-query/src/infiniteQueryOptions.ts
@@ -149,7 +149,10 @@ export type DefinedInitialDataInfiniteOptions<
  * })
  *
  * function Projects() {
- *   const { data } = useInfiniteQuery(projectsOptions)
+ *   const { data, isError, error } = useInfiniteQuery(projectsOptions)
+ *
+ *   if (isError) return <span>Error: {error.message}</span>
+ *
  *   return (
  *     <ul>
  *       {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
@@ -200,10 +203,14 @@ export function infiniteQueryOptions<
  * })
  *
  * function Projects() {
- *   const { data } = useInfiniteQuery(projectsOptions)
+ *   const { data, isPending, isError, error } = useInfiniteQuery(projectsOptions)
+ *
+ *   if (isPending) return 'Loading...'
+ *   if (isError) return <span>Error: {error.message}</span>
+ *
  *   return (
  *     <ul>
- *       {data?.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
+ *       {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
  *     </ul>
  *   )
  * }
@@ -288,10 +295,14 @@ export function infiniteQueryOptions<
  * })
  *
  * function Projects() {
- *   const { data } = useInfiniteQuery(projectsOptions)
+ *   const { data, isPending, isError, error } = useInfiniteQuery(projectsOptions)
+ *
+ *   if (isPending) return 'Loading...'
+ *   if (isError) return <span>Error: {error.message}</span>
+ *
  *   return (
  *     <ul>
- *       {data?.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
+ *       {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
  *     </ul>
  *   )
  * }
diff --git a/packages/preact-query/src/queryOptions.ts b/packages/preact-query/src/queryOptions.ts
index 90f3d00c20..eb7a9dca75 100644
--- a/packages/preact-query/src/queryOptions.ts
+++ b/packages/preact-query/src/queryOptions.ts
@@ -123,7 +123,10 @@ export type DefinedInitialDataOptions<
  *
  * function Posts() {
  *   // `data` is `Post[]`, never `undefined`, thanks to `initialData`.
- *   const { data } = useQuery(postsOptions)
+ *   const { data, isError, error } = useQuery(postsOptions)
+ *
+ *   if (isError) return <span>Error: {error.message}</span>
+ *
  *   return (
  *     <ul>
  *       {data.map((post) => <li key={post.id}>{post.title}</li>)}
@@ -161,10 +164,14 @@ export function queryOptions<
  * })
  *
  * function Posts() {
- *   const { data } = useQuery(postsOptions)
+ *   const { data, isPending, isError, error } = useQuery(postsOptions)
+ *
+ *   if (isPending) return 'Loading...'
+ *   if (isError) return <span>Error: {error.message}</span>
+ *
  *   return (
  *     <ul>
- *       {data?.map((post) => <li key={post.id}>{post.title}</li>)}
+ *       {data.map((post) => <li key={post.id}>{post.title}</li>)}
  *     </ul>
  *   )
  * }
@@ -182,8 +189,10 @@ export function queryOptions<
  *   })
  *
  * function Post({ id }: { id: string }) {
- *   const { data } = useQuery(postOptions(id))
- *   return <h1>{data?.title}</h1>
+ *   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` —
@@ -203,10 +212,14 @@ export function queryOptions<
  * })
  *
  * function Todos() {
- *   const { data } = useQuery(todosOptions)
+ *   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>)}
+ *       {data.map((todo) => <li key={todo.id}>{todo.title}</li>)}
  *     </ul>
  *   )
  * }
@@ -245,10 +258,14 @@ export function queryOptions<
  * })
  *
  * function Posts() {
- *   const { data } = useQuery(postsOptions)
+ *   const { data, isPending, isError, error } = useQuery(postsOptions)
+ *
+ *   if (isPending) return 'Loading...'
+ *   if (isError) return <span>Error: {error.message}</span>
+ *
  *   return (
  *     <ul>
- *       {data?.map((post) => <li key={post.id}>{post.title}</li>)}
+ *       {data.map((post) => <li key={post.id}>{post.title}</li>)}
  *     </ul>
  *   )
  * }
@@ -266,8 +283,10 @@ export function queryOptions<
  *   })
  *
  * function Post({ id }: { id: string }) {
- *   const { data } = useQuery(postOptions(id))
- *   return <h1>{data?.title}</h1>
+ *   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` —
@@ -287,10 +306,14 @@ export function queryOptions<
  * })
  *
  * function Todos() {
- *   const { data } = useQuery(todosOptions)
+ *   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>)}
+ *       {data.map((todo) => <li key={todo.id}>{todo.title}</li>)}
  *     </ul>
  *   )
  * }
@@ -312,10 +335,11 @@ export function queryOptions<
  *   })
  *
  * function Post({ postId }: { postId: number | undefined }) {
- *   const { data, isLoading } = useQuery(postOptions(postId))
+ *   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>
  * }
diff --git a/packages/preact-query/src/useInfiniteQuery.ts b/packages/preact-query/src/useInfiniteQuery.ts
index 2b48140ee2..6427613b68 100644
--- a/packages/preact-query/src/useInfiniteQuery.ts
+++ b/packages/preact-query/src/useInfiniteQuery.ts
@@ -40,7 +40,7 @@ import { useBaseQuery } from './useBaseQuery'
  * import { useInfiniteQuery } from '@tanstack/preact-query'
  *
  * function Projects() {
- *   const { data } = useInfiniteQuery({
+ *   const { data, isError, error } = useInfiniteQuery({
  *     queryKey: ['projects'],
  *     queryFn: ({ pageParam }) => fetchProjects(pageParam),
  *     initialPageParam: 0,
@@ -48,6 +48,8 @@ import { useBaseQuery } from './useBaseQuery'
  *     initialData: { pages: [], pageParams: [] },
  *   })
  *
+ *   if (isError) return <span>Error: {error.message}</span>
+ *
  *   return (
  *     <ul>
  *       {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
diff --git a/packages/preact-query/src/useQuery.ts b/packages/preact-query/src/useQuery.ts
index 8736ed9e5b..9602d7e305 100644
--- a/packages/preact-query/src/useQuery.ts
+++ b/packages/preact-query/src/useQuery.ts
@@ -210,7 +210,7 @@ export function useQuery<
  * function Post({ postId }: { postId: number }) {
  *   const queryClient = useQueryClient()
  *
- *   const { data } = useQuery({
+ *   const { data, isError, error } = useQuery({
  *     queryKey: ['post', postId],
  *     queryFn: () => fetchPost(postId),
  *     initialData: () =>
@@ -219,6 +219,8 @@ export function useQuery<
  *         ?.find((post) => post.id === postId),
  *   })
  *
+ *   if (isError) return <span>Error: {error.message}</span>
+ *
  *   return <h1>{data?.title}</h1>
  * }
  * ```
@@ -232,12 +234,14 @@ export function useQuery<
  * function Posts() {
  *   const [page, setPage] = useState(0)
  *
- *   const { data, isPlaceholderData } = useQuery({
+ *   const { data, isPlaceholderData, isError, error } = useQuery({
  *     queryKey: ['posts', page],
  *     queryFn: () => fetchPosts(page),
  *     placeholderData: keepPreviousData,
  *   })
  *
+ *   if (isError) return <span>Error: {error.message}</span>
+ *
  *   return (
  *     <div>
  *       <ul>
@@ -267,7 +271,8 @@ export function useQuery<
  *   })
  *
  * function Post({ id }: { id: string }) {
- *   const { data } = useQuery(postOptions(id))
+ *   const { data, isError, error } = useQuery(postOptions(id))
+ *   if (isError) return <span>Error: {error.message}</span>
  *   return <h1>{data?.title}</h1>
  * }
  *

From f0cf0c181894ba1bb462fc0498ae184f98581b1f Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Sat, 29 Aug 2026 12:09:14 +0900
Subject: [PATCH 22/30] docs(preact-query): keep 'initialData' examples showing
 data alongside errors instead of hiding it

---
 .../functions/infiniteQueryOptions.md         | 19 ++++++++++--------
 .../reference/functions/queryOptions.md       | 20 ++++++++++---------
 .../reference/functions/useInfiniteQuery.md   | 19 ++++++++++--------
 .../preact/reference/functions/useQuery.md    | 20 +++++++++++--------
 .../preact-query/src/infiniteQueryOptions.ts  | 13 +++++++-----
 packages/preact-query/src/queryOptions.ts     | 14 +++++++------
 packages/preact-query/src/useInfiniteQuery.ts | 13 +++++++-----
 packages/preact-query/src/useQuery.ts         | 14 ++++++++-----
 8 files changed, 78 insertions(+), 54 deletions(-)

diff --git a/docs/framework/preact/reference/functions/infiniteQueryOptions.md b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
index 7d6d9983ea..7c1650470a 100644
--- a/docs/framework/preact/reference/functions/infiniteQueryOptions.md
+++ b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
@@ -9,7 +9,7 @@ title: infiniteQueryOptions
 function infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options): UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & object & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData, unknown>, TError>;
 ```
 
-Defined in: [preact-query/src/infiniteQueryOptions.ts:164](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L164)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:167](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L167)
 
 You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
 These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
@@ -69,14 +69,17 @@ export const projectsOptions = infiniteQueryOptions({
 })
 
 function Projects() {
+  // `data` is never `undefined`, thanks to `initialData` — even if a refetch fails, so the
+  // list stays visible alongside the error.
   const { data, isError, error } = useInfiniteQuery(projectsOptions)
 
-  if (isError) return <span>Error: {error.message}</span>
-
   return (
-    <ul>
-      {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
-    </ul>
+    <div>
+      {isError ? <span>Error: {error.message}</span> : null}
+      <ul>
+        {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
+      </ul>
+    </div>
   )
 }
 ```
@@ -87,7 +90,7 @@ function Projects() {
 function infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options): OmitKeyof<UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, "queryFn"> & object & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData, unknown>, TError>;
 ```
 
-Defined in: [preact-query/src/infiniteQueryOptions.ts:256](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L256)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:259](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L259)
 
 You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
 These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
@@ -196,7 +199,7 @@ queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
 function infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options): UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & object & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData, unknown>, TError>;
 ```
 
-Defined in: [preact-query/src/infiniteQueryOptions.ts:384](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L384)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:387](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L387)
 
 You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
 These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
diff --git a/docs/framework/preact/reference/functions/queryOptions.md b/docs/framework/preact/reference/functions/queryOptions.md
index 03cbda3916..3ca9efb150 100644
--- a/docs/framework/preact/reference/functions/queryOptions.md
+++ b/docs/framework/preact/reference/functions/queryOptions.md
@@ -9,7 +9,7 @@ title: queryOptions
 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:138](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L138)
+Defined in: [preact-query/src/queryOptions.ts:140](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L140)
 
 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
@@ -63,15 +63,17 @@ export const postsOptions = queryOptions({
 })
 
 function Posts() {
-  // `data` is `Post[]`, never `undefined`, thanks to `initialData`.
+  // `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)
 
-  if (isError) return <span>Error: {error.message}</span>
-
   return (
-    <ul>
-      {data.map((post) => <li key={post.id}>{post.title}</li>)}
-    </ul>
+    <div>
+      {isError ? <span>Error: {error.message}</span> : null}
+      <ul>
+        {data.map((post) => <li key={post.id}>{post.title}</li>)}
+      </ul>
+    </div>
   )
 }
 ```
@@ -82,7 +84,7 @@ function Posts() {
 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:232](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L232)
+Defined in: [preact-query/src/queryOptions.ts:234](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L234)
 
 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
@@ -202,7 +204,7 @@ queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefi
 function queryOptions<TQueryFnData, TError, TData, TQueryKey>(options): UseQueryOptions<TQueryFnData, TError, TData, TQueryKey> & object & QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>;
 ```
 
-Defined in: [preact-query/src/queryOptions.ts:348](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L348)
+Defined in: [preact-query/src/queryOptions.ts:350](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L350)
 
 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
diff --git a/docs/framework/preact/reference/functions/useInfiniteQuery.md b/docs/framework/preact/reference/functions/useInfiniteQuery.md
index 7fcc20d4d6..831cd6fe6a 100644
--- a/docs/framework/preact/reference/functions/useInfiniteQuery.md
+++ b/docs/framework/preact/reference/functions/useInfiniteQuery.md
@@ -9,7 +9,7 @@ title: useInfiniteQuery
 function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): DefinedUseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useInfiniteQuery.ts:61](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L61)
+Defined in: [preact-query/src/useInfiniteQuery.ts:64](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L64)
 
 The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
 `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
@@ -77,6 +77,8 @@ actions, or add conditions like `hasNextPage && !isFetching`.
 import { useInfiniteQuery } from '@tanstack/preact-query'
 
 function Projects() {
+  // `data` is never `undefined`, thanks to `initialData` — even if a refetch fails, so the
+  // list stays visible alongside the error.
   const { data, isError, error } = useInfiniteQuery({
     queryKey: ['projects'],
     queryFn: ({ pageParam }) => fetchProjects(pageParam),
@@ -85,12 +87,13 @@ function Projects() {
     initialData: { pages: [], pageParams: [] },
   })
 
-  if (isError) return <span>Error: {error.message}</span>
-
   return (
-    <ul>
-      {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
-    </ul>
+    <div>
+      {isError ? <span>Error: {error.message}</span> : null}
+      <ul>
+        {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
+      </ul>
+    </div>
   )
 }
 ```
@@ -101,7 +104,7 @@ function Projects() {
 function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): UseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useInfiniteQuery.ts:139](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L139)
+Defined in: [preact-query/src/useInfiniteQuery.ts:142](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L142)
 
 The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
 `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
@@ -214,7 +217,7 @@ function Projects() {
 function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): UseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useInfiniteQuery.ts:291](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L291)
+Defined in: [preact-query/src/useInfiniteQuery.ts:294](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L294)
 
 The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
 `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
diff --git a/docs/framework/preact/reference/functions/useQuery.md b/docs/framework/preact/reference/functions/useQuery.md
index 1e89c1eb72..4ce44660c4 100644
--- a/docs/framework/preact/reference/functions/useQuery.md
+++ b/docs/framework/preact/reference/functions/useQuery.md
@@ -9,7 +9,7 @@ title: useQuery
 function useQuery<TQueryFnData, TError, TData, TQueryKey>(options, queryClient?): DefinedUseQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useQuery.ts:46](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L46)
+Defined in: [preact-query/src/useQuery.ts:50](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L50)
 
 This overload is selected when `initialData` is set, so the resulting `data` is never `undefined`.
 
@@ -64,17 +64,21 @@ since `initialData` guarantees data upfront). `isSuccess`/`isError` are derived
 import { useQuery } from '@tanstack/preact-query'
 
 function Posts() {
-  // `data` is `Post[]`, never `undefined`, thanks to `initialData`.
-  const { data } = useQuery({
+  // `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({
     queryKey: ['posts'],
     queryFn: fetchPosts,
     initialData: [],
   })
 
   return (
-    <ul>
-      {data.map((post) => <li key={post.id}>{post.title}</li>)}
-    </ul>
+    <div>
+      {isError ? <span>Error: {error.message}</span> : null}
+      <ul>
+        {data.map((post) => <li key={post.id}>{post.title}</li>)}
+      </ul>
+    </div>
   )
 }
 ```
@@ -85,7 +89,7 @@ function Posts() {
 function useQuery<TQueryFnData, TError, TData, TQueryKey>(options, queryClient?): UseQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useQuery.ts:115](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L115)
+Defined in: [preact-query/src/useQuery.ts:119](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L119)
 
 ### Type Parameters
 
@@ -188,7 +192,7 @@ function Posts() {
 function useQuery<TQueryFnData, TError, TData, TQueryKey>(options, queryClient?): UseQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useQuery.ts:293](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L293)
+Defined in: [preact-query/src/useQuery.ts:297](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L297)
 
 ### Type Parameters
 
diff --git a/packages/preact-query/src/infiniteQueryOptions.ts b/packages/preact-query/src/infiniteQueryOptions.ts
index fe04a67e6f..5e1cd58835 100644
--- a/packages/preact-query/src/infiniteQueryOptions.ts
+++ b/packages/preact-query/src/infiniteQueryOptions.ts
@@ -149,14 +149,17 @@ export type DefinedInitialDataInfiniteOptions<
  * })
  *
  * function Projects() {
+ *   // `data` is never `undefined`, thanks to `initialData` — even if a refetch fails, so the
+ *   // list stays visible alongside the error.
  *   const { data, isError, error } = useInfiniteQuery(projectsOptions)
  *
- *   if (isError) return <span>Error: {error.message}</span>
- *
  *   return (
- *     <ul>
- *       {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
- *     </ul>
+ *     <div>
+ *       {isError ? <span>Error: {error.message}</span> : null}
+ *       <ul>
+ *         {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
+ *       </ul>
+ *     </div>
  *   )
  * }
  * ```
diff --git a/packages/preact-query/src/queryOptions.ts b/packages/preact-query/src/queryOptions.ts
index eb7a9dca75..a090606c96 100644
--- a/packages/preact-query/src/queryOptions.ts
+++ b/packages/preact-query/src/queryOptions.ts
@@ -122,15 +122,17 @@ export type DefinedInitialDataOptions<
  * })
  *
  * function Posts() {
- *   // `data` is `Post[]`, never `undefined`, thanks to `initialData`.
+ *   // `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)
  *
- *   if (isError) return <span>Error: {error.message}</span>
- *
  *   return (
- *     <ul>
- *       {data.map((post) => <li key={post.id}>{post.title}</li>)}
- *     </ul>
+ *     <div>
+ *       {isError ? <span>Error: {error.message}</span> : null}
+ *       <ul>
+ *         {data.map((post) => <li key={post.id}>{post.title}</li>)}
+ *       </ul>
+ *     </div>
  *   )
  * }
  * ```
diff --git a/packages/preact-query/src/useInfiniteQuery.ts b/packages/preact-query/src/useInfiniteQuery.ts
index 6427613b68..39b639e111 100644
--- a/packages/preact-query/src/useInfiniteQuery.ts
+++ b/packages/preact-query/src/useInfiniteQuery.ts
@@ -40,6 +40,8 @@ import { useBaseQuery } from './useBaseQuery'
  * import { useInfiniteQuery } from '@tanstack/preact-query'
  *
  * function Projects() {
+ *   // `data` is never `undefined`, thanks to `initialData` — even if a refetch fails, so the
+ *   // list stays visible alongside the error.
  *   const { data, isError, error } = useInfiniteQuery({
  *     queryKey: ['projects'],
  *     queryFn: ({ pageParam }) => fetchProjects(pageParam),
@@ -48,12 +50,13 @@ import { useBaseQuery } from './useBaseQuery'
  *     initialData: { pages: [], pageParams: [] },
  *   })
  *
- *   if (isError) return <span>Error: {error.message}</span>
- *
  *   return (
- *     <ul>
- *       {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
- *     </ul>
+ *     <div>
+ *       {isError ? <span>Error: {error.message}</span> : null}
+ *       <ul>
+ *         {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
+ *       </ul>
+ *     </div>
  *   )
  * }
  * ```
diff --git a/packages/preact-query/src/useQuery.ts b/packages/preact-query/src/useQuery.ts
index 9602d7e305..e005fe2f54 100644
--- a/packages/preact-query/src/useQuery.ts
+++ b/packages/preact-query/src/useQuery.ts
@@ -28,17 +28,21 @@ import { useBaseQuery } from './useBaseQuery'
  * import { useQuery } from '@tanstack/preact-query'
  *
  * function Posts() {
- *   // `data` is `Post[]`, never `undefined`, thanks to `initialData`.
- *   const { data } = useQuery({
+ *   // `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({
  *     queryKey: ['posts'],
  *     queryFn: fetchPosts,
  *     initialData: [],
  *   })
  *
  *   return (
- *     <ul>
- *       {data.map((post) => <li key={post.id}>{post.title}</li>)}
- *     </ul>
+ *     <div>
+ *       {isError ? <span>Error: {error.message}</span> : null}
+ *       <ul>
+ *         {data.map((post) => <li key={post.id}>{post.title}</li>)}
+ *       </ul>
+ *     </div>
  *   )
  * }
  * ```

From 3676ed7e53a4206eb7342cb687ccf0f263cf0de9 Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Sun, 30 Aug 2026 11:49:15 +0900
Subject: [PATCH 23/30] docs(preact-query): use scroll-triggered pagination in
 'useInfiniteQuery' examples, add a 'fetchNextPage' trigger to
 'infiniteQueryOptions'

---
 .../functions/infiniteQueryOptions.md         |  49 ++++++---
 .../reference/functions/useInfiniteQuery.md   | 100 +++++++++---------
 .../preact-query/src/infiniteQueryOptions.ts  |  43 ++++++--
 packages/preact-query/src/useInfiniteQuery.ts | 100 +++++++++---------
 4 files changed, 171 insertions(+), 121 deletions(-)

diff --git a/docs/framework/preact/reference/functions/infiniteQueryOptions.md b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
index 7c1650470a..7afcb478ff 100644
--- a/docs/framework/preact/reference/functions/infiniteQueryOptions.md
+++ b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
@@ -9,7 +9,7 @@ title: infiniteQueryOptions
 function infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options): UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & object & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData, unknown>, TError>;
 ```
 
-Defined in: [preact-query/src/infiniteQueryOptions.ts:167](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L167)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:174](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L174)
 
 You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
 These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
@@ -71,7 +71,8 @@ export const projectsOptions = infiniteQueryOptions({
 function Projects() {
   // `data` is never `undefined`, thanks to `initialData` — even if a refetch fails, so the
   // list stays visible alongside the error.
-  const { data, isError, error } = useInfiniteQuery(projectsOptions)
+  const { data, isError, error, fetchNextPage, hasNextPage } =
+    useInfiniteQuery(projectsOptions)
 
   return (
     <div>
@@ -79,18 +80,24 @@ function Projects() {
       <ul>
         {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
       </ul>
+      {hasNextPage ? (
+        <button onClick={() => fetchNextPage()}>Load More</button>
+      ) : null}
     </div>
   )
 }
 ```
 
+See [useInfiniteQuery](useInfiniteQuery.md) for an example that fetches the next page automatically as the
+user scrolls, instead of on a button click.
+
 ## Call Signature
 
 ```ts
 function infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options): OmitKeyof<UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, "queryFn"> & object & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData, unknown>, TError>;
 ```
 
-Defined in: [preact-query/src/infiniteQueryOptions.ts:259](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L259)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:275](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L275)
 
 You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
 These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
@@ -143,19 +150,28 @@ export const projectsOptions = infiniteQueryOptions({
 })
 
 function Projects() {
-  const { data, isPending, isError, error } = useInfiniteQuery(projectsOptions)
+  const { data, isPending, isError, error, fetchNextPage, hasNextPage } =
+    useInfiniteQuery(projectsOptions)
 
   if (isPending) return 'Loading...'
   if (isError) return <span>Error: {error.message}</span>
 
   return (
-    <ul>
-      {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
-    </ul>
+    <div>
+      <ul>
+        {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
+      </ul>
+      {hasNextPage ? (
+        <button onClick={() => fetchNextPage()}>Load More</button>
+      ) : null}
+    </div>
   )
 }
 ```
 
+See [useInfiniteQuery](useInfiniteQuery.md) for an example that fetches the next page automatically as the
+user scrolls, instead of on a button click.
+
 A parameterized factory, reused across a hook and an imperative call with the same cache entry:
 ```tsx
 import {
@@ -199,7 +215,7 @@ queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
 function infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options): UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & object & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData, unknown>, TError>;
 ```
 
-Defined in: [preact-query/src/infiniteQueryOptions.ts:387](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L387)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:412](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L412)
 
 You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
 These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
@@ -252,19 +268,28 @@ export const projectsOptions = infiniteQueryOptions({
 })
 
 function Projects() {
-  const { data, isPending, isError, error } = useInfiniteQuery(projectsOptions)
+  const { data, isPending, isError, error, fetchNextPage, hasNextPage } =
+    useInfiniteQuery(projectsOptions)
 
   if (isPending) return 'Loading...'
   if (isError) return <span>Error: {error.message}</span>
 
   return (
-    <ul>
-      {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
-    </ul>
+    <div>
+      <ul>
+        {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
+      </ul>
+      {hasNextPage ? (
+        <button onClick={() => fetchNextPage()}>Load More</button>
+      ) : null}
+    </div>
   )
 }
 ```
 
+See [useInfiniteQuery](useInfiniteQuery.md) for an example that fetches the next page automatically as the
+user scrolls, instead of on a button click.
+
 A parameterized factory, reused across a hook and an imperative call with the same cache entry:
 ```tsx
 import {
diff --git a/docs/framework/preact/reference/functions/useInfiniteQuery.md b/docs/framework/preact/reference/functions/useInfiniteQuery.md
index 831cd6fe6a..691fb990db 100644
--- a/docs/framework/preact/reference/functions/useInfiniteQuery.md
+++ b/docs/framework/preact/reference/functions/useInfiniteQuery.md
@@ -166,25 +166,34 @@ actions, or add conditions like `hasNextPage && !isFetching`.
 
 ### Example
 
+Fetching the next page automatically as the user scrolls, using an `IntersectionObserver` on a
+sentinel element after the list:
 ```tsx
 import { useInfiniteQuery } from '@tanstack/preact-query'
+import { useEffect, useRef } from 'preact/hooks'
 
 function Projects() {
-  const {
-    data,
-    isPending,
-    isError,
-    error,
-    fetchNextPage,
-    hasNextPage,
-    isFetching,
-    isFetchingNextPage,
-  } = useInfiniteQuery({
-    queryKey: ['projects'],
-    queryFn: ({ pageParam }) => fetchProjects(pageParam),
-    initialPageParam: 0,
-    getNextPageParam: (lastPage) => lastPage.nextId,
-  })
+  const { data, isPending, isError, error, fetchNextPage, hasNextPage, isFetchingNextPage } =
+    useInfiniteQuery({
+      queryKey: ['projects'],
+      queryFn: ({ pageParam }) => fetchProjects(pageParam),
+      initialPageParam: 0,
+      getNextPageParam: (lastPage) => lastPage.nextId,
+    })
+
+  const sentinelRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    const sentinel = sentinelRef.current
+    if (sentinel == null || !hasNextPage) return
+
+    const observer = new IntersectionObserver(([entry]) => {
+      if (entry.isIntersecting) fetchNextPage()
+    })
+    observer.observe(sentinel)
+
+    return () => observer.disconnect()
+  }, [hasNextPage, fetchNextPage])
 
   if (isPending) return 'Loading...'
   if (isError) return <span>Error: {error.message}</span>
@@ -196,16 +205,7 @@ function Projects() {
           page.projects.map((project) => <li key={project.id}>{project.name}</li>),
         )}
       </ul>
-      <button
-        onClick={() => fetchNextPage()}
-        disabled={!hasNextPage || isFetching}
-      >
-        {isFetchingNextPage
-          ? 'Loading more...'
-          : hasNextPage
-            ? 'Load More'
-            : 'Nothing more to load'}
-      </button>
+      <div ref={sentinelRef}>{isFetchingNextPage ? 'Loading more...' : null}</div>
     </>
   )
 }
@@ -279,25 +279,34 @@ actions, or add conditions like `hasNextPage && !isFetching`.
 
 ### Examples
 
+Fetching the next page automatically as the user scrolls, using an `IntersectionObserver` on a
+sentinel element after the list:
 ```tsx
 import { useInfiniteQuery } from '@tanstack/preact-query'
+import { useEffect, useRef } from 'preact/hooks'
 
 function Projects() {
-  const {
-    data,
-    isPending,
-    isError,
-    error,
-    fetchNextPage,
-    hasNextPage,
-    isFetching,
-    isFetchingNextPage,
-  } = useInfiniteQuery({
-    queryKey: ['projects'],
-    queryFn: ({ pageParam }) => fetchProjects(pageParam),
-    initialPageParam: 0,
-    getNextPageParam: (lastPage) => lastPage.nextId,
-  })
+  const { data, isPending, isError, error, fetchNextPage, hasNextPage, isFetchingNextPage } =
+    useInfiniteQuery({
+      queryKey: ['projects'],
+      queryFn: ({ pageParam }) => fetchProjects(pageParam),
+      initialPageParam: 0,
+      getNextPageParam: (lastPage) => lastPage.nextId,
+    })
+
+  const sentinelRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    const sentinel = sentinelRef.current
+    if (sentinel == null || !hasNextPage) return
+
+    const observer = new IntersectionObserver(([entry]) => {
+      if (entry.isIntersecting) fetchNextPage()
+    })
+    observer.observe(sentinel)
+
+    return () => observer.disconnect()
+  }, [hasNextPage, fetchNextPage])
 
   if (isPending) return 'Loading...'
   if (isError) return <span>Error: {error.message}</span>
@@ -309,16 +318,7 @@ function Projects() {
           page.projects.map((project) => <li key={project.id}>{project.name}</li>),
         )}
       </ul>
-      <button
-        onClick={() => fetchNextPage()}
-        disabled={!hasNextPage || isFetching}
-      >
-        {isFetchingNextPage
-          ? 'Loading more...'
-          : hasNextPage
-            ? 'Load More'
-            : 'Nothing more to load'}
-      </button>
+      <div ref={sentinelRef}>{isFetchingNextPage ? 'Loading more...' : null}</div>
     </>
   )
 }
diff --git a/packages/preact-query/src/infiniteQueryOptions.ts b/packages/preact-query/src/infiniteQueryOptions.ts
index 5e1cd58835..7147ee2884 100644
--- a/packages/preact-query/src/infiniteQueryOptions.ts
+++ b/packages/preact-query/src/infiniteQueryOptions.ts
@@ -151,7 +151,8 @@ export type DefinedInitialDataInfiniteOptions<
  * function Projects() {
  *   // `data` is never `undefined`, thanks to `initialData` — even if a refetch fails, so the
  *   // list stays visible alongside the error.
- *   const { data, isError, error } = useInfiniteQuery(projectsOptions)
+ *   const { data, isError, error, fetchNextPage, hasNextPage } =
+ *     useInfiniteQuery(projectsOptions)
  *
  *   return (
  *     <div>
@@ -159,10 +160,16 @@ export type DefinedInitialDataInfiniteOptions<
  *       <ul>
  *         {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
  *       </ul>
+ *       {hasNextPage ? (
+ *         <button onClick={() => fetchNextPage()}>Load More</button>
+ *       ) : null}
  *     </div>
  *   )
  * }
  * ```
+ *
+ * See {@link useInfiniteQuery} for an example that fetches the next page automatically as the
+ * user scrolls, instead of on a button click.
  */
 export function infiniteQueryOptions<
   TQueryFnData,
@@ -206,19 +213,28 @@ export function infiniteQueryOptions<
  * })
  *
  * function Projects() {
- *   const { data, isPending, isError, error } = useInfiniteQuery(projectsOptions)
+ *   const { data, isPending, isError, error, fetchNextPage, hasNextPage } =
+ *     useInfiniteQuery(projectsOptions)
  *
  *   if (isPending) return 'Loading...'
  *   if (isError) return <span>Error: {error.message}</span>
  *
  *   return (
- *     <ul>
- *       {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
- *     </ul>
+ *     <div>
+ *       <ul>
+ *         {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
+ *       </ul>
+ *       {hasNextPage ? (
+ *         <button onClick={() => fetchNextPage()}>Load More</button>
+ *       ) : null}
+ *     </div>
  *   )
  * }
  * ```
  *
+ * See {@link useInfiniteQuery} for an example that fetches the next page automatically as the
+ * user scrolls, instead of on a button click.
+ *
  * @example
  * A parameterized factory, reused across a hook and an imperative call with the same cache entry:
  * ```tsx
@@ -298,19 +314,28 @@ export function infiniteQueryOptions<
  * })
  *
  * function Projects() {
- *   const { data, isPending, isError, error } = useInfiniteQuery(projectsOptions)
+ *   const { data, isPending, isError, error, fetchNextPage, hasNextPage } =
+ *     useInfiniteQuery(projectsOptions)
  *
  *   if (isPending) return 'Loading...'
  *   if (isError) return <span>Error: {error.message}</span>
  *
  *   return (
- *     <ul>
- *       {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
- *     </ul>
+ *     <div>
+ *       <ul>
+ *         {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
+ *       </ul>
+ *       {hasNextPage ? (
+ *         <button onClick={() => fetchNextPage()}>Load More</button>
+ *       ) : null}
+ *     </div>
  *   )
  * }
  * ```
  *
+ * See {@link useInfiniteQuery} for an example that fetches the next page automatically as the
+ * user scrolls, instead of on a button click.
+ *
  * @example
  * A parameterized factory, reused across a hook and an imperative call with the same cache entry:
  * ```tsx
diff --git a/packages/preact-query/src/useInfiniteQuery.ts b/packages/preact-query/src/useInfiniteQuery.ts
index 39b639e111..fbc6afb81b 100644
--- a/packages/preact-query/src/useInfiniteQuery.ts
+++ b/packages/preact-query/src/useInfiniteQuery.ts
@@ -94,25 +94,34 @@ export function useInfiniteQuery<
  * `isFetchingPreviousPage`.
  *
  * @example
+ * Fetching the next page automatically as the user scrolls, using an `IntersectionObserver` on a
+ * sentinel element after the list:
  * ```tsx
  * import { useInfiniteQuery } from '@tanstack/preact-query'
+ * import { useEffect, useRef } from 'preact/hooks'
  *
  * function Projects() {
- *   const {
- *     data,
- *     isPending,
- *     isError,
- *     error,
- *     fetchNextPage,
- *     hasNextPage,
- *     isFetching,
- *     isFetchingNextPage,
- *   } = useInfiniteQuery({
- *     queryKey: ['projects'],
- *     queryFn: ({ pageParam }) => fetchProjects(pageParam),
- *     initialPageParam: 0,
- *     getNextPageParam: (lastPage) => lastPage.nextId,
- *   })
+ *   const { data, isPending, isError, error, fetchNextPage, hasNextPage, isFetchingNextPage } =
+ *     useInfiniteQuery({
+ *       queryKey: ['projects'],
+ *       queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *       initialPageParam: 0,
+ *       getNextPageParam: (lastPage) => lastPage.nextId,
+ *     })
+ *
+ *   const sentinelRef = useRef<HTMLDivElement>(null)
+ *
+ *   useEffect(() => {
+ *     const sentinel = sentinelRef.current
+ *     if (sentinel == null || !hasNextPage) return
+ *
+ *     const observer = new IntersectionObserver(([entry]) => {
+ *       if (entry.isIntersecting) fetchNextPage()
+ *     })
+ *     observer.observe(sentinel)
+ *
+ *     return () => observer.disconnect()
+ *   }, [hasNextPage, fetchNextPage])
  *
  *   if (isPending) return 'Loading...'
  *   if (isError) return <span>Error: {error.message}</span>
@@ -124,16 +133,7 @@ export function useInfiniteQuery<
  *           page.projects.map((project) => <li key={project.id}>{project.name}</li>),
  *         )}
  *       </ul>
- *       <button
- *         onClick={() => fetchNextPage()}
- *         disabled={!hasNextPage || isFetching}
- *       >
- *         {isFetchingNextPage
- *           ? 'Loading more...'
- *           : hasNextPage
- *             ? 'Load More'
- *             : 'Nothing more to load'}
- *       </button>
+ *       <div ref={sentinelRef}>{isFetchingNextPage ? 'Loading more...' : null}</div>
  *     </>
  *   )
  * }
@@ -172,25 +172,34 @@ export function useInfiniteQuery<
  * `isFetchingPreviousPage`.
  *
  * @example
+ * Fetching the next page automatically as the user scrolls, using an `IntersectionObserver` on a
+ * sentinel element after the list:
  * ```tsx
  * import { useInfiniteQuery } from '@tanstack/preact-query'
+ * import { useEffect, useRef } from 'preact/hooks'
  *
  * function Projects() {
- *   const {
- *     data,
- *     isPending,
- *     isError,
- *     error,
- *     fetchNextPage,
- *     hasNextPage,
- *     isFetching,
- *     isFetchingNextPage,
- *   } = useInfiniteQuery({
- *     queryKey: ['projects'],
- *     queryFn: ({ pageParam }) => fetchProjects(pageParam),
- *     initialPageParam: 0,
- *     getNextPageParam: (lastPage) => lastPage.nextId,
- *   })
+ *   const { data, isPending, isError, error, fetchNextPage, hasNextPage, isFetchingNextPage } =
+ *     useInfiniteQuery({
+ *       queryKey: ['projects'],
+ *       queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *       initialPageParam: 0,
+ *       getNextPageParam: (lastPage) => lastPage.nextId,
+ *     })
+ *
+ *   const sentinelRef = useRef<HTMLDivElement>(null)
+ *
+ *   useEffect(() => {
+ *     const sentinel = sentinelRef.current
+ *     if (sentinel == null || !hasNextPage) return
+ *
+ *     const observer = new IntersectionObserver(([entry]) => {
+ *       if (entry.isIntersecting) fetchNextPage()
+ *     })
+ *     observer.observe(sentinel)
+ *
+ *     return () => observer.disconnect()
+ *   }, [hasNextPage, fetchNextPage])
  *
  *   if (isPending) return 'Loading...'
  *   if (isError) return <span>Error: {error.message}</span>
@@ -202,16 +211,7 @@ export function useInfiniteQuery<
  *           page.projects.map((project) => <li key={project.id}>{project.name}</li>),
  *         )}
  *       </ul>
- *       <button
- *         onClick={() => fetchNextPage()}
- *         disabled={!hasNextPage || isFetching}
- *       >
- *         {isFetchingNextPage
- *           ? 'Loading more...'
- *           : hasNextPage
- *             ? 'Load More'
- *             : 'Nothing more to load'}
- *       </button>
+ *       <div ref={sentinelRef}>{isFetchingNextPage ? 'Loading more...' : null}</div>
  *     </>
  *   )
  * }

From 9509231ae0106d82e8391d0b5aeb2773d22f9acf Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Sun, 30 Aug 2026 11:59:36 +0900
Subject: [PATCH 24/30] docs(preact-query): guard scroll-triggered
 'fetchNextPage' with 'isFetching', move cross-reference out of '@example'

---
 .../functions/infiniteQueryOptions.md         | 30 ++++++----
 .../reference/functions/useInfiniteQuery.md   | 60 ++++++++++++-------
 .../preact-query/src/infiniteQueryOptions.ts  | 15 ++---
 packages/preact-query/src/useInfiniteQuery.ts | 56 ++++++++++-------
 4 files changed, 98 insertions(+), 63 deletions(-)

diff --git a/docs/framework/preact/reference/functions/infiniteQueryOptions.md b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
index 7afcb478ff..a003d6144b 100644
--- a/docs/framework/preact/reference/functions/infiniteQueryOptions.md
+++ b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
@@ -9,7 +9,7 @@ title: infiniteQueryOptions
 function infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options): UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & object & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData, unknown>, TError>;
 ```
 
-Defined in: [preact-query/src/infiniteQueryOptions.ts:174](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L174)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:173](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L173)
 
 You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
 These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
@@ -55,6 +55,11 @@ The same options object, typed so that `queryKey` carries the inferred data type
 
 [useInfiniteQuery](useInfiniteQuery.md) to run an infinite query with these options.
 
+### Remarks
+
+The example below fetches the next page from a button click. See [useInfiniteQuery](useInfiniteQuery.md) for a
+version that fetches automatically as the user scrolls.
+
 ### Example
 
 ```tsx
@@ -88,16 +93,13 @@ function Projects() {
 }
 ```
 
-See [useInfiniteQuery](useInfiniteQuery.md) for an example that fetches the next page automatically as the
-user scrolls, instead of on a button click.
-
 ## Call Signature
 
 ```ts
 function infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options): OmitKeyof<UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, "queryFn"> & object & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData, unknown>, TError>;
 ```
 
-Defined in: [preact-query/src/infiniteQueryOptions.ts:275](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L275)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:273](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L273)
 
 You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
 These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
@@ -137,6 +139,11 @@ The [UnusedSkipTokenInfiniteOptions](../type-aliases/UnusedSkipTokenInfiniteOpti
 
 The same options object, typed so that `queryKey` carries the inferred data type.
 
+### Remarks
+
+The first example below fetches the next page from a button click. See [useInfiniteQuery](useInfiniteQuery.md)
+for a version that fetches automatically as the user scrolls.
+
 ### Examples
 
 ```tsx
@@ -169,9 +176,6 @@ function Projects() {
 }
 ```
 
-See [useInfiniteQuery](useInfiniteQuery.md) for an example that fetches the next page automatically as the
-user scrolls, instead of on a button click.
-
 A parameterized factory, reused across a hook and an imperative call with the same cache entry:
 ```tsx
 import {
@@ -215,7 +219,7 @@ queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
 function infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options): UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & object & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData, unknown>, TError>;
 ```
 
-Defined in: [preact-query/src/infiniteQueryOptions.ts:412](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L412)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:409](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L409)
 
 You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
 These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
@@ -255,6 +259,11 @@ The [UndefinedInitialDataInfiniteOptions](../type-aliases/UndefinedInitialDataIn
 
 The same options object, typed so that `queryKey` carries the inferred data type.
 
+### Remarks
+
+The first example below fetches the next page from a button click. See [useInfiniteQuery](useInfiniteQuery.md)
+for a version that fetches automatically as the user scrolls.
+
 ### Examples
 
 ```tsx
@@ -287,9 +296,6 @@ function Projects() {
 }
 ```
 
-See [useInfiniteQuery](useInfiniteQuery.md) for an example that fetches the next page automatically as the
-user scrolls, instead of on a button click.
-
 A parameterized factory, reused across a hook and an imperative call with the same cache entry:
 ```tsx
 import {
diff --git a/docs/framework/preact/reference/functions/useInfiniteQuery.md b/docs/framework/preact/reference/functions/useInfiniteQuery.md
index 691fb990db..f7dcb324ae 100644
--- a/docs/framework/preact/reference/functions/useInfiniteQuery.md
+++ b/docs/framework/preact/reference/functions/useInfiniteQuery.md
@@ -104,7 +104,7 @@ function Projects() {
 function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): UseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useInfiniteQuery.ts:142](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L142)
+Defined in: [preact-query/src/useInfiniteQuery.ts:150](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L150)
 
 The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
 `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
@@ -173,27 +173,35 @@ import { useInfiniteQuery } from '@tanstack/preact-query'
 import { useEffect, useRef } from 'preact/hooks'
 
 function Projects() {
-  const { data, isPending, isError, error, fetchNextPage, hasNextPage, isFetchingNextPage } =
-    useInfiniteQuery({
-      queryKey: ['projects'],
-      queryFn: ({ pageParam }) => fetchProjects(pageParam),
-      initialPageParam: 0,
-      getNextPageParam: (lastPage) => lastPage.nextId,
-    })
+  const {
+    data,
+    isPending,
+    isError,
+    error,
+    fetchNextPage,
+    hasNextPage,
+    isFetching,
+    isFetchingNextPage,
+  } = useInfiniteQuery({
+    queryKey: ['projects'],
+    queryFn: ({ pageParam }) => fetchProjects(pageParam),
+    initialPageParam: 0,
+    getNextPageParam: (lastPage) => lastPage.nextId,
+  })
 
   const sentinelRef = useRef<HTMLDivElement>(null)
 
   useEffect(() => {
     const sentinel = sentinelRef.current
-    if (sentinel == null || !hasNextPage) return
+    if (sentinel == null || !hasNextPage || isFetching) return
 
     const observer = new IntersectionObserver(([entry]) => {
-      if (entry.isIntersecting) fetchNextPage()
+      if (entry?.isIntersecting) fetchNextPage()
     })
     observer.observe(sentinel)
 
     return () => observer.disconnect()
-  }, [hasNextPage, fetchNextPage])
+  }, [hasNextPage, isFetching, fetchNextPage])
 
   if (isPending) return 'Loading...'
   if (isError) return <span>Error: {error.message}</span>
@@ -217,7 +225,7 @@ function Projects() {
 function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): UseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useInfiniteQuery.ts:294](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L294)
+Defined in: [preact-query/src/useInfiniteQuery.ts:310](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L310)
 
 The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
 `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
@@ -286,27 +294,35 @@ import { useInfiniteQuery } from '@tanstack/preact-query'
 import { useEffect, useRef } from 'preact/hooks'
 
 function Projects() {
-  const { data, isPending, isError, error, fetchNextPage, hasNextPage, isFetchingNextPage } =
-    useInfiniteQuery({
-      queryKey: ['projects'],
-      queryFn: ({ pageParam }) => fetchProjects(pageParam),
-      initialPageParam: 0,
-      getNextPageParam: (lastPage) => lastPage.nextId,
-    })
+  const {
+    data,
+    isPending,
+    isError,
+    error,
+    fetchNextPage,
+    hasNextPage,
+    isFetching,
+    isFetchingNextPage,
+  } = useInfiniteQuery({
+    queryKey: ['projects'],
+    queryFn: ({ pageParam }) => fetchProjects(pageParam),
+    initialPageParam: 0,
+    getNextPageParam: (lastPage) => lastPage.nextId,
+  })
 
   const sentinelRef = useRef<HTMLDivElement>(null)
 
   useEffect(() => {
     const sentinel = sentinelRef.current
-    if (sentinel == null || !hasNextPage) return
+    if (sentinel == null || !hasNextPage || isFetching) return
 
     const observer = new IntersectionObserver(([entry]) => {
-      if (entry.isIntersecting) fetchNextPage()
+      if (entry?.isIntersecting) fetchNextPage()
     })
     observer.observe(sentinel)
 
     return () => observer.disconnect()
-  }, [hasNextPage, fetchNextPage])
+  }, [hasNextPage, isFetching, fetchNextPage])
 
   if (isPending) return 'Loading...'
   if (isError) return <span>Error: {error.message}</span>
diff --git a/packages/preact-query/src/infiniteQueryOptions.ts b/packages/preact-query/src/infiniteQueryOptions.ts
index 7147ee2884..984ce62564 100644
--- a/packages/preact-query/src/infiniteQueryOptions.ts
+++ b/packages/preact-query/src/infiniteQueryOptions.ts
@@ -135,6 +135,8 @@ export type DefinedInitialDataInfiniteOptions<
  * @see {@link useInfiniteQuery} to run an infinite query with these options.
  * @param options - The {@link DefinedInitialDataInfiniteOptions} to use — everything you can pass to `useInfiniteQuery`, with `initialData` set.
  * @returns The same options object, typed so that `queryKey` carries the inferred data type.
+ * @remarks The example below fetches the next page from a button click. See {@link useInfiniteQuery} for a
+ * version that fetches automatically as the user scrolls.
  *
  * @example
  * ```tsx
@@ -167,9 +169,6 @@ export type DefinedInitialDataInfiniteOptions<
  *   )
  * }
  * ```
- *
- * See {@link useInfiniteQuery} for an example that fetches the next page automatically as the
- * user scrolls, instead of on a button click.
  */
 export function infiniteQueryOptions<
   TQueryFnData,
@@ -200,6 +199,8 @@ export function infiniteQueryOptions<
  * `options.queryKey` is required and is the query key to generate options for.
  *
  * @returns The same options object, typed so that `queryKey` carries the inferred data type.
+ * @remarks The first example below fetches the next page from a button click. See {@link useInfiniteQuery}
+ * for a version that fetches automatically as the user scrolls.
  *
  * @example
  * ```tsx
@@ -232,9 +233,6 @@ export function infiniteQueryOptions<
  * }
  * ```
  *
- * See {@link useInfiniteQuery} for an example that fetches the next page automatically as the
- * user scrolls, instead of on a button click.
- *
  * @example
  * A parameterized factory, reused across a hook and an imperative call with the same cache entry:
  * ```tsx
@@ -301,6 +299,8 @@ export function infiniteQueryOptions<
  * `options.queryKey` is required and is the query key to generate options for.
  *
  * @returns The same options object, typed so that `queryKey` carries the inferred data type.
+ * @remarks The first example below fetches the next page from a button click. See {@link useInfiniteQuery}
+ * for a version that fetches automatically as the user scrolls.
  *
  * @example
  * ```tsx
@@ -333,9 +333,6 @@ export function infiniteQueryOptions<
  * }
  * ```
  *
- * See {@link useInfiniteQuery} for an example that fetches the next page automatically as the
- * user scrolls, instead of on a button click.
- *
  * @example
  * A parameterized factory, reused across a hook and an imperative call with the same cache entry:
  * ```tsx
diff --git a/packages/preact-query/src/useInfiniteQuery.ts b/packages/preact-query/src/useInfiniteQuery.ts
index fbc6afb81b..1be82049ba 100644
--- a/packages/preact-query/src/useInfiniteQuery.ts
+++ b/packages/preact-query/src/useInfiniteQuery.ts
@@ -101,27 +101,35 @@ export function useInfiniteQuery<
  * import { useEffect, useRef } from 'preact/hooks'
  *
  * function Projects() {
- *   const { data, isPending, isError, error, fetchNextPage, hasNextPage, isFetchingNextPage } =
- *     useInfiniteQuery({
- *       queryKey: ['projects'],
- *       queryFn: ({ pageParam }) => fetchProjects(pageParam),
- *       initialPageParam: 0,
- *       getNextPageParam: (lastPage) => lastPage.nextId,
- *     })
+ *   const {
+ *     data,
+ *     isPending,
+ *     isError,
+ *     error,
+ *     fetchNextPage,
+ *     hasNextPage,
+ *     isFetching,
+ *     isFetchingNextPage,
+ *   } = useInfiniteQuery({
+ *     queryKey: ['projects'],
+ *     queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *     initialPageParam: 0,
+ *     getNextPageParam: (lastPage) => lastPage.nextId,
+ *   })
  *
  *   const sentinelRef = useRef<HTMLDivElement>(null)
  *
  *   useEffect(() => {
  *     const sentinel = sentinelRef.current
- *     if (sentinel == null || !hasNextPage) return
+ *     if (sentinel == null || !hasNextPage || isFetching) return
  *
  *     const observer = new IntersectionObserver(([entry]) => {
- *       if (entry.isIntersecting) fetchNextPage()
+ *       if (entry?.isIntersecting) fetchNextPage()
  *     })
  *     observer.observe(sentinel)
  *
  *     return () => observer.disconnect()
- *   }, [hasNextPage, fetchNextPage])
+ *   }, [hasNextPage, isFetching, fetchNextPage])
  *
  *   if (isPending) return 'Loading...'
  *   if (isError) return <span>Error: {error.message}</span>
@@ -179,27 +187,35 @@ export function useInfiniteQuery<
  * import { useEffect, useRef } from 'preact/hooks'
  *
  * function Projects() {
- *   const { data, isPending, isError, error, fetchNextPage, hasNextPage, isFetchingNextPage } =
- *     useInfiniteQuery({
- *       queryKey: ['projects'],
- *       queryFn: ({ pageParam }) => fetchProjects(pageParam),
- *       initialPageParam: 0,
- *       getNextPageParam: (lastPage) => lastPage.nextId,
- *     })
+ *   const {
+ *     data,
+ *     isPending,
+ *     isError,
+ *     error,
+ *     fetchNextPage,
+ *     hasNextPage,
+ *     isFetching,
+ *     isFetchingNextPage,
+ *   } = useInfiniteQuery({
+ *     queryKey: ['projects'],
+ *     queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *     initialPageParam: 0,
+ *     getNextPageParam: (lastPage) => lastPage.nextId,
+ *   })
  *
  *   const sentinelRef = useRef<HTMLDivElement>(null)
  *
  *   useEffect(() => {
  *     const sentinel = sentinelRef.current
- *     if (sentinel == null || !hasNextPage) return
+ *     if (sentinel == null || !hasNextPage || isFetching) return
  *
  *     const observer = new IntersectionObserver(([entry]) => {
- *       if (entry.isIntersecting) fetchNextPage()
+ *       if (entry?.isIntersecting) fetchNextPage()
  *     })
  *     observer.observe(sentinel)
  *
  *     return () => observer.disconnect()
- *   }, [hasNextPage, fetchNextPage])
+ *   }, [hasNextPage, isFetching, fetchNextPage])
  *
  *   if (isPending) return 'Loading...'
  *   if (isError) return <span>Error: {error.message}</span>

From 0c2834e270085a2c0f5fd31af9ab19a477d96c2b Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Sun, 30 Aug 2026 12:08:31 +0900
Subject: [PATCH 25/30] docs(preact-query): move duplicated usage examples from
 'queryOptions'/'infiniteQueryOptions' into their hooks

---
 .../functions/infiniteQueryOptions.md         | 123 ++----------------
 .../reference/functions/queryOptions.md       |  61 +++------
 .../reference/functions/useInfiniteQuery.md   |  82 +++++++++++-
 .../preact-query/src/infiniteQueryOptions.ts  | 116 +----------------
 packages/preact-query/src/queryOptions.ts     |  52 +-------
 packages/preact-query/src/useInfiniteQuery.ts |  78 +++++++++++
 6 files changed, 198 insertions(+), 314 deletions(-)

diff --git a/docs/framework/preact/reference/functions/infiniteQueryOptions.md b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
index a003d6144b..c7c714edea 100644
--- a/docs/framework/preact/reference/functions/infiniteQueryOptions.md
+++ b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
@@ -9,7 +9,7 @@ title: infiniteQueryOptions
 function infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options): UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & object & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData, unknown>, TError>;
 ```
 
-Defined in: [preact-query/src/infiniteQueryOptions.ts:173](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L173)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:169](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L169)
 
 You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
 These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
@@ -57,8 +57,8 @@ The same options object, typed so that `queryKey` carries the inferred data type
 
 ### Remarks
 
-The example below fetches the next page from a button click. See [useInfiniteQuery](useInfiniteQuery.md) for a
-version that fetches automatically as the user scrolls.
+See [useInfiniteQuery](useInfiniteQuery.md) for examples that fetch further pages, from a button click or
+automatically as the user scrolls.
 
 ### Example
 
@@ -76,8 +76,7 @@ export const projectsOptions = infiniteQueryOptions({
 function Projects() {
   // `data` is never `undefined`, thanks to `initialData` — even if a refetch fails, so the
   // list stays visible alongside the error.
-  const { data, isError, error, fetchNextPage, hasNextPage } =
-    useInfiniteQuery(projectsOptions)
+  const { data, isError, error } = useInfiniteQuery(projectsOptions)
 
   return (
     <div>
@@ -85,9 +84,6 @@ function Projects() {
       <ul>
         {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
       </ul>
-      {hasNextPage ? (
-        <button onClick={() => fetchNextPage()}>Load More</button>
-      ) : null}
     </div>
   )
 }
@@ -99,7 +95,7 @@ function Projects() {
 function infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options): OmitKeyof<UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, "queryFn"> & object & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData, unknown>, TError>;
 ```
 
-Defined in: [preact-query/src/infiniteQueryOptions.ts:273](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L273)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:238](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L238)
 
 You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
 These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
@@ -141,40 +137,10 @@ The same options object, typed so that `queryKey` carries the inferred data type
 
 ### Remarks
 
-The first example below fetches the next page from a button click. See [useInfiniteQuery](useInfiniteQuery.md)
-for a version that fetches automatically as the user scrolls.
+See [useInfiniteQuery](useInfiniteQuery.md) for examples that fetch further pages, from a button click or
+automatically as the user scrolls.
 
-### Examples
-
-```tsx
-import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
-
-export const projectsOptions = infiniteQueryOptions({
-  queryKey: ['projects'],
-  queryFn: ({ pageParam }) => fetchProjects(pageParam),
-  initialPageParam: 0,
-  getNextPageParam: (lastPage) => lastPage.nextId,
-})
-
-function Projects() {
-  const { data, isPending, isError, error, fetchNextPage, hasNextPage } =
-    useInfiniteQuery(projectsOptions)
-
-  if (isPending) return 'Loading...'
-  if (isError) return <span>Error: {error.message}</span>
-
-  return (
-    <div>
-      <ul>
-        {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
-      </ul>
-      {hasNextPage ? (
-        <button onClick={() => fetchNextPage()}>Load More</button>
-      ) : null}
-    </div>
-  )
-}
-```
+### Example
 
 A parameterized factory, reused across a hook and an imperative call with the same cache entry:
 ```tsx
@@ -219,7 +185,7 @@ queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
 function infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options): UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & object & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData, unknown>, TError>;
 ```
 
-Defined in: [preact-query/src/infiniteQueryOptions.ts:409](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L409)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:307](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L307)
 
 You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
 These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
@@ -261,40 +227,10 @@ The same options object, typed so that `queryKey` carries the inferred data type
 
 ### Remarks
 
-The first example below fetches the next page from a button click. See [useInfiniteQuery](useInfiniteQuery.md)
-for a version that fetches automatically as the user scrolls.
-
-### Examples
-
-```tsx
-import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
-
-export const projectsOptions = infiniteQueryOptions({
-  queryKey: ['projects'],
-  queryFn: ({ pageParam }) => fetchProjects(pageParam),
-  initialPageParam: 0,
-  getNextPageParam: (lastPage) => lastPage.nextId,
-})
-
-function Projects() {
-  const { data, isPending, isError, error, fetchNextPage, hasNextPage } =
-    useInfiniteQuery(projectsOptions)
-
-  if (isPending) return 'Loading...'
-  if (isError) return <span>Error: {error.message}</span>
+See [useInfiniteQuery](useInfiniteQuery.md) for examples that fetch further pages (from a button click or
+automatically as the user scrolls) and that use `skipToken` to disable the query until `postId` is set.
 
-  return (
-    <div>
-      <ul>
-        {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
-      </ul>
-      {hasNextPage ? (
-        <button onClick={() => fetchNextPage()}>Load More</button>
-      ) : null}
-    </div>
-  )
-}
-```
+### Example
 
 A parameterized factory, reused across a hook and an imperative call with the same cache entry:
 ```tsx
@@ -329,41 +265,6 @@ const postId = '1'
 queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
 ```
 
-A factory that disables the query, type safe, until `postId` is set:
-```tsx
-import {
-  infiniteQueryOptions,
-  skipToken,
-  useInfiniteQuery,
-} from '@tanstack/preact-query'
-
-export const commentsOptions = (postId: string | undefined) =>
-  infiniteQueryOptions({
-    queryKey: ['post', postId, 'comments'],
-    queryFn:
-      postId != null
-        ? ({ pageParam }) => fetchComments(postId, pageParam)
-        : skipToken,
-    initialPageParam: 0,
-    getNextPageParam: (lastPage) => lastPage.nextId,
-  })
-
-function Comments({ postId }: { postId: string | undefined }) {
-  // Use `isLoading`, not `isPending`, so the loading state doesn't show while the query is disabled.
-  const { data, isLoading, isError, error } = useInfiniteQuery(commentsOptions(postId))
-
-  if (postId == null) return 'Select a post'
-  if (isLoading) return 'Loading...'
-  if (isError) return <span>Error: {error.message}</span>
-
-  return (
-    <ul>
-      {data?.pages.map((page) => page.comments.map((c) => <li key={c.id}>{c.text}</li>))}
-    </ul>
-  )
-}
-```
-
 ### See
 
 [useInfiniteQuery](useInfiniteQuery.md) to run an infinite query with these options.
diff --git a/docs/framework/preact/reference/functions/queryOptions.md b/docs/framework/preact/reference/functions/queryOptions.md
index 3ca9efb150..672ca16cca 100644
--- a/docs/framework/preact/reference/functions/queryOptions.md
+++ b/docs/framework/preact/reference/functions/queryOptions.md
@@ -9,7 +9,7 @@ title: queryOptions
 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](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L140)
+Defined in: [preact-query/src/queryOptions.ts:142](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L142)
 
 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
@@ -51,6 +51,11 @@ The same options object, typed so that `queryKey` carries the inferred data type
 
 [useQuery](useQuery.md) to run a query with these options.
 
+### Remarks
+
+See [useQuery](useQuery.md) for more usage patterns — this factory works the same regardless of which
+overload you use.
+
 ### Example
 
 ```tsx
@@ -84,7 +89,7 @@ function Posts() {
 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:234](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L234)
+Defined in: [preact-query/src/queryOptions.ts:215](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L215)
 
 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
@@ -124,29 +129,12 @@ The same options object, typed so that `queryKey` carries the inferred data type
 
 [useQuery](useQuery.md) to run a query with these options.
 
-### Examples
+### Remarks
 
-```tsx
-import { queryOptions, useQuery } from '@tanstack/preact-query'
+See [useQuery](useQuery.md) for more usage patterns — this factory works the same regardless of which
+overload you use.
 
-export const postsOptions = queryOptions({
-  queryKey: ['posts'],
-  queryFn: fetchPosts,
-})
-
-function Posts() {
-  const { data, isPending, isError, error } = useQuery(postsOptions)
-
-  if (isPending) return 'Loading...'
-  if (isError) return <span>Error: {error.message}</span>
-
-  return (
-    <ul>
-      {data.map((post) => <li key={post.id}>{post.title}</li>)}
-    </ul>
-  )
-}
-```
+### Examples
 
 A parameterized factory, reused across a hook and an imperative call with the same cache entry:
 ```tsx
@@ -204,7 +192,7 @@ queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefi
 function queryOptions<TQueryFnData, TError, TData, TQueryKey>(options): UseQueryOptions<TQueryFnData, TError, TData, TQueryKey> & object & QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>;
 ```
 
-Defined in: [preact-query/src/queryOptions.ts:350](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L350)
+Defined in: [preact-query/src/queryOptions.ts:310](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L310)
 
 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
@@ -244,29 +232,12 @@ The same options object, typed so that `queryKey` carries the inferred data type
 
 [useQuery](useQuery.md) to run a query with these options.
 
-### Examples
-
-```tsx
-import { queryOptions, useQuery } from '@tanstack/preact-query'
+### Remarks
 
-export const postsOptions = queryOptions({
-  queryKey: ['posts'],
-  queryFn: fetchPosts,
-})
-
-function Posts() {
-  const { data, isPending, isError, error } = useQuery(postsOptions)
+See [useQuery](useQuery.md) for more usage patterns — this factory works the same regardless of which
+overload you use. This is the only overload that accepts `queryFn: skipToken`, shown below.
 
-  if (isPending) return 'Loading...'
-  if (isError) return <span>Error: {error.message}</span>
-
-  return (
-    <ul>
-      {data.map((post) => <li key={post.id}>{post.title}</li>)}
-    </ul>
-  )
-}
-```
+### Examples
 
 A parameterized factory, reused across a hook and an imperative call with the same cache entry:
 ```tsx
diff --git a/docs/framework/preact/reference/functions/useInfiniteQuery.md b/docs/framework/preact/reference/functions/useInfiniteQuery.md
index f7dcb324ae..2075ddfc47 100644
--- a/docs/framework/preact/reference/functions/useInfiniteQuery.md
+++ b/docs/framework/preact/reference/functions/useInfiniteQuery.md
@@ -104,7 +104,7 @@ function Projects() {
 function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): UseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useInfiniteQuery.ts:150](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L150)
+Defined in: [preact-query/src/useInfiniteQuery.ts:189](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L189)
 
 The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
 `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
@@ -164,7 +164,45 @@ actions, or add conditions like `hasNextPage && !isFetching`.
 
 [infiniteQueryOptions](infiniteQueryOptions.md) to share these options between `useInfiniteQuery` and imperative APIs like `queryClient.infiniteQuery`.
 
-### Example
+### Examples
+
+Fetching the next page from a "Load More" button click:
+```tsx
+import { useInfiniteQuery } from '@tanstack/preact-query'
+
+function Projects() {
+  const { data, isPending, isError, error, fetchNextPage, hasNextPage, isFetching, isFetchingNextPage } =
+    useInfiniteQuery({
+      queryKey: ['projects'],
+      queryFn: ({ pageParam }) => fetchProjects(pageParam),
+      initialPageParam: 0,
+      getNextPageParam: (lastPage) => lastPage.nextId,
+    })
+
+  if (isPending) return 'Loading...'
+  if (isError) return <span>Error: {error.message}</span>
+
+  return (
+    <>
+      <ul>
+        {data.pages.map((page) =>
+          page.projects.map((project) => <li key={project.id}>{project.name}</li>),
+        )}
+      </ul>
+      <button
+        onClick={() => fetchNextPage()}
+        disabled={!hasNextPage || isFetching}
+      >
+        {isFetchingNextPage
+          ? 'Loading more...'
+          : hasNextPage
+            ? 'Load More'
+            : 'Nothing more to load'}
+      </button>
+    </>
+  )
+}
+```
 
 Fetching the next page automatically as the user scrolls, using an `IntersectionObserver` on a
 sentinel element after the list:
@@ -225,7 +263,7 @@ function Projects() {
 function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): UseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useInfiniteQuery.ts:310](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L310)
+Defined in: [preact-query/src/useInfiniteQuery.ts:388](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L388)
 
 The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
 `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
@@ -287,6 +325,44 @@ actions, or add conditions like `hasNextPage && !isFetching`.
 
 ### Examples
 
+Fetching the next page from a "Load More" button click:
+```tsx
+import { useInfiniteQuery } from '@tanstack/preact-query'
+
+function Projects() {
+  const { data, isPending, isError, error, fetchNextPage, hasNextPage, isFetching, isFetchingNextPage } =
+    useInfiniteQuery({
+      queryKey: ['projects'],
+      queryFn: ({ pageParam }) => fetchProjects(pageParam),
+      initialPageParam: 0,
+      getNextPageParam: (lastPage) => lastPage.nextId,
+    })
+
+  if (isPending) return 'Loading...'
+  if (isError) return <span>Error: {error.message}</span>
+
+  return (
+    <>
+      <ul>
+        {data.pages.map((page) =>
+          page.projects.map((project) => <li key={project.id}>{project.name}</li>),
+        )}
+      </ul>
+      <button
+        onClick={() => fetchNextPage()}
+        disabled={!hasNextPage || isFetching}
+      >
+        {isFetchingNextPage
+          ? 'Loading more...'
+          : hasNextPage
+            ? 'Load More'
+            : 'Nothing more to load'}
+      </button>
+    </>
+  )
+}
+```
+
 Fetching the next page automatically as the user scrolls, using an `IntersectionObserver` on a
 sentinel element after the list:
 ```tsx
diff --git a/packages/preact-query/src/infiniteQueryOptions.ts b/packages/preact-query/src/infiniteQueryOptions.ts
index 984ce62564..3a61ecfe7a 100644
--- a/packages/preact-query/src/infiniteQueryOptions.ts
+++ b/packages/preact-query/src/infiniteQueryOptions.ts
@@ -135,8 +135,8 @@ export type DefinedInitialDataInfiniteOptions<
  * @see {@link useInfiniteQuery} to run an infinite query with these options.
  * @param options - The {@link DefinedInitialDataInfiniteOptions} to use — everything you can pass to `useInfiniteQuery`, with `initialData` set.
  * @returns The same options object, typed so that `queryKey` carries the inferred data type.
- * @remarks The example below fetches the next page from a button click. See {@link useInfiniteQuery} for a
- * version that fetches automatically as the user scrolls.
+ * @remarks See {@link useInfiniteQuery} for examples that fetch further pages, from a button click or
+ * automatically as the user scrolls.
  *
  * @example
  * ```tsx
@@ -153,8 +153,7 @@ export type DefinedInitialDataInfiniteOptions<
  * function Projects() {
  *   // `data` is never `undefined`, thanks to `initialData` — even if a refetch fails, so the
  *   // list stays visible alongside the error.
- *   const { data, isError, error, fetchNextPage, hasNextPage } =
- *     useInfiniteQuery(projectsOptions)
+ *   const { data, isError, error } = useInfiniteQuery(projectsOptions)
  *
  *   return (
  *     <div>
@@ -162,9 +161,6 @@ export type DefinedInitialDataInfiniteOptions<
  *       <ul>
  *         {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
  *       </ul>
- *       {hasNextPage ? (
- *         <button onClick={() => fetchNextPage()}>Load More</button>
- *       ) : null}
  *     </div>
  *   )
  * }
@@ -199,39 +195,8 @@ export function infiniteQueryOptions<
  * `options.queryKey` is required and is the query key to generate options for.
  *
  * @returns The same options object, typed so that `queryKey` carries the inferred data type.
- * @remarks The first example below fetches the next page from a button click. See {@link useInfiniteQuery}
- * for a version that fetches automatically as the user scrolls.
- *
- * @example
- * ```tsx
- * import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
- *
- * export const projectsOptions = infiniteQueryOptions({
- *   queryKey: ['projects'],
- *   queryFn: ({ pageParam }) => fetchProjects(pageParam),
- *   initialPageParam: 0,
- *   getNextPageParam: (lastPage) => lastPage.nextId,
- * })
- *
- * function Projects() {
- *   const { data, isPending, isError, error, fetchNextPage, hasNextPage } =
- *     useInfiniteQuery(projectsOptions)
- *
- *   if (isPending) return 'Loading...'
- *   if (isError) return <span>Error: {error.message}</span>
- *
- *   return (
- *     <div>
- *       <ul>
- *         {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
- *       </ul>
- *       {hasNextPage ? (
- *         <button onClick={() => fetchNextPage()}>Load More</button>
- *       ) : null}
- *     </div>
- *   )
- * }
- * ```
+ * @remarks See {@link useInfiniteQuery} for examples that fetch further pages, from a button click or
+ * automatically as the user scrolls.
  *
  * @example
  * A parameterized factory, reused across a hook and an imperative call with the same cache entry:
@@ -299,39 +264,8 @@ export function infiniteQueryOptions<
  * `options.queryKey` is required and is the query key to generate options for.
  *
  * @returns The same options object, typed so that `queryKey` carries the inferred data type.
- * @remarks The first example below fetches the next page from a button click. See {@link useInfiniteQuery}
- * for a version that fetches automatically as the user scrolls.
- *
- * @example
- * ```tsx
- * import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
- *
- * export const projectsOptions = infiniteQueryOptions({
- *   queryKey: ['projects'],
- *   queryFn: ({ pageParam }) => fetchProjects(pageParam),
- *   initialPageParam: 0,
- *   getNextPageParam: (lastPage) => lastPage.nextId,
- * })
- *
- * function Projects() {
- *   const { data, isPending, isError, error, fetchNextPage, hasNextPage } =
- *     useInfiniteQuery(projectsOptions)
- *
- *   if (isPending) return 'Loading...'
- *   if (isError) return <span>Error: {error.message}</span>
- *
- *   return (
- *     <div>
- *       <ul>
- *         {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
- *       </ul>
- *       {hasNextPage ? (
- *         <button onClick={() => fetchNextPage()}>Load More</button>
- *       ) : null}
- *     </div>
- *   )
- * }
- * ```
+ * @remarks See {@link useInfiniteQuery} for examples that fetch further pages (from a button click or
+ * automatically as the user scrolls) and that use `skipToken` to disable the query until `postId` is set.
  *
  * @example
  * A parameterized factory, reused across a hook and an imperative call with the same cache entry:
@@ -367,42 +301,6 @@ export function infiniteQueryOptions<
  * queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
  * ```
  *
- * @example
- * A factory that disables the query, type safe, until `postId` is set:
- * ```tsx
- * import {
- *   infiniteQueryOptions,
- *   skipToken,
- *   useInfiniteQuery,
- * } from '@tanstack/preact-query'
- *
- * export const commentsOptions = (postId: string | undefined) =>
- *   infiniteQueryOptions({
- *     queryKey: ['post', postId, 'comments'],
- *     queryFn:
- *       postId != null
- *         ? ({ pageParam }) => fetchComments(postId, pageParam)
- *         : skipToken,
- *     initialPageParam: 0,
- *     getNextPageParam: (lastPage) => lastPage.nextId,
- *   })
- *
- * function Comments({ postId }: { postId: string | undefined }) {
- *   // Use `isLoading`, not `isPending`, so the loading state doesn't show while the query is disabled.
- *   const { data, isLoading, isError, error } = useInfiniteQuery(commentsOptions(postId))
- *
- *   if (postId == null) return 'Select a post'
- *   if (isLoading) return 'Loading...'
- *   if (isError) return <span>Error: {error.message}</span>
- *
- *   return (
- *     <ul>
- *       {data?.pages.map((page) => page.comments.map((c) => <li key={c.id}>{c.text}</li>))}
- *     </ul>
- *   )
- * }
- * ```
- *
  * @see {@link useInfiniteQuery} to run an infinite query with these options.
  * @param options - The {@link UndefinedInitialDataInfiniteOptions} to use — everything you can pass to `useInfiniteQuery`.
  */
diff --git a/packages/preact-query/src/queryOptions.ts b/packages/preact-query/src/queryOptions.ts
index a090606c96..b55ca0e14e 100644
--- a/packages/preact-query/src/queryOptions.ts
+++ b/packages/preact-query/src/queryOptions.ts
@@ -110,6 +110,8 @@ export type DefinedInitialDataOptions<
  * @see {@link useQuery} to run a query with these options.
  * @param options - The {@link 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.
+ * @remarks See {@link useQuery} for more usage patterns — this factory works the same regardless of which
+ * overload you use.
  *
  * @example
  * ```tsx
@@ -155,29 +157,8 @@ export function queryOptions<
  * @see {@link useQuery} to run a query with these options.
  * @param options - The {@link UnusedSkipTokenOptions} to use — everything you can pass to `useQuery`.
  * @returns The same options object, typed so that `queryKey` carries the inferred data type.
- *
- * @example
- * ```tsx
- * import { queryOptions, useQuery } from '@tanstack/preact-query'
- *
- * export const postsOptions = queryOptions({
- *   queryKey: ['posts'],
- *   queryFn: fetchPosts,
- * })
- *
- * function Posts() {
- *   const { data, isPending, isError, error } = useQuery(postsOptions)
- *
- *   if (isPending) return 'Loading...'
- *   if (isError) return <span>Error: {error.message}</span>
- *
- *   return (
- *     <ul>
- *       {data.map((post) => <li key={post.id}>{post.title}</li>)}
- *     </ul>
- *   )
- * }
- * ```
+ * @remarks See {@link useQuery} for more usage patterns — this factory works the same regardless of which
+ * overload you use.
  *
  * @example
  * A parameterized factory, reused across a hook and an imperative call with the same cache entry:
@@ -249,29 +230,8 @@ export function queryOptions<
  * @see {@link useQuery} to run a query with these options.
  * @param options - The {@link UndefinedInitialDataOptions} to use — everything you can pass to `useQuery`.
  * @returns The same options object, typed so that `queryKey` carries the inferred data type.
- *
- * @example
- * ```tsx
- * import { queryOptions, useQuery } from '@tanstack/preact-query'
- *
- * export const postsOptions = queryOptions({
- *   queryKey: ['posts'],
- *   queryFn: fetchPosts,
- * })
- *
- * function Posts() {
- *   const { data, isPending, isError, error } = useQuery(postsOptions)
- *
- *   if (isPending) return 'Loading...'
- *   if (isError) return <span>Error: {error.message}</span>
- *
- *   return (
- *     <ul>
- *       {data.map((post) => <li key={post.id}>{post.title}</li>)}
- *     </ul>
- *   )
- * }
- * ```
+ * @remarks See {@link useQuery} for more usage patterns — this factory works the same regardless of which
+ * overload you use. This is the only overload that accepts `queryFn: skipToken`, shown below.
  *
  * @example
  * A parameterized factory, reused across a hook and an imperative call with the same cache entry:
diff --git a/packages/preact-query/src/useInfiniteQuery.ts b/packages/preact-query/src/useInfiniteQuery.ts
index 1be82049ba..2026ce0511 100644
--- a/packages/preact-query/src/useInfiniteQuery.ts
+++ b/packages/preact-query/src/useInfiniteQuery.ts
@@ -94,6 +94,45 @@ export function useInfiniteQuery<
  * `isFetchingPreviousPage`.
  *
  * @example
+ * Fetching the next page from a "Load More" button click:
+ * ```tsx
+ * import { useInfiniteQuery } from '@tanstack/preact-query'
+ *
+ * function Projects() {
+ *   const { data, isPending, isError, error, fetchNextPage, hasNextPage, isFetching, isFetchingNextPage } =
+ *     useInfiniteQuery({
+ *       queryKey: ['projects'],
+ *       queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *       initialPageParam: 0,
+ *       getNextPageParam: (lastPage) => lastPage.nextId,
+ *     })
+ *
+ *   if (isPending) return 'Loading...'
+ *   if (isError) return <span>Error: {error.message}</span>
+ *
+ *   return (
+ *     <>
+ *       <ul>
+ *         {data.pages.map((page) =>
+ *           page.projects.map((project) => <li key={project.id}>{project.name}</li>),
+ *         )}
+ *       </ul>
+ *       <button
+ *         onClick={() => fetchNextPage()}
+ *         disabled={!hasNextPage || isFetching}
+ *       >
+ *         {isFetchingNextPage
+ *           ? 'Loading more...'
+ *           : hasNextPage
+ *             ? 'Load More'
+ *             : 'Nothing more to load'}
+ *       </button>
+ *     </>
+ *   )
+ * }
+ * ```
+ *
+ * @example
  * Fetching the next page automatically as the user scrolls, using an `IntersectionObserver` on a
  * sentinel element after the list:
  * ```tsx
@@ -180,6 +219,45 @@ export function useInfiniteQuery<
  * `isFetchingPreviousPage`.
  *
  * @example
+ * Fetching the next page from a "Load More" button click:
+ * ```tsx
+ * import { useInfiniteQuery } from '@tanstack/preact-query'
+ *
+ * function Projects() {
+ *   const { data, isPending, isError, error, fetchNextPage, hasNextPage, isFetching, isFetchingNextPage } =
+ *     useInfiniteQuery({
+ *       queryKey: ['projects'],
+ *       queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *       initialPageParam: 0,
+ *       getNextPageParam: (lastPage) => lastPage.nextId,
+ *     })
+ *
+ *   if (isPending) return 'Loading...'
+ *   if (isError) return <span>Error: {error.message}</span>
+ *
+ *   return (
+ *     <>
+ *       <ul>
+ *         {data.pages.map((page) =>
+ *           page.projects.map((project) => <li key={project.id}>{project.name}</li>),
+ *         )}
+ *       </ul>
+ *       <button
+ *         onClick={() => fetchNextPage()}
+ *         disabled={!hasNextPage || isFetching}
+ *       >
+ *         {isFetchingNextPage
+ *           ? 'Loading more...'
+ *           : hasNextPage
+ *             ? 'Load More'
+ *             : 'Nothing more to load'}
+ *       </button>
+ *     </>
+ *   )
+ * }
+ * ```
+ *
+ * @example
  * Fetching the next page automatically as the user scrolls, using an `IntersectionObserver` on a
  * sentinel element after the list:
  * ```tsx

From 323487c28d309ae0b117979c0aa7692bcc38bb73 Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Sun, 30 Aug 2026 12:14:38 +0900
Subject: [PATCH 26/30] docs(preact-query): remove duplicated basic-mutation
 example from 'mutationOptions', trim boilerplate '@remarks'

---
 .../reference/functions/mutationOptions.md    | 25 ++++++-------------
 .../reference/functions/queryOptions.md       | 19 +++-----------
 packages/preact-query/src/mutationOptions.ts  | 17 ++-----------
 packages/preact-query/src/queryOptions.ts     |  7 +-----
 4 files changed, 15 insertions(+), 53 deletions(-)

diff --git a/docs/framework/preact/reference/functions/mutationOptions.md b/docs/framework/preact/reference/functions/mutationOptions.md
index 8d2e39f62a..018495b962 100644
--- a/docs/framework/preact/reference/functions/mutationOptions.md
+++ b/docs/framework/preact/reference/functions/mutationOptions.md
@@ -9,7 +9,7 @@ title: mutationOptions
 function mutationOptions<TData, TError, TVariables, TOnMutateResult>(options): WithRequired<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">;
 ```
 
-Defined in: [preact-query/src/mutationOptions.ts:49](https://github.com/TanStack/query/blob/main/packages/preact-query/src/mutationOptions.ts#L49)
+Defined in: [preact-query/src/mutationOptions.ts:34](https://github.com/TanStack/query/blob/main/packages/preact-query/src/mutationOptions.ts#L34)
 
 You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. A
 `mutationKey` is required on this overload so the mutation can be looked up later, e.g. with
@@ -52,21 +52,7 @@ The same options object, unchanged.
 
 [useMutation](useMutation.md) to run the mutation these options describe.
 
-### Examples
-
-```tsx
-import { mutationOptions, useMutation } from '@tanstack/preact-query'
-
-export const createPostOptions = mutationOptions({
-  mutationKey: ['posts', 'create'],
-  mutationFn: createPost,
-})
-
-function CreatePost() {
-  const mutation = useMutation(createPostOptions)
-  return <button onClick={() => mutation.mutate({ title: 'Hello' })}>Create</button>
-}
-```
+### Example
 
 Looking the mutation up elsewhere via its `mutationKey`, e.g. for a global "saving…" indicator:
 ```tsx
@@ -92,7 +78,7 @@ function SavingIndicator() {
 function mutationOptions<TData, TError, TVariables, TOnMutateResult>(options): Omit<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">;
 ```
 
-Defined in: [preact-query/src/mutationOptions.ts:87](https://github.com/TanStack/query/blob/main/packages/preact-query/src/mutationOptions.ts#L87)
+Defined in: [preact-query/src/mutationOptions.ts:74](https://github.com/TanStack/query/blob/main/packages/preact-query/src/mutationOptions.ts#L74)
 
 You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. No
 `mutationKey` is required on this overload — use this when you don't need to look the mutation up later
@@ -135,6 +121,11 @@ The same options object, unchanged.
 
 [useMutation](useMutation.md) to run the mutation these options describe.
 
+### Remarks
+
+Without a `mutationKey`, the mutation can't be looked up elsewhere via `useMutationState` — see
+the other overload's example for that.
+
 ### Example
 
 ```tsx
diff --git a/docs/framework/preact/reference/functions/queryOptions.md b/docs/framework/preact/reference/functions/queryOptions.md
index 672ca16cca..adc0d5f8e9 100644
--- a/docs/framework/preact/reference/functions/queryOptions.md
+++ b/docs/framework/preact/reference/functions/queryOptions.md
@@ -9,7 +9,7 @@ title: queryOptions
 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:142](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L142)
+Defined in: [preact-query/src/queryOptions.ts:140](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L140)
 
 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
@@ -51,11 +51,6 @@ The same options object, typed so that `queryKey` carries the inferred data type
 
 [useQuery](useQuery.md) to run a query with these options.
 
-### Remarks
-
-See [useQuery](useQuery.md) for more usage patterns — this factory works the same regardless of which
-overload you use.
-
 ### Example
 
 ```tsx
@@ -89,7 +84,7 @@ function Posts() {
 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:215](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L215)
+Defined in: [preact-query/src/queryOptions.ts:211](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L211)
 
 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
@@ -129,11 +124,6 @@ The same options object, typed so that `queryKey` carries the inferred data type
 
 [useQuery](useQuery.md) to run a query with these options.
 
-### Remarks
-
-See [useQuery](useQuery.md) for more usage patterns — this factory works the same regardless of which
-overload you use.
-
 ### Examples
 
 A parameterized factory, reused across a hook and an imperative call with the same cache entry:
@@ -192,7 +182,7 @@ queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefi
 function queryOptions<TQueryFnData, TError, TData, TQueryKey>(options): UseQueryOptions<TQueryFnData, TError, TData, TQueryKey> & object & QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>;
 ```
 
-Defined in: [preact-query/src/queryOptions.ts:310](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L310)
+Defined in: [preact-query/src/queryOptions.ts:305](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L305)
 
 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
@@ -234,8 +224,7 @@ The same options object, typed so that `queryKey` carries the inferred data type
 
 ### Remarks
 
-See [useQuery](useQuery.md) for more usage patterns — this factory works the same regardless of which
-overload you use. This is the only overload that accepts `queryFn: skipToken`, shown below.
+This is the only overload that accepts `queryFn: skipToken`, shown below.
 
 ### Examples
 
diff --git a/packages/preact-query/src/mutationOptions.ts b/packages/preact-query/src/mutationOptions.ts
index 8763b4d903..3b9cf445d0 100644
--- a/packages/preact-query/src/mutationOptions.ts
+++ b/packages/preact-query/src/mutationOptions.ts
@@ -13,21 +13,6 @@ import type { UseMutationOptions } from './types'
  * @returns The same options object, unchanged.
  *
  * @example
- * ```tsx
- * import { mutationOptions, useMutation } from '@tanstack/preact-query'
- *
- * export const createPostOptions = mutationOptions({
- *   mutationKey: ['posts', 'create'],
- *   mutationFn: createPost,
- * })
- *
- * function CreatePost() {
- *   const mutation = useMutation(createPostOptions)
- *   return <button onClick={() => mutation.mutate({ title: 'Hello' })}>Create</button>
- * }
- * ```
- *
- * @example
  * Looking the mutation up elsewhere via its `mutationKey`, e.g. for a global "saving…" indicator:
  * ```tsx
  * import { mutationOptions, useMutationState } from '@tanstack/preact-query'
@@ -69,6 +54,8 @@ export function mutationOptions<
  * @param options - The mutation options to use, identical to what you'd pass to `useMutation`, without a
  * `mutationKey`.
  * @returns The same options object, unchanged.
+ * @remarks Without a `mutationKey`, the mutation can't be looked up elsewhere via `useMutationState` — see
+ * the other overload's example for that.
  *
  * @example
  * ```tsx
diff --git a/packages/preact-query/src/queryOptions.ts b/packages/preact-query/src/queryOptions.ts
index b55ca0e14e..fd04d84a49 100644
--- a/packages/preact-query/src/queryOptions.ts
+++ b/packages/preact-query/src/queryOptions.ts
@@ -110,8 +110,6 @@ export type DefinedInitialDataOptions<
  * @see {@link useQuery} to run a query with these options.
  * @param options - The {@link 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.
- * @remarks See {@link useQuery} for more usage patterns — this factory works the same regardless of which
- * overload you use.
  *
  * @example
  * ```tsx
@@ -157,8 +155,6 @@ export function queryOptions<
  * @see {@link useQuery} to run a query with these options.
  * @param options - The {@link UnusedSkipTokenOptions} to use — everything you can pass to `useQuery`.
  * @returns The same options object, typed so that `queryKey` carries the inferred data type.
- * @remarks See {@link useQuery} for more usage patterns — this factory works the same regardless of which
- * overload you use.
  *
  * @example
  * A parameterized factory, reused across a hook and an imperative call with the same cache entry:
@@ -230,8 +226,7 @@ export function queryOptions<
  * @see {@link useQuery} to run a query with these options.
  * @param options - The {@link UndefinedInitialDataOptions} to use — everything you can pass to `useQuery`.
  * @returns The same options object, typed so that `queryKey` carries the inferred data type.
- * @remarks See {@link useQuery} for more usage patterns — this factory works the same regardless of which
- * overload you use. This is the only overload that accepts `queryFn: skipToken`, shown below.
+ * @remarks This is the only overload that accepts `queryFn: skipToken`, shown below.
  *
  * @example
  * A parameterized factory, reused across a hook and an imperative call with the same cache entry:

From 53a0114998fe1dd010a5a03e4e2f1a0dcd85d54f Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Sun, 30 Aug 2026 12:18:20 +0900
Subject: [PATCH 27/30] docs(preact-query): add 'combine' example to
 'useSuspenseQueries', link 'useSuspenseInfiniteQuery' to 'useInfiniteQuery'
 and document its waterfall/refetch risks

---
 .../functions/useSuspenseInfiniteQuery.md     | 16 +++++++++-
 .../reference/functions/useSuspenseQueries.md | 31 +++++++++++++++++--
 .../src/useSuspenseInfiniteQuery.ts           |  8 +++++
 .../preact-query/src/useSuspenseQueries.ts    | 28 +++++++++++++++++
 4 files changed, 80 insertions(+), 3 deletions(-)

diff --git a/docs/framework/preact/reference/functions/useSuspenseInfiniteQuery.md b/docs/framework/preact/reference/functions/useSuspenseInfiniteQuery.md
index 571dc5b14d..17429a391c 100644
--- a/docs/framework/preact/reference/functions/useSuspenseInfiniteQuery.md
+++ b/docs/framework/preact/reference/functions/useSuspenseInfiniteQuery.md
@@ -7,7 +7,7 @@ title: useSuspenseInfiniteQuery
 function useSuspenseInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): UseSuspenseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useSuspenseInfiniteQuery.ts:76](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseInfiniteQuery.ts#L76)
+Defined in: [preact-query/src/useSuspenseInfiniteQuery.ts:84](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseInfiniteQuery.ts#L84)
 
 The options for `useSuspenseInfiniteQuery` are the same as for `useInfiniteQuery`, except for `throwOnError`,
 `enabled`, and `placeholderData`.
@@ -59,6 +59,20 @@ The same object as `useInfiniteQuery`, except that `data` is guaranteed to be de
 `isPlaceholderData` is missing, and `status` is either `success` or `error` (with the derived flags set
 accordingly).
 
+## Remarks
+
+Multiple suspenseful query calls (`useSuspenseInfiniteQuery`, `useSuspenseQuery`, etc.) in the
+same component suspend serially, causing a request waterfall — each one blocks rendering until it
+resolves, so the next doesn't even start fetching until then. There's no `useSuspenseInfiniteQueries` to
+parallelize multiple infinite queries the way [useSuspenseQueries](useSuspenseQueries.md) does for regular ones. Also keep
+in mind that imperative fetch calls, such as `fetchNextPage`, may interfere with the default refetch
+behavior, resulting in outdated data. Make sure to call these functions only in response to user actions,
+or add conditions like `hasNextPage && !isFetching`.
+
+## See
+
+[useInfiniteQuery](useInfiniteQuery.md) for the non-Suspense version of this hook.
+
 ## Example
 
 ```tsx
diff --git a/docs/framework/preact/reference/functions/useSuspenseQueries.md b/docs/framework/preact/reference/functions/useSuspenseQueries.md
index 6ab4726a4a..f3a77c96fc 100644
--- a/docs/framework/preact/reference/functions/useSuspenseQueries.md
+++ b/docs/framework/preact/reference/functions/useSuspenseQueries.md
@@ -9,7 +9,7 @@ title: useSuspenseQueries
 function useSuspenseQueries<T, TCombinedResult>(options, queryClient?): TCombinedResult;
 ```
 
-Defined in: [preact-query/src/useSuspenseQueries.ts:264](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseQueries.ts#L264)
+Defined in: [preact-query/src/useSuspenseQueries.ts:292](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseQueries.ts#L292)
 
 The options for `useSuspenseQueries` are the same as for `useQueries`, except that each `query` can't have
 `throwOnError`, `enabled`, or `placeholderData`.
@@ -129,13 +129,40 @@ function App() {
 }
 ```
 
+`combine`s the results into a single boolean, so `Refresh` only re-renders when that boolean changes,
+not on every individual query update. This overload is the only one that accepts `combine`:
+```tsx
+import { Suspense } from 'preact/compat'
+import { useSuspenseQueries } from '@tanstack/preact-query'
+
+function Refresh() {
+  const anyFetching = useSuspenseQueries({
+    queries: [
+      { queryKey: ['users'], queryFn: fetchUsers },
+      { queryKey: ['teams'], queryFn: fetchTeams },
+    ],
+    combine: (results) => results.some((result) => result.isFetching),
+  })
+
+  return anyFetching ? <span>Refreshing…</span> : null
+}
+
+function App() {
+  return (
+    <Suspense fallback={<h1>Loading dashboard...</h1>}>
+      <Refresh />
+    </Suspense>
+  )
+}
+```
+
 ## Call Signature
 
 ```ts
 function useSuspenseQueries<T, TCombinedResult>(options, queryClient?): TCombinedResult;
 ```
 
-Defined in: [preact-query/src/useSuspenseQueries.ts:365](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseQueries.ts#L365)
+Defined in: [preact-query/src/useSuspenseQueries.ts:393](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseQueries.ts#L393)
 
 The options for `useSuspenseQueries` are the same as for `useQueries`, except that each `query` can't have
 `throwOnError`, `enabled`, or `placeholderData`.
diff --git a/packages/preact-query/src/useSuspenseInfiniteQuery.ts b/packages/preact-query/src/useSuspenseInfiniteQuery.ts
index 8e193936d3..d2cec89a89 100644
--- a/packages/preact-query/src/useSuspenseInfiniteQuery.ts
+++ b/packages/preact-query/src/useSuspenseInfiniteQuery.ts
@@ -21,6 +21,14 @@ import { useBaseQuery } from './useBaseQuery'
  *
  * Caveat: cancellation does not work.
  *
+ * @remarks Multiple suspenseful query calls (`useSuspenseInfiniteQuery`, `useSuspenseQuery`, etc.) in the
+ * same component suspend serially, causing a request waterfall — each one blocks rendering until it
+ * resolves, so the next doesn't even start fetching until then. There's no `useSuspenseInfiniteQueries` to
+ * parallelize multiple infinite queries the way {@link useSuspenseQueries} does for regular ones. Also keep
+ * in mind that imperative fetch calls, such as `fetchNextPage`, may interfere with the default refetch
+ * behavior, resulting in outdated data. Make sure to call these functions only in response to user actions,
+ * or add conditions like `hasNextPage && !isFetching`.
+ * @see {@link useInfiniteQuery} for the non-Suspense version of this hook.
  * @param options - The {@link UseSuspenseInfiniteQueryOptions} to use — the same options as `useInfiniteQuery`, minus the ones listed above.
  * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
  * be used.
diff --git a/packages/preact-query/src/useSuspenseQueries.ts b/packages/preact-query/src/useSuspenseQueries.ts
index 61e886c7fe..60f84b8f90 100644
--- a/packages/preact-query/src/useSuspenseQueries.ts
+++ b/packages/preact-query/src/useSuspenseQueries.ts
@@ -260,6 +260,34 @@ export type SuspenseQueriesResults<
  *   )
  * }
  * ```
+ *
+ * @example
+ * `combine`s the results into a single boolean, so `Refresh` only re-renders when that boolean changes,
+ * not on every individual query update. This overload is the only one that accepts `combine`:
+ * ```tsx
+ * import { Suspense } from 'preact/compat'
+ * import { useSuspenseQueries } from '@tanstack/preact-query'
+ *
+ * function Refresh() {
+ *   const anyFetching = useSuspenseQueries({
+ *     queries: [
+ *       { queryKey: ['users'], queryFn: fetchUsers },
+ *       { queryKey: ['teams'], queryFn: fetchTeams },
+ *     ],
+ *     combine: (results) => results.some((result) => result.isFetching),
+ *   })
+ *
+ *   return anyFetching ? <span>Refreshing…</span> : null
+ * }
+ *
+ * function App() {
+ *   return (
+ *     <Suspense fallback={<h1>Loading dashboard...</h1>}>
+ *       <Refresh />
+ *     </Suspense>
+ *   )
+ * }
+ * ```
  */
 export function useSuspenseQueries<
   T extends Array<any>,

From a20ed3e44a185ad72fbed5c2c6eb3f4a35952753 Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Sun, 30 Aug 2026 12:20:34 +0900
Subject: [PATCH 28/30] docs(preact-query): drop irrelevant
 'useSuspenseQueries' reference from 'useSuspenseInfiniteQuery' waterfall
 remark

---
 .../functions/useSuspenseInfiniteQuery.md         | 15 +++++++--------
 .../preact-query/src/useSuspenseInfiniteQuery.ts  | 13 ++++++-------
 2 files changed, 13 insertions(+), 15 deletions(-)

diff --git a/docs/framework/preact/reference/functions/useSuspenseInfiniteQuery.md b/docs/framework/preact/reference/functions/useSuspenseInfiniteQuery.md
index 17429a391c..167e24c091 100644
--- a/docs/framework/preact/reference/functions/useSuspenseInfiniteQuery.md
+++ b/docs/framework/preact/reference/functions/useSuspenseInfiniteQuery.md
@@ -7,7 +7,7 @@ title: useSuspenseInfiniteQuery
 function useSuspenseInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): UseSuspenseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useSuspenseInfiniteQuery.ts:84](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseInfiniteQuery.ts#L84)
+Defined in: [preact-query/src/useSuspenseInfiniteQuery.ts:83](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseInfiniteQuery.ts#L83)
 
 The options for `useSuspenseInfiniteQuery` are the same as for `useInfiniteQuery`, except for `throwOnError`,
 `enabled`, and `placeholderData`.
@@ -61,13 +61,12 @@ accordingly).
 
 ## Remarks
 
-Multiple suspenseful query calls (`useSuspenseInfiniteQuery`, `useSuspenseQuery`, etc.) in the
-same component suspend serially, causing a request waterfall — each one blocks rendering until it
-resolves, so the next doesn't even start fetching until then. There's no `useSuspenseInfiniteQueries` to
-parallelize multiple infinite queries the way [useSuspenseQueries](useSuspenseQueries.md) does for regular ones. Also keep
-in mind that imperative fetch calls, such as `fetchNextPage`, may interfere with the default refetch
-behavior, resulting in outdated data. Make sure to call these functions only in response to user actions,
-or add conditions like `hasNextPage && !isFetching`.
+Multiple suspenseful query calls in the same component suspend serially, causing a request
+waterfall — each one blocks rendering until it resolves, so the next doesn't even start fetching until
+then. There's no way to parallelize multiple infinite queries under Suspense. Also keep in mind that
+imperative fetch calls, such as `fetchNextPage`, may interfere with the default refetch behavior,
+resulting in outdated data. Make sure to call these functions only in response to user actions, or add
+conditions like `hasNextPage && !isFetching`.
 
 ## See
 
diff --git a/packages/preact-query/src/useSuspenseInfiniteQuery.ts b/packages/preact-query/src/useSuspenseInfiniteQuery.ts
index d2cec89a89..c7c1235300 100644
--- a/packages/preact-query/src/useSuspenseInfiniteQuery.ts
+++ b/packages/preact-query/src/useSuspenseInfiniteQuery.ts
@@ -21,13 +21,12 @@ import { useBaseQuery } from './useBaseQuery'
  *
  * Caveat: cancellation does not work.
  *
- * @remarks Multiple suspenseful query calls (`useSuspenseInfiniteQuery`, `useSuspenseQuery`, etc.) in the
- * same component suspend serially, causing a request waterfall — each one blocks rendering until it
- * resolves, so the next doesn't even start fetching until then. There's no `useSuspenseInfiniteQueries` to
- * parallelize multiple infinite queries the way {@link useSuspenseQueries} does for regular ones. Also keep
- * in mind that imperative fetch calls, such as `fetchNextPage`, may interfere with the default refetch
- * behavior, resulting in outdated data. Make sure to call these functions only in response to user actions,
- * or add conditions like `hasNextPage && !isFetching`.
+ * @remarks Multiple suspenseful query calls in the same component suspend serially, causing a request
+ * waterfall — each one blocks rendering until it resolves, so the next doesn't even start fetching until
+ * then. There's no way to parallelize multiple infinite queries under Suspense. Also keep in mind that
+ * imperative fetch calls, such as `fetchNextPage`, may interfere with the default refetch behavior,
+ * resulting in outdated data. Make sure to call these functions only in response to user actions, or add
+ * conditions like `hasNextPage && !isFetching`.
  * @see {@link useInfiniteQuery} for the non-Suspense version of this hook.
  * @param options - The {@link UseSuspenseInfiniteQueryOptions} to use — the same options as `useInfiniteQuery`, minus the ones listed above.
  * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will

From 66d28b7af58c1c624c551a3eaacb43b6daaa0092 Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Sun, 30 Aug 2026 12:24:53 +0900
Subject: [PATCH 29/30] docs(preact-query): strengthen 'useMutation''s '@see'
 pointer to 'mutationOptions' with its 'mutationKey' lookup benefit

---
 docs/framework/preact/reference/functions/useMutation.md | 5 +++--
 packages/preact-query/src/useMutation.ts                 | 3 ++-
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/docs/framework/preact/reference/functions/useMutation.md b/docs/framework/preact/reference/functions/useMutation.md
index a5c6fe1939..6483a6b004 100644
--- a/docs/framework/preact/reference/functions/useMutation.md
+++ b/docs/framework/preact/reference/functions/useMutation.md
@@ -7,7 +7,7 @@ title: useMutation
 function useMutation<TData, TError, TVariables, TOnMutateResult>(options, queryClient?): UseMutationResult<TData, TError, TVariables, TOnMutateResult>;
 ```
 
-Defined in: [preact-query/src/useMutation.ts:190](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useMutation.ts#L190)
+Defined in: [preact-query/src/useMutation.ts:191](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useMutation.ts#L191)
 
 Unlike queries, mutations are typically used to create/update/delete data or perform server side-effects.
 `useMutation` is the hook for that.
@@ -56,7 +56,8 @@ made.
 
 ## See
 
-[mutationOptions](mutationOptions.md) to share these options across multiple `useMutation` call sites.
+[mutationOptions](mutationOptions.md) to share these options across multiple `useMutation` call sites, or to look
+the mutation up elsewhere via its `mutationKey` (e.g. with `useMutationState`).
 
 ## Examples
 
diff --git a/packages/preact-query/src/useMutation.ts b/packages/preact-query/src/useMutation.ts
index bd4baf0326..eb3565732f 100644
--- a/packages/preact-query/src/useMutation.ts
+++ b/packages/preact-query/src/useMutation.ts
@@ -21,7 +21,8 @@ import { useSyncExternalStore } from './utils'
  * Unlike queries, mutations are typically used to create/update/delete data or perform server side-effects.
  * `useMutation` is the hook for that.
  *
- * @see {@link mutationOptions} to share these options across multiple `useMutation` call sites.
+ * @see {@link mutationOptions} to share these options across multiple `useMutation` call sites, or to look
+ * the mutation up elsewhere via its `mutationKey` (e.g. with `useMutationState`).
  * @param options - The {@link UseMutationOptions} to use — everything you can pass to `useMutation`.
  * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
  * be used.

From efa26bfddf95c8da42f17f9a36ef415ae79e8755 Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Sun, 30 Aug 2026 12:47:19 +0900
Subject: [PATCH 30/30] docs(preact-query): add blank lines around
 'isPending'/'isError' guards for consistency with other examples

---
 .../preact/reference/functions/infiniteQueryOptions.md    | 8 ++++++--
 docs/framework/preact/reference/functions/queryOptions.md | 8 ++++++--
 .../preact/reference/functions/useInfiniteQuery.md        | 4 +++-
 packages/preact-query/src/infiniteQueryOptions.ts         | 4 ++++
 packages/preact-query/src/queryOptions.ts                 | 4 ++++
 packages/preact-query/src/useInfiniteQuery.ts             | 2 ++
 6 files changed, 25 insertions(+), 5 deletions(-)

diff --git a/docs/framework/preact/reference/functions/infiniteQueryOptions.md b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
index c7c714edea..206087481c 100644
--- a/docs/framework/preact/reference/functions/infiniteQueryOptions.md
+++ b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
@@ -95,7 +95,7 @@ function Projects() {
 function infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options): OmitKeyof<UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, "queryFn"> & object & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData, unknown>, TError>;
 ```
 
-Defined in: [preact-query/src/infiniteQueryOptions.ts:238](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L238)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:240](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L240)
 
 You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
 These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
@@ -160,8 +160,10 @@ export const commentsOptions = (postId: string) =>
 
 function Comments({ postId }: { postId: string }) {
   const { data, isPending, isError, error } = useInfiniteQuery(commentsOptions(postId))
+
   if (isPending) return 'Loading...'
   if (isError) return <span>Error: {error.message}</span>
+
   return (
     <ul>
       {data.pages.map((page) => page.comments.map((c) => <li key={c.id}>{c.text}</li>))}
@@ -185,7 +187,7 @@ queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
 function infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options): UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & object & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData, unknown>, TError>;
 ```
 
-Defined in: [preact-query/src/infiniteQueryOptions.ts:307](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L307)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:311](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L311)
 
 You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
 These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
@@ -250,8 +252,10 @@ export const commentsOptions = (postId: string) =>
 
 function Comments({ postId }: { postId: string }) {
   const { data, isPending, isError, error } = useInfiniteQuery(commentsOptions(postId))
+
   if (isPending) return 'Loading...'
   if (isError) return <span>Error: {error.message}</span>
+
   return (
     <ul>
       {data.pages.map((page) => page.comments.map((c) => <li key={c.id}>{c.text}</li>))}
diff --git a/docs/framework/preact/reference/functions/queryOptions.md b/docs/framework/preact/reference/functions/queryOptions.md
index adc0d5f8e9..4e6f33a105 100644
--- a/docs/framework/preact/reference/functions/queryOptions.md
+++ b/docs/framework/preact/reference/functions/queryOptions.md
@@ -84,7 +84,7 @@ function Posts() {
 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:211](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L211)
+Defined in: [preact-query/src/queryOptions.ts:213](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L213)
 
 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
@@ -138,8 +138,10 @@ export const postOptions = (id: string) =>
 
 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>
 }
 
@@ -182,7 +184,7 @@ queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefi
 function queryOptions<TQueryFnData, TError, TData, TQueryKey>(options): UseQueryOptions<TQueryFnData, TError, TData, TQueryKey> & object & QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>;
 ```
 
-Defined in: [preact-query/src/queryOptions.ts:305](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L305)
+Defined in: [preact-query/src/queryOptions.ts:309](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L309)
 
 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
@@ -240,8 +242,10 @@ export const postOptions = (id: string) =>
 
 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>
 }
 
diff --git a/docs/framework/preact/reference/functions/useInfiniteQuery.md b/docs/framework/preact/reference/functions/useInfiniteQuery.md
index 2075ddfc47..0201330bc3 100644
--- a/docs/framework/preact/reference/functions/useInfiniteQuery.md
+++ b/docs/framework/preact/reference/functions/useInfiniteQuery.md
@@ -263,7 +263,7 @@ function Projects() {
 function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): UseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useInfiniteQuery.ts:388](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L388)
+Defined in: [preact-query/src/useInfiniteQuery.ts:390](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L390)
 
 The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
 `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
@@ -436,8 +436,10 @@ const commentsOptions = (postId: string) =>
 
 function Comments({ postId }: { postId: string }) {
   const { data, isPending, isError, error } = useInfiniteQuery(commentsOptions(postId))
+
   if (isPending) return 'Loading...'
   if (isError) return <span>Error: {error.message}</span>
+
   return (
     <ul>
       {data.pages.map((page) => page.comments.map((c) => <li key={c.id}>{c.text}</li>))}
diff --git a/packages/preact-query/src/infiniteQueryOptions.ts b/packages/preact-query/src/infiniteQueryOptions.ts
index 3a61ecfe7a..ece6e2c7fb 100644
--- a/packages/preact-query/src/infiniteQueryOptions.ts
+++ b/packages/preact-query/src/infiniteQueryOptions.ts
@@ -217,8 +217,10 @@ export function infiniteQueryOptions<
  *
  * function Comments({ postId }: { postId: string }) {
  *   const { data, isPending, isError, error } = useInfiniteQuery(commentsOptions(postId))
+ *
  *   if (isPending) return 'Loading...'
  *   if (isError) return <span>Error: {error.message}</span>
+ *
  *   return (
  *     <ul>
  *       {data.pages.map((page) => page.comments.map((c) => <li key={c.id}>{c.text}</li>))}
@@ -286,8 +288,10 @@ export function infiniteQueryOptions<
  *
  * function Comments({ postId }: { postId: string }) {
  *   const { data, isPending, isError, error } = useInfiniteQuery(commentsOptions(postId))
+ *
  *   if (isPending) return 'Loading...'
  *   if (isError) return <span>Error: {error.message}</span>
+ *
  *   return (
  *     <ul>
  *       {data.pages.map((page) => page.comments.map((c) => <li key={c.id}>{c.text}</li>))}
diff --git a/packages/preact-query/src/queryOptions.ts b/packages/preact-query/src/queryOptions.ts
index fd04d84a49..ef9aec009f 100644
--- a/packages/preact-query/src/queryOptions.ts
+++ b/packages/preact-query/src/queryOptions.ts
@@ -169,8 +169,10 @@ export function queryOptions<
  *
  * 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>
  * }
  *
@@ -241,8 +243,10 @@ export function queryOptions<
  *
  * 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>
  * }
  *
diff --git a/packages/preact-query/src/useInfiniteQuery.ts b/packages/preact-query/src/useInfiniteQuery.ts
index 2026ce0511..36e1514d37 100644
--- a/packages/preact-query/src/useInfiniteQuery.ts
+++ b/packages/preact-query/src/useInfiniteQuery.ts
@@ -332,8 +332,10 @@ export function useInfiniteQuery<
  *
  * function Comments({ postId }: { postId: string }) {
  *   const { data, isPending, isError, error } = useInfiniteQuery(commentsOptions(postId))
+ *
  *   if (isPending) return 'Loading...'
  *   if (isError) return <span>Error: {error.message}</span>
+ *
  *   return (
  *     <ul>
  *       {data.pages.map((page) => page.comments.map((c) => <li key={c.id}>{c.text}</li>))}