From c069283844b47fe709af6acfba59c68a68481b3e Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Mon, 24 Aug 2026 18:11:40 +0900
Subject: [PATCH 01/28] docs(preact-query): document functions and components
 with JSDoc for generated reference docs

---
 .../reference/functions/HydrationBoundary.md  | 18 ++++-
 .../functions/QueryClientProvider.md          | 16 ++++-
 .../functions/QueryErrorResetBoundary.md      | 44 +++++++++++-
 .../functions/infiniteQueryOptions.md         | 18 ++++-
 .../reference/functions/mutationOptions.md    |  8 ++-
 .../reference/functions/queryOptions.md       | 60 +++++++++++++++-
 .../reference/functions/useInfiniteQuery.md   | 60 +++++++++++++++-
 .../reference/functions/useIsFetching.md      | 24 ++++++-
 .../reference/functions/useIsMutating.md      | 23 ++++++-
 .../preact/reference/functions/useMutation.md | 24 ++++++-
 .../reference/functions/useMutationState.md   | 43 +++++++++++-
 .../functions/usePrefetchInfiniteQuery.md     | 13 +++-
 .../reference/functions/usePrefetchQuery.md   |  7 +-
 .../preact/reference/functions/useQueries.md  | 51 +++++++++++++-
 .../preact/reference/functions/useQuery.md    | 45 +++++++++++-
 .../reference/functions/useQueryClient.md     |  7 +-
 .../functions/useQueryErrorResetBoundary.md   | 28 +++++++-
 .../functions/useSuspenseInfiniteQuery.md     | 11 ++-
 .../reference/functions/useSuspenseQueries.md | 26 ++++++-
 .../reference/functions/useSuspenseQuery.md   | 10 ++-
 .../interfaces/HydrationBoundaryProps.md      | 14 ++--
 .../QueryErrorResetBoundaryProps.md           |  4 +-
 .../type-aliases/QueryClientProviderProps.md  | 10 ++-
 .../QueryErrorResetBoundaryFunction.md        |  2 +-
 .../preact-query/src/HydrationBoundary.tsx    | 25 +++++++
 .../preact-query/src/QueryClientProvider.tsx  | 25 +++++++
 .../src/QueryErrorResetBoundary.tsx           | 68 +++++++++++++++++++
 .../preact-query/src/infiniteQueryOptions.ts  | 15 ++++
 packages/preact-query/src/mutationOptions.ts  |  6 ++
 packages/preact-query/src/queryOptions.ts     | 54 +++++++++++++++
 packages/preact-query/src/useInfiniteQuery.ts | 55 +++++++++++++++
 packages/preact-query/src/useIsFetching.ts    | 20 ++++++
 packages/preact-query/src/useMutation.ts      | 22 ++++++
 packages/preact-query/src/useMutationState.ts | 62 +++++++++++++++++
 .../src/usePrefetchInfiniteQuery.tsx          | 12 ++++
 .../preact-query/src/usePrefetchQuery.tsx     |  6 ++
 packages/preact-query/src/useQueries.ts       | 49 +++++++++++++
 packages/preact-query/src/useQuery.ts         | 41 +++++++++++
 .../src/useSuspenseInfiniteQuery.ts           | 10 +++
 .../preact-query/src/useSuspenseQueries.ts    | 24 +++++++
 packages/preact-query/src/useSuspenseQuery.ts |  9 +++
 41 files changed, 1029 insertions(+), 40 deletions(-)

diff --git a/docs/framework/preact/reference/functions/HydrationBoundary.md b/docs/framework/preact/reference/functions/HydrationBoundary.md
index 3d48a51149d..afcbdba0045 100644
--- a/docs/framework/preact/reference/functions/HydrationBoundary.md
+++ b/docs/framework/preact/reference/functions/HydrationBoundary.md
@@ -7,7 +7,13 @@ title: HydrationBoundary
 function HydrationBoundary(__namedParameters): Element;
 ```
 
-Defined in: [preact-query/src/HydrationBoundary.tsx:26](https://github.com/TanStack/query/blob/main/packages/preact-query/src/HydrationBoundary.tsx#L26)
+Defined in: [preact-query/src/HydrationBoundary.tsx:51](https://github.com/TanStack/query/blob/main/packages/preact-query/src/HydrationBoundary.tsx#L51)
+
+`HydrationBoundary` adds a previously dehydrated state into the `queryClient` that would be returned by
+`useQueryClient()`. If the client already contains data, the new queries will be intelligently merged based on
+update timestamp.
+
+Note: Only `queries` can be dehydrated with an `HydrationBoundary`.
 
 ## Parameters
 
@@ -18,3 +24,13 @@ Defined in: [preact-query/src/HydrationBoundary.tsx:26](https://github.com/TanSt
 ## Returns
 
 `Element`
+
+## Example
+
+```tsx
+import { HydrationBoundary } from '@tanstack/preact-query'
+
+function App() {
+  return <HydrationBoundary state={dehydratedState}>...</HydrationBoundary>
+}
+```
diff --git a/docs/framework/preact/reference/functions/QueryClientProvider.md b/docs/framework/preact/reference/functions/QueryClientProvider.md
index 2ac3ccfbda1..b680a16f538 100644
--- a/docs/framework/preact/reference/functions/QueryClientProvider.md
+++ b/docs/framework/preact/reference/functions/QueryClientProvider.md
@@ -7,7 +7,9 @@ title: QueryClientProvider
 function QueryClientProvider(__namedParameters): VNode;
 ```
 
-Defined in: [preact-query/src/QueryClientProvider.tsx:29](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryClientProvider.tsx#L29)
+Defined in: [preact-query/src/QueryClientProvider.tsx:54](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryClientProvider.tsx#L54)
+
+Use the `QueryClientProvider` component to connect and provide a `QueryClient` to your application.
 
 ## Parameters
 
@@ -18,3 +20,15 @@ Defined in: [preact-query/src/QueryClientProvider.tsx:29](https://github.com/Tan
 ## Returns
 
 `VNode`
+
+## Example
+
+```tsx
+import { QueryClient, QueryClientProvider } from '@tanstack/preact-query'
+
+const queryClient = new QueryClient()
+
+function App() {
+  return <QueryClientProvider client={queryClient}>...</QueryClientProvider>
+}
+```
diff --git a/docs/framework/preact/reference/functions/QueryErrorResetBoundary.md b/docs/framework/preact/reference/functions/QueryErrorResetBoundary.md
index aa06d5317d9..acba933862c 100644
--- a/docs/framework/preact/reference/functions/QueryErrorResetBoundary.md
+++ b/docs/framework/preact/reference/functions/QueryErrorResetBoundary.md
@@ -7,7 +7,11 @@ title: QueryErrorResetBoundary
 function QueryErrorResetBoundary(__namedParameters): Element;
 ```
 
-Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:48](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L48)
+Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:116](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L116)
+
+When using **suspense** or **throwOnError** in your queries, you need a way to let queries know that you want to
+try again when re-rendering after some error occurred. With the `QueryErrorResetBoundary` component you can
+reset any query errors within the boundaries of the component.
 
 ## Parameters
 
@@ -18,3 +22,41 @@ Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:48](https://github.com
 ## Returns
 
 `Element`
+
+## Example
+
+```tsx
+import { useErrorBoundary } from 'preact/hooks'
+import { QueryErrorResetBoundary } from '@tanstack/preact-query'
+
+function ErrorBoundary({
+  children,
+  reset,
+}: {
+  children: ComponentChildren
+  reset: () => void
+}) {
+  const [error, resetError] = useErrorBoundary(() => reset())
+
+  if (error) {
+    return (
+      <div>
+        There was an error!
+        <button onClick={() => resetError()}>Try again</button>
+      </div>
+    )
+  }
+
+  return children
+}
+
+const App = () => (
+  <QueryErrorResetBoundary>
+    {({ reset }) => (
+      <ErrorBoundary reset={reset}>
+        <Page />
+      </ErrorBoundary>
+    )}
+  </QueryErrorResetBoundary>
+)
+```
diff --git a/docs/framework/preact/reference/functions/infiniteQueryOptions.md b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
index a304f4271c0..b454d91a9ba 100644
--- a/docs/framework/preact/reference/functions/infiniteQueryOptions.md
+++ b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
@@ -9,7 +9,11 @@ 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:76](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L76)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:81](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L81)
+
+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`.
+`options.queryKey` is required and is the query key to generate options for.
 
 ### Type Parameters
 
@@ -49,7 +53,11 @@ Defined in: [preact-query/src/infiniteQueryOptions.ts:76](https://github.com/Tan
 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:99](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L99)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:109](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L109)
+
+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`.
+`options.queryKey` is required and is the query key to generate options for.
 
 ### Type Parameters
 
@@ -89,7 +97,11 @@ Defined in: [preact-query/src/infiniteQueryOptions.ts:99](https://github.com/Tan
 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:122](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L122)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:137](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L137)
+
+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`.
+`options.queryKey` is required and is the query key to generate options for.
 
 ### Type Parameters
 
diff --git a/docs/framework/preact/reference/functions/mutationOptions.md b/docs/framework/preact/reference/functions/mutationOptions.md
index a72866cc0ab..5d3a146ed25 100644
--- a/docs/framework/preact/reference/functions/mutationOptions.md
+++ b/docs/framework/preact/reference/functions/mutationOptions.md
@@ -9,7 +9,9 @@ title: mutationOptions
 function mutationOptions<TData, TError, TVariables, TOnMutateResult>(options): WithRequired<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">;
 ```
 
-Defined in: [preact-query/src/mutationOptions.ts:5](https://github.com/TanStack/query/blob/main/packages/preact-query/src/mutationOptions.ts#L5)
+Defined in: [preact-query/src/mutationOptions.ts:8](https://github.com/TanStack/query/blob/main/packages/preact-query/src/mutationOptions.ts#L8)
+
+You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`.
 
 ### Type Parameters
 
@@ -45,7 +47,9 @@ Defined in: [preact-query/src/mutationOptions.ts:5](https://github.com/TanStack/
 function mutationOptions<TData, TError, TVariables, TOnMutateResult>(options): Omit<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">;
 ```
 
-Defined in: [preact-query/src/mutationOptions.ts:19](https://github.com/TanStack/query/blob/main/packages/preact-query/src/mutationOptions.ts#L19)
+Defined in: [preact-query/src/mutationOptions.ts:25](https://github.com/TanStack/query/blob/main/packages/preact-query/src/mutationOptions.ts#L25)
+
+You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`.
 
 ### Type Parameters
 
diff --git a/docs/framework/preact/reference/functions/queryOptions.md b/docs/framework/preact/reference/functions/queryOptions.md
index 4db0bb82373..69a8990dc53 100644
--- a/docs/framework/preact/reference/functions/queryOptions.md
+++ b/docs/framework/preact/reference/functions/queryOptions.md
@@ -9,7 +9,11 @@ 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:53](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L53)
+Defined in: [preact-query/src/queryOptions.ts:71](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L71)
+
+You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can
+be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and
+is the query key to generate options for.
 
 ### Type Parameters
 
@@ -39,13 +43,31 @@ Defined in: [preact-query/src/queryOptions.ts:53](https://github.com/TanStack/qu
 
 `Omit`\<[`UseQueryOptions`](../interfaces/UseQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>, `"queryFn"`\> & `object` & `QueryKeyWithDataTag`\<`TQueryKey`, `TQueryFnData`, `TError`\>
 
+### Example
+
+```tsx
+import { queryOptions } from '@tanstack/preact-query'
+
+export const pokemonOptions = queryOptions({
+  queryKey: ['pokemon'],
+  queryFn: async () => {
+    const response = await fetch('https://pokeapi.co/api/v2/pokemon/25')
+    return response.json()
+  },
+})
+```
+
 ## Call Signature
 
 ```ts
 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:63](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L63)
+Defined in: [preact-query/src/queryOptions.ts:99](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L99)
+
+You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can
+be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and
+is the query key to generate options for.
 
 ### Type Parameters
 
@@ -75,13 +97,31 @@ Defined in: [preact-query/src/queryOptions.ts:63](https://github.com/TanStack/qu
 
 `OmitKeyof`\<[`UseQueryOptions`](../interfaces/UseQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>, `"queryFn"`\> & `object` & `QueryKeyWithDataTag`\<`TQueryKey`, `TQueryFnData`, `TError`\>
 
+### Example
+
+```tsx
+import { queryOptions } from '@tanstack/preact-query'
+
+export const pokemonOptions = queryOptions({
+  queryKey: ['pokemon'],
+  queryFn: async () => {
+    const response = await fetch('https://pokeapi.co/api/v2/pokemon/25')
+    return response.json()
+  },
+})
+```
+
 ## Call Signature
 
 ```ts
 function queryOptions<TQueryFnData, TError, TData, TQueryKey>(options): UseQueryOptions<TQueryFnData, TError, TData, TQueryKey> & object & QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>;
 ```
 
-Defined in: [preact-query/src/queryOptions.ts:73](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L73)
+Defined in: [preact-query/src/queryOptions.ts:127](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L127)
+
+You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can
+be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and
+is the query key to generate options for.
 
 ### Type Parameters
 
@@ -110,3 +150,17 @@ Defined in: [preact-query/src/queryOptions.ts:73](https://github.com/TanStack/qu
 ### Returns
 
 [`UseQueryOptions`](../interfaces/UseQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & `object` & `QueryKeyWithDataTag`\<`TQueryKey`, `TQueryFnData`, `TError`\>
+
+### Example
+
+```tsx
+import { queryOptions } from '@tanstack/preact-query'
+
+export const pokemonOptions = queryOptions({
+  queryKey: ['pokemon'],
+  queryFn: async () => {
+    const response = await fetch('https://pokeapi.co/api/v2/pokemon/25')
+    return response.json()
+  },
+})
+```
diff --git a/docs/framework/preact/reference/functions/useInfiniteQuery.md b/docs/framework/preact/reference/functions/useInfiniteQuery.md
index 87fa3c3fa57..34a19a8d2af 100644
--- a/docs/framework/preact/reference/functions/useInfiniteQuery.md
+++ b/docs/framework/preact/reference/functions/useInfiniteQuery.md
@@ -9,7 +9,10 @@ title: useInfiniteQuery
 function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): DefinedUseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useInfiniteQuery.ts:21](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L21)
+Defined in: [preact-query/src/useInfiniteQuery.ts:28](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L28)
+
+The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
+`initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
 
 ### Type Parameters
 
@@ -43,6 +46,9 @@ Defined in: [preact-query/src/useInfiniteQuery.ts:21](https://github.com/TanStac
 
 `QueryClient`
 
+Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
+be used.
+
 ### Returns
 
 [`DefinedUseInfiniteQueryResult`](../type-aliases/DefinedUseInfiniteQueryResult.md)\<`TData`, `TError`\>
@@ -53,7 +59,10 @@ Defined in: [preact-query/src/useInfiniteQuery.ts:21](https://github.com/TanStac
 function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): UseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useInfiniteQuery.ts:38](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L38)
+Defined in: [preact-query/src/useInfiniteQuery.ts:52](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L52)
+
+The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
+`initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
 
 ### Type Parameters
 
@@ -87,6 +96,9 @@ Defined in: [preact-query/src/useInfiniteQuery.ts:38](https://github.com/TanStac
 
 `QueryClient`
 
+Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
+be used.
+
 ### Returns
 
 [`UseInfiniteQueryResult`](../type-aliases/UseInfiniteQueryResult.md)\<`TData`, `TError`\>
@@ -97,7 +109,10 @@ Defined in: [preact-query/src/useInfiniteQuery.ts:38](https://github.com/TanStac
 function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): UseInfiniteQueryResult<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:110](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L110)
+
+The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
+`initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
 
 ### Type Parameters
 
@@ -131,6 +146,45 @@ Defined in: [preact-query/src/useInfiniteQuery.ts:55](https://github.com/TanStac
 
 `QueryClient`
 
+Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
+be used.
+
 ### Returns
 
 [`UseInfiniteQueryResult`](../type-aliases/UseInfiniteQueryResult.md)\<`TData`, `TError`\>
+
+The same properties as `useQuery`, with the addition of `data.pages`, `data.pageParams`,
+`fetchNextPage`, `fetchPreviousPage`, `hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and
+`isFetchingPreviousPage`.
+
+Keep in mind that imperative fetch calls, such as `fetchNextPage`, may interfere with the default refetch
+behaviour, resulting in outdated data. Make sure to call these functions only in response to user actions,
+or add conditions like `hasNextPage && !isFetching`.
+
+### Example
+
+```tsx
+import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
+
+const projectsOptions = infiniteQueryOptions({
+  queryKey: ['projects'],
+  queryFn: ({ pageParam }) =>
+    fetch(`/api/projects?cursor=${pageParam}`).then((r) => r.json()),
+  initialPageParam: 0,
+  getNextPageParam: (lastPage) => lastPage.nextId,
+})
+
+function Projects() {
+  const { data, fetchNextPage, hasNextPage, isFetchingNextPage } =
+    useInfiniteQuery(projectsOptions)
+
+  return (
+    <button
+      onClick={() => fetchNextPage()}
+      disabled={!hasNextPage || isFetchingNextPage}
+    >
+      Load More
+    </button>
+  )
+}
+```
diff --git a/docs/framework/preact/reference/functions/useIsFetching.md b/docs/framework/preact/reference/functions/useIsFetching.md
index 2e8d489d814..e697a482236 100644
--- a/docs/framework/preact/reference/functions/useIsFetching.md
+++ b/docs/framework/preact/reference/functions/useIsFetching.md
@@ -7,7 +7,10 @@ title: useIsFetching
 function useIsFetching(filters?, queryClient?): number;
 ```
 
-Defined in: [preact-query/src/useIsFetching.ts:8](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useIsFetching.ts#L8)
+Defined in: [preact-query/src/useIsFetching.ts:28](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useIsFetching.ts#L28)
+
+`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).
 
 ## Parameters
 
@@ -15,10 +18,29 @@ Defined in: [preact-query/src/useIsFetching.ts:8](https://github.com/TanStack/qu
 
 `QueryFilters`\<readonly `unknown`[]\>
 
+QueryFilters
+
 ### queryClient?
 
 `QueryClient`
 
+Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
+be used.
+
 ## Returns
 
 `number`
+
+Will be the `number` of the queries that your application is currently loading or fetching in the
+background.
+
+## Example
+
+```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'] })
+```
diff --git a/docs/framework/preact/reference/functions/useIsMutating.md b/docs/framework/preact/reference/functions/useIsMutating.md
index 13327fc0ca2..ca3a9b76b71 100644
--- a/docs/framework/preact/reference/functions/useIsMutating.md
+++ b/docs/framework/preact/reference/functions/useIsMutating.md
@@ -7,7 +7,10 @@ title: useIsMutating
 function useIsMutating(filters?, queryClient?): number;
 ```
 
-Defined in: [preact-query/src/useMutationState.ts:14](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useMutationState.ts#L14)
+Defined in: [preact-query/src/useMutationState.ts:33](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useMutationState.ts#L33)
+
+`useIsMutating` is an optional hook that returns the `number` of mutations that your application is fetching
+(useful for app-wide loading indicators).
 
 ## Parameters
 
@@ -15,10 +18,28 @@ Defined in: [preact-query/src/useMutationState.ts:14](https://github.com/TanStac
 
 `MutationFilters`\<`unknown`, `Error`, `unknown`, `unknown`\>
 
+MutationFilters
+
 ### queryClient?
 
 `QueryClient`
 
+Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
+be used.
+
 ## Returns
 
 `number`
+
+Will be the `number` of the mutations that your application is currently fetching.
+
+## Example
+
+```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'] })
+```
diff --git a/docs/framework/preact/reference/functions/useMutation.md b/docs/framework/preact/reference/functions/useMutation.md
index 0a67753e610..11167112aed 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:20](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useMutation.ts#L20)
+Defined in: [preact-query/src/useMutation.ts:42](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useMutation.ts#L42)
 
 ## Type Parameters
 
@@ -37,6 +37,28 @@ Defined in: [preact-query/src/useMutation.ts:20](https://github.com/TanStack/que
 
 `QueryClient`
 
+Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
+be used.
+
 ## Returns
 
 [`UseMutationResult`](../type-aliases/UseMutationResult.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>
+
+## Example
+
+```tsx
+import { useMutation, useQueryClient } from '@tanstack/preact-query'
+
+function Example() {
+  const queryClient = useQueryClient()
+
+  const addMutation = useMutation({
+    mutationFn: (add: string) => fetch(`/api/data?add=${add}`),
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
+  })
+
+  return (
+    <button onClick={() => addMutation.mutate('Item')}>Add</button>
+  )
+}
+```
diff --git a/docs/framework/preact/reference/functions/useMutationState.md b/docs/framework/preact/reference/functions/useMutationState.md
index 28b6bda79c2..00018c26a98 100644
--- a/docs/framework/preact/reference/functions/useMutationState.md
+++ b/docs/framework/preact/reference/functions/useMutationState.md
@@ -7,7 +7,10 @@ title: useMutationState
 function useMutationState<TResult, TMutation>(options, queryClient?): TResult[];
 ```
 
-Defined in: [preact-query/src/useMutationState.ts:63](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useMutationState.ts#L63)
+Defined in: [preact-query/src/useMutationState.ts:125](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useMutationState.ts#L125)
+
+`useMutationState` is a hook that gives you access to all mutations in the `MutationCache`. You can pass
+`filters` to it to narrow down your mutations, and `select` to transform the mutation state.
 
 ## Type Parameters
 
@@ -29,6 +32,44 @@ Defined in: [preact-query/src/useMutationState.ts:63](https://github.com/TanStac
 
 `QueryClient`
 
+Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
+be used.
+
 ## Returns
 
 `TResult`[]
+
+Will be an Array of whatever `select` returns for each matching mutation.
+
+## Examples
+
+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,
+})
+```
+
+Get all data for specific mutations via the `mutationKey`:
+```tsx
+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: (newPost) => {
+    return axios.post('/posts', newPost)
+  },
+})
+
+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,
+})
+```
diff --git a/docs/framework/preact/reference/functions/usePrefetchInfiniteQuery.md b/docs/framework/preact/reference/functions/usePrefetchInfiniteQuery.md
index 33b0cb93004..6015b04667e 100644
--- a/docs/framework/preact/reference/functions/usePrefetchInfiniteQuery.md
+++ b/docs/framework/preact/reference/functions/usePrefetchInfiniteQuery.md
@@ -7,7 +7,18 @@ title: usePrefetchInfiniteQuery
 function usePrefetchInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): void;
 ```
 
-Defined in: [preact-query/src/usePrefetchInfiniteQuery.tsx:7](https://github.com/TanStack/query/blob/main/packages/preact-query/src/usePrefetchInfiniteQuery.tsx#L7)
+Defined in: [preact-query/src/usePrefetchInfiniteQuery.tsx:19](https://github.com/TanStack/query/blob/main/packages/preact-query/src/usePrefetchInfiniteQuery.tsx#L19)
+
+`usePrefetchInfiniteQuery` does not return anything, it should be used just to fire a prefetch during render,
+before a suspense boundary that wraps a component that uses `useSuspenseInfiniteQuery`. You can pass
+everything to `usePrefetchInfiniteQuery` that you can pass to `queryClient.fetchInfiniteQuery`, though
+`queryKey`, `initialPageParam`, and `getNextPageParam` are always required, and `queryFn` is required unless
+a default query function has been defined.
+
+`getNextPageParam` receives both the last page of the infinite list of data and the full array of all pages,
+as well as pageParam information, and should return a single variable that will be passed as the last
+optional parameter to your query function. Return `undefined` or `null` to indicate there is no next page
+available.
 
 ## Type Parameters
 
diff --git a/docs/framework/preact/reference/functions/usePrefetchQuery.md b/docs/framework/preact/reference/functions/usePrefetchQuery.md
index 8f9648d84a3..c6a0c767115 100644
--- a/docs/framework/preact/reference/functions/usePrefetchQuery.md
+++ b/docs/framework/preact/reference/functions/usePrefetchQuery.md
@@ -7,7 +7,12 @@ title: usePrefetchQuery
 function usePrefetchQuery<TQueryFnData, TError, TData, TQueryData, TQueryKey>(options, queryClient?): void;
 ```
 
-Defined in: [preact-query/src/usePrefetchQuery.tsx:7](https://github.com/TanStack/query/blob/main/packages/preact-query/src/usePrefetchQuery.tsx#L7)
+Defined in: [preact-query/src/usePrefetchQuery.tsx:13](https://github.com/TanStack/query/blob/main/packages/preact-query/src/usePrefetchQuery.tsx#L13)
+
+`usePrefetchQuery` does not return anything, it should be used just to fire a prefetch during render, before
+a suspense boundary that wraps a component that uses `useSuspenseQuery`. You can pass everything to
+`usePrefetchQuery` that you can pass to `queryClient.fetchQuery`, though `queryKey` is always required, and
+`queryFn` is required unless a default query function has been defined.
 
 ## Type Parameters
 
diff --git a/docs/framework/preact/reference/functions/useQueries.md b/docs/framework/preact/reference/functions/useQueries.md
index 382fc008657..49f375e8444 100644
--- a/docs/framework/preact/reference/functions/useQueries.md
+++ b/docs/framework/preact/reference/functions/useQueries.md
@@ -7,7 +7,19 @@ title: useQueries
 function useQueries<T, TCombinedResult>(__namedParameters, queryClient?): TCombinedResult;
 ```
 
-Defined in: [preact-query/src/useQueries.ts:207](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQueries.ts#L207)
+Defined in: [preact-query/src/useQueries.ts:256](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQueries.ts#L256)
+
+The `useQueries` hook can be used to fetch a variable number of queries.
+
+The `queries` key accepts an array with query option objects identical to `useQuery` (excluding the
+`queryClient` option - because the `QueryClient` can be passed in on the top level).
+
+Having the same query key more than once in the array of query objects may cause some data to be shared
+between queries. To avoid this, consider de-duplicating the queries and map the results back to the desired
+structure.
+
+The `combine` option can be used to combine the results of the queries into a single value. The result will
+be structurally shared to be as referentially stable as possible.
 
 ## Type Parameters
 
@@ -40,6 +52,43 @@ Defined in: [preact-query/src/useQueries.ts:207](https://github.com/TanStack/que
 
 `QueryClient`
 
+Use this to provide a custom QueryClient. Otherwise, the one from the nearest context
+will be used.
+
 ## Returns
 
 `TCombinedResult`
+
+An array with all the query results. The order returned is the same as the input order.
+
+## Examples
+
+```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,
+  })),
+})
+```
+
+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),
+    }
+  },
+})
+```
diff --git a/docs/framework/preact/reference/functions/useQuery.md b/docs/framework/preact/reference/functions/useQuery.md
index ff2b38d7be4..5b77b97b868 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:15](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L15)
+Defined in: [preact-query/src/useQuery.ts:19](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L19)
 
 ### Type Parameters
 
@@ -39,6 +39,9 @@ Defined in: [preact-query/src/useQuery.ts:15](https://github.com/TanStack/query/
 
 `QueryClient`
 
+Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
+be used.
+
 ### Returns
 
 [`DefinedUseQueryResult`](../type-aliases/DefinedUseQueryResult.md)\<`TData`, `TError`\>
@@ -49,7 +52,7 @@ Defined in: [preact-query/src/useQuery.ts:15](https://github.com/TanStack/query/
 function useQuery<TQueryFnData, TError, TData, TQueryKey>(options, queryClient?): UseQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useQuery.ts:25](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L25)
+Defined in: [preact-query/src/useQuery.ts:33](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L33)
 
 ### Type Parameters
 
@@ -79,6 +82,9 @@ Defined in: [preact-query/src/useQuery.ts:25](https://github.com/TanStack/query/
 
 `QueryClient`
 
+Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
+be used.
+
 ### Returns
 
 [`UseQueryResult`](../type-aliases/UseQueryResult.md)\<`TData`, `TError`\>
@@ -89,7 +95,7 @@ Defined in: [preact-query/src/useQuery.ts:25](https://github.com/TanStack/query/
 function useQuery<TQueryFnData, TError, TData, TQueryKey>(options, queryClient?): UseQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useQuery.ts:35](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L35)
+Defined in: [preact-query/src/useQuery.ts:76](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L76)
 
 ### Type Parameters
 
@@ -119,6 +125,39 @@ Defined in: [preact-query/src/useQuery.ts:35](https://github.com/TanStack/query/
 
 `QueryClient`
 
+Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
+be used.
+
 ### Returns
 
 [`UseQueryResult`](../type-aliases/UseQueryResult.md)\<`TData`, `TError`\>
+
+### Example
+
+```tsx
+import { queryOptions, useQuery } from '@tanstack/preact-query'
+
+const postsOptions = queryOptions({
+  queryKey: ['posts'],
+  queryFn: async () => {
+    const response = await fetch('https://jsonplaceholder.typicode.com/posts')
+    return await response.json()
+  },
+})
+
+function Posts() {
+  const { status, data, error, isFetching } = useQuery(postsOptions)
+
+  if (status === 'pending') return 'Loading...'
+  if (status === 'error') return <span>Error: {error.message}</span>
+
+  return (
+    <div>
+      {data.map((post) => (
+        <p key={post.id}>{post.title}</p>
+      ))}
+      <div>{isFetching ? 'Background Updating...' : ' '}</div>
+    </div>
+  )
+}
+```
diff --git a/docs/framework/preact/reference/functions/useQueryClient.md b/docs/framework/preact/reference/functions/useQueryClient.md
index 61be8c5af45..dd4a572d39b 100644
--- a/docs/framework/preact/reference/functions/useQueryClient.md
+++ b/docs/framework/preact/reference/functions/useQueryClient.md
@@ -7,7 +7,9 @@ title: useQueryClient
 function useQueryClient(queryClient?): QueryClient;
 ```
 
-Defined in: [preact-query/src/QueryClientProvider.tsx:10](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryClientProvider.tsx#L10)
+Defined in: [preact-query/src/QueryClientProvider.tsx:16](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryClientProvider.tsx#L16)
+
+The `useQueryClient` hook returns the current `QueryClient` instance.
 
 ## Parameters
 
@@ -15,6 +17,9 @@ Defined in: [preact-query/src/QueryClientProvider.tsx:10](https://github.com/Tan
 
 `QueryClient`
 
+Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
+be used.
+
 ## Returns
 
 `QueryClient`
diff --git a/docs/framework/preact/reference/functions/useQueryErrorResetBoundary.md b/docs/framework/preact/reference/functions/useQueryErrorResetBoundary.md
index d9b96677a42..62ebccdc088 100644
--- a/docs/framework/preact/reference/functions/useQueryErrorResetBoundary.md
+++ b/docs/framework/preact/reference/functions/useQueryErrorResetBoundary.md
@@ -7,8 +7,34 @@ title: useQueryErrorResetBoundary
 function useQueryErrorResetBoundary(): QueryErrorResetBoundaryValue;
 ```
 
-Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:35](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L35)
+Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:61](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L61)
+
+This hook will reset any query errors within the closest `QueryErrorResetBoundary`. If there is no boundary
+defined it will reset them globally.
 
 ## Returns
 
 `QueryErrorResetBoundaryValue`
+
+## Example
+
+```tsx
+import { useErrorBoundary } from 'preact/hooks'
+import { useQueryErrorResetBoundary } from '@tanstack/preact-query'
+
+function App({ children }: { children: ComponentChildren }) {
+  const { reset } = useQueryErrorResetBoundary()
+  const [error, resetError] = useErrorBoundary(() => reset())
+
+  if (error) {
+    return (
+      <div>
+        There was an error!
+        <button onClick={() => resetError()}>Try again</button>
+      </div>
+    )
+  }
+
+  return children
+}
+```
diff --git a/docs/framework/preact/reference/functions/useSuspenseInfiniteQuery.md b/docs/framework/preact/reference/functions/useSuspenseInfiniteQuery.md
index 230d861343d..7e7f3d5bfa6 100644
--- a/docs/framework/preact/reference/functions/useSuspenseInfiniteQuery.md
+++ b/docs/framework/preact/reference/functions/useSuspenseInfiniteQuery.md
@@ -7,7 +7,10 @@ title: useSuspenseInfiniteQuery
 function useSuspenseInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): UseSuspenseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useSuspenseInfiniteQuery.ts:18](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseInfiniteQuery.ts#L18)
+Defined in: [preact-query/src/useSuspenseInfiniteQuery.ts:28](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseInfiniteQuery.ts#L28)
+
+The options for `useSuspenseInfiniteQuery` are the same as for `useInfiniteQuery`, except for `throwOnError`,
+`enabled`, and `placeholderData`.
 
 ## Type Parameters
 
@@ -44,3 +47,9 @@ Defined in: [preact-query/src/useSuspenseInfiniteQuery.ts:18](https://github.com
 ## Returns
 
 [`UseSuspenseInfiniteQueryResult`](../type-aliases/UseSuspenseInfiniteQueryResult.md)\<`TData`, `TError`\>
+
+The same object as `useInfiniteQuery`, except that `data` is guaranteed to be defined,
+`isPlaceholderData` is missing, and `status` is either `success` or `error` (with the derived flags set
+accordingly).
+
+Caveat: cancellation does not work.
diff --git a/docs/framework/preact/reference/functions/useSuspenseQueries.md b/docs/framework/preact/reference/functions/useSuspenseQueries.md
index 7fd0a764978..108937eb6fb 100644
--- a/docs/framework/preact/reference/functions/useSuspenseQueries.md
+++ b/docs/framework/preact/reference/functions/useSuspenseQueries.md
@@ -9,7 +9,10 @@ title: useSuspenseQueries
 function useSuspenseQueries<T, TCombinedResult>(options, queryClient?): TCombinedResult;
 ```
 
-Defined in: [preact-query/src/useSuspenseQueries.ts:165](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseQueries.ts#L165)
+Defined in: [preact-query/src/useSuspenseQueries.ts:177](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseQueries.ts#L177)
+
+The options for `useSuspenseQueries` are the same as for `useQueries`, except that each `query` can't have
+`throwOnError`, `enabled`, or `placeholderData`.
 
 ### Type Parameters
 
@@ -42,13 +45,24 @@ Defined in: [preact-query/src/useSuspenseQueries.ts:165](https://github.com/TanS
 
 `TCombinedResult`
 
+The same structure as `useQueries`, except that for each `query`, `data` is guaranteed to be
+defined, `isPlaceholderData` is missing, and `status` is either `success` or `error` (with the derived
+flags set accordingly).
+
+Caveat: the component will only re-mount after all queries have finished loading. Hence, if a query has gone
+stale in the time it took for all the queries to complete, it will be fetched again at re-mount. To avoid
+this, make sure to set a high enough `staleTime`. Cancellation does not work.
+
 ## Call Signature
 
 ```ts
 function useSuspenseQueries<T, TCombinedResult>(options, queryClient?): TCombinedResult;
 ```
 
-Defined in: [preact-query/src/useSuspenseQueries.ts:178](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseQueries.ts#L178)
+Defined in: [preact-query/src/useSuspenseQueries.ts:202](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseQueries.ts#L202)
+
+The options for `useSuspenseQueries` are the same as for `useQueries`, except that each `query` can't have
+`throwOnError`, `enabled`, or `placeholderData`.
 
 ### Type Parameters
 
@@ -79,3 +93,11 @@ readonly \[`T` *extends* \[\] ? \[\] : `T` *extends* \[`Head`\] ? \[`GetUseSuspe
 ### Returns
 
 `TCombinedResult`
+
+The same structure as `useQueries`, except that for each `query`, `data` is guaranteed to be
+defined, `isPlaceholderData` is missing, and `status` is either `success` or `error` (with the derived
+flags set accordingly).
+
+Caveat: the component will only re-mount after all queries have finished loading. Hence, if a query has gone
+stale in the time it took for all the queries to complete, it will be fetched again at re-mount. To avoid
+this, make sure to set a high enough `staleTime`. Cancellation does not work.
diff --git a/docs/framework/preact/reference/functions/useSuspenseQuery.md b/docs/framework/preact/reference/functions/useSuspenseQuery.md
index 7750202206d..b6dec950a43 100644
--- a/docs/framework/preact/reference/functions/useSuspenseQuery.md
+++ b/docs/framework/preact/reference/functions/useSuspenseQuery.md
@@ -7,7 +7,10 @@ title: useSuspenseQuery
 function useSuspenseQuery<TQueryFnData, TError, TData, TQueryKey>(options, queryClient?): UseSuspenseQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useSuspenseQuery.ts:8](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseQuery.ts#L8)
+Defined in: [preact-query/src/useSuspenseQuery.ts:17](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseQuery.ts#L17)
+
+The options for `useSuspenseQuery` are the same as for `useQuery`, except for `throwOnError`, `enabled`, and
+`placeholderData`.
 
 ## Type Parameters
 
@@ -40,3 +43,8 @@ Defined in: [preact-query/src/useSuspenseQuery.ts:8](https://github.com/TanStack
 ## Returns
 
 [`UseSuspenseQueryResult`](../type-aliases/UseSuspenseQueryResult.md)\<`TData`, `TError`\>
+
+The same object as `useQuery`, except that `data` is guaranteed to be defined, `isPlaceholderData`
+is missing, and `status` is either `success` or `error` (with the derived flags set accordingly).
+
+Caveat: cancellation does not work.
diff --git a/docs/framework/preact/reference/interfaces/HydrationBoundaryProps.md b/docs/framework/preact/reference/interfaces/HydrationBoundaryProps.md
index 3470aedf9c5..e7bc72ec8d3 100644
--- a/docs/framework/preact/reference/interfaces/HydrationBoundaryProps.md
+++ b/docs/framework/preact/reference/interfaces/HydrationBoundaryProps.md
@@ -13,7 +13,7 @@ Defined in: [preact-query/src/HydrationBoundary.tsx:14](https://github.com/TanSt
 optional children: ComponentChildren;
 ```
 
-Defined in: [preact-query/src/HydrationBoundary.tsx:22](https://github.com/TanStack/query/blob/main/packages/preact-query/src/HydrationBoundary.tsx#L22)
+Defined in: [preact-query/src/HydrationBoundary.tsx:28](https://github.com/TanStack/query/blob/main/packages/preact-query/src/HydrationBoundary.tsx#L28)
 
 ***
 
@@ -23,7 +23,9 @@ Defined in: [preact-query/src/HydrationBoundary.tsx:22](https://github.com/TanSt
 optional options: OmitKeyof<HydrateOptions, "defaultOptions"> & object;
 ```
 
-Defined in: [preact-query/src/HydrationBoundary.tsx:16](https://github.com/TanStack/query/blob/main/packages/preact-query/src/HydrationBoundary.tsx#L16)
+Defined in: [preact-query/src/HydrationBoundary.tsx:22](https://github.com/TanStack/query/blob/main/packages/preact-query/src/HydrationBoundary.tsx#L22)
+
+Optional. Note: unlike `hydrate`, `mutations` cannot be set here.
 
 #### Type Declaration
 
@@ -42,7 +44,9 @@ optional defaultOptions: OmitKeyof<{
 optional queryClient: QueryClient;
 ```
 
-Defined in: [preact-query/src/HydrationBoundary.tsx:23](https://github.com/TanStack/query/blob/main/packages/preact-query/src/HydrationBoundary.tsx#L23)
+Defined in: [preact-query/src/HydrationBoundary.tsx:32](https://github.com/TanStack/query/blob/main/packages/preact-query/src/HydrationBoundary.tsx#L32)
+
+Use this to use a custom QueryClient. Otherwise, the one from the nearest context will be used.
 
 ***
 
@@ -52,4 +56,6 @@ Defined in: [preact-query/src/HydrationBoundary.tsx:23](https://github.com/TanSt
 state: DehydratedState | null | undefined;
 ```
 
-Defined in: [preact-query/src/HydrationBoundary.tsx:15](https://github.com/TanStack/query/blob/main/packages/preact-query/src/HydrationBoundary.tsx#L15)
+Defined in: [preact-query/src/HydrationBoundary.tsx:18](https://github.com/TanStack/query/blob/main/packages/preact-query/src/HydrationBoundary.tsx#L18)
+
+The state to hydrate.
diff --git a/docs/framework/preact/reference/interfaces/QueryErrorResetBoundaryProps.md b/docs/framework/preact/reference/interfaces/QueryErrorResetBoundaryProps.md
index ea3ebed77e4..dab7497f1cf 100644
--- a/docs/framework/preact/reference/interfaces/QueryErrorResetBoundaryProps.md
+++ b/docs/framework/preact/reference/interfaces/QueryErrorResetBoundaryProps.md
@@ -3,7 +3,7 @@ id: QueryErrorResetBoundaryProps
 title: QueryErrorResetBoundaryProps
 ---
 
-Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:44](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L44)
+Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:70](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L70)
 
 ## Properties
 
@@ -15,4 +15,4 @@ children:
   | QueryErrorResetBoundaryFunction;
 ```
 
-Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:45](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L45)
+Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:71](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L71)
diff --git a/docs/framework/preact/reference/type-aliases/QueryClientProviderProps.md b/docs/framework/preact/reference/type-aliases/QueryClientProviderProps.md
index 0d835b30c94..d13af4859ca 100644
--- a/docs/framework/preact/reference/type-aliases/QueryClientProviderProps.md
+++ b/docs/framework/preact/reference/type-aliases/QueryClientProviderProps.md
@@ -7,7 +7,7 @@ title: QueryClientProviderProps
 type QueryClientProviderProps = object;
 ```
 
-Defined in: [preact-query/src/QueryClientProvider.tsx:24](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryClientProvider.tsx#L24)
+Defined in: [preact-query/src/QueryClientProvider.tsx:30](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryClientProvider.tsx#L30)
 
 ## Properties
 
@@ -17,7 +17,7 @@ Defined in: [preact-query/src/QueryClientProvider.tsx:24](https://github.com/Tan
 optional children: ComponentChildren;
 ```
 
-Defined in: [preact-query/src/QueryClientProvider.tsx:26](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryClientProvider.tsx#L26)
+Defined in: [preact-query/src/QueryClientProvider.tsx:37](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryClientProvider.tsx#L37)
 
 ***
 
@@ -27,4 +27,8 @@ Defined in: [preact-query/src/QueryClientProvider.tsx:26](https://github.com/Tan
 client: QueryClient;
 ```
 
-Defined in: [preact-query/src/QueryClientProvider.tsx:25](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryClientProvider.tsx#L25)
+Defined in: [preact-query/src/QueryClientProvider.tsx:36](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryClientProvider.tsx#L36)
+
+**Required**
+
+The QueryClient instance to provide.
diff --git a/docs/framework/preact/reference/type-aliases/QueryErrorResetBoundaryFunction.md b/docs/framework/preact/reference/type-aliases/QueryErrorResetBoundaryFunction.md
index 4d6027cea02..f44fc3d5f75 100644
--- a/docs/framework/preact/reference/type-aliases/QueryErrorResetBoundaryFunction.md
+++ b/docs/framework/preact/reference/type-aliases/QueryErrorResetBoundaryFunction.md
@@ -7,7 +7,7 @@ title: QueryErrorResetBoundaryFunction
 type QueryErrorResetBoundaryFunction = (value) => ComponentChildren;
 ```
 
-Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:40](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L40)
+Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:66](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L66)
 
 ## Parameters
 
diff --git a/packages/preact-query/src/HydrationBoundary.tsx b/packages/preact-query/src/HydrationBoundary.tsx
index 1f860f9e385..079782356e8 100644
--- a/packages/preact-query/src/HydrationBoundary.tsx
+++ b/packages/preact-query/src/HydrationBoundary.tsx
@@ -12,7 +12,13 @@ import { useEffect, useMemo, useRef } from 'preact/hooks'
 import { useQueryClient } from './QueryClientProvider'
 
 export interface HydrationBoundaryProps {
+  /**
+   * The state to hydrate.
+   */
   state: DehydratedState | null | undefined
+  /**
+   * Optional. Note: unlike `hydrate`, `mutations` cannot be set here.
+   */
   options?: OmitKeyof<HydrateOptions, 'defaultOptions'> & {
     defaultOptions?: OmitKeyof<
       Exclude<HydrateOptions['defaultOptions'], undefined>,
@@ -20,9 +26,28 @@ export interface HydrationBoundaryProps {
     >
   }
   children?: ComponentChildren
+  /**
+   * Use this to use a custom QueryClient. Otherwise, the one from the nearest context will be used.
+   */
   queryClient?: QueryClient
 }
 
+/**
+ * `HydrationBoundary` adds a previously dehydrated state into the `queryClient` that would be returned by
+ * `useQueryClient()`. If the client already contains data, the new queries will be intelligently merged based on
+ * update timestamp.
+ *
+ * Note: Only `queries` can be dehydrated with an `HydrationBoundary`.
+ *
+ * @example
+ * ```tsx
+ * import { HydrationBoundary } from '@tanstack/preact-query'
+ *
+ * function App() {
+ *   return <HydrationBoundary state={dehydratedState}>...</HydrationBoundary>
+ * }
+ * ```
+ */
 export const HydrationBoundary = ({
   children,
   options = {},
diff --git a/packages/preact-query/src/QueryClientProvider.tsx b/packages/preact-query/src/QueryClientProvider.tsx
index b4a1dfa1b58..9d438e3fba0 100644
--- a/packages/preact-query/src/QueryClientProvider.tsx
+++ b/packages/preact-query/src/QueryClientProvider.tsx
@@ -7,6 +7,12 @@ export const QueryClientContext = createContext<QueryClient | undefined>(
   undefined,
 )
 
+/**
+ * The `useQueryClient` hook returns the current `QueryClient` instance.
+ *
+ * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
+ * be used.
+ */
 export const useQueryClient = (queryClient?: QueryClient) => {
   const client = useContext(QueryClientContext)
 
@@ -22,10 +28,29 @@ export const useQueryClient = (queryClient?: QueryClient) => {
 }
 
 export type QueryClientProviderProps = {
+  /**
+   * **Required**
+   *
+   * The QueryClient instance to provide.
+   */
   client: QueryClient
   children?: ComponentChildren
 }
 
+/**
+ * Use the `QueryClientProvider` component to connect and provide a `QueryClient` to your application.
+ *
+ * @example
+ * ```tsx
+ * import { QueryClient, QueryClientProvider } from '@tanstack/preact-query'
+ *
+ * const queryClient = new QueryClient()
+ *
+ * function App() {
+ *   return <QueryClientProvider client={queryClient}>...</QueryClientProvider>
+ * }
+ * ```
+ */
 export const QueryClientProvider = ({
   client,
   children,
diff --git a/packages/preact-query/src/QueryErrorResetBoundary.tsx b/packages/preact-query/src/QueryErrorResetBoundary.tsx
index ed038bc31b2..f3329d6790a 100644
--- a/packages/preact-query/src/QueryErrorResetBoundary.tsx
+++ b/packages/preact-query/src/QueryErrorResetBoundary.tsx
@@ -32,6 +32,32 @@ const QueryErrorResetBoundaryContext = createContext(createValue())
 
 // HOOK
 
+/**
+ * This hook will reset any query errors within the closest `QueryErrorResetBoundary`. If there is no boundary
+ * defined it will reset them globally.
+ *
+ * @example
+ * ```tsx
+ * import { useErrorBoundary } from 'preact/hooks'
+ * import { useQueryErrorResetBoundary } from '@tanstack/preact-query'
+ *
+ * function App({ children }: { children: ComponentChildren }) {
+ *   const { reset } = useQueryErrorResetBoundary()
+ *   const [error, resetError] = useErrorBoundary(() => reset())
+ *
+ *   if (error) {
+ *     return (
+ *       <div>
+ *         There was an error!
+ *         <button onClick={() => resetError()}>Try again</button>
+ *       </div>
+ *     )
+ *   }
+ *
+ *   return children
+ * }
+ * ```
+ */
 export const useQueryErrorResetBoundary = () =>
   useContext(QueryErrorResetBoundaryContext)
 
@@ -45,6 +71,48 @@ export interface QueryErrorResetBoundaryProps {
   children: QueryErrorResetBoundaryFunction | ComponentChildren
 }
 
+/**
+ * When using **suspense** or **throwOnError** in your queries, you need a way to let queries know that you want to
+ * try again when re-rendering after some error occurred. With the `QueryErrorResetBoundary` component you can
+ * reset any query errors within the boundaries of the component.
+ *
+ * @example
+ * ```tsx
+ * import { useErrorBoundary } from 'preact/hooks'
+ * import { QueryErrorResetBoundary } from '@tanstack/preact-query'
+ *
+ * function ErrorBoundary({
+ *   children,
+ *   reset,
+ * }: {
+ *   children: ComponentChildren
+ *   reset: () => void
+ * }) {
+ *   const [error, resetError] = useErrorBoundary(() => reset())
+ *
+ *   if (error) {
+ *     return (
+ *       <div>
+ *         There was an error!
+ *         <button onClick={() => resetError()}>Try again</button>
+ *       </div>
+ *     )
+ *   }
+ *
+ *   return children
+ * }
+ *
+ * const App = () => (
+ *   <QueryErrorResetBoundary>
+ *     {({ reset }) => (
+ *       <ErrorBoundary reset={reset}>
+ *         <Page />
+ *       </ErrorBoundary>
+ *     )}
+ *   </QueryErrorResetBoundary>
+ * )
+ * ```
+ */
 export const QueryErrorResetBoundary = ({
   children,
 }: QueryErrorResetBoundaryProps) => {
diff --git a/packages/preact-query/src/infiniteQueryOptions.ts b/packages/preact-query/src/infiniteQueryOptions.ts
index 660f00b1de3..22d4f7068f6 100644
--- a/packages/preact-query/src/infiniteQueryOptions.ts
+++ b/packages/preact-query/src/infiniteQueryOptions.ts
@@ -73,6 +73,11 @@ export type DefinedInitialDataInfiniteOptions<
     | undefined
 }
 
+/**
+ * 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`.
+ * `options.queryKey` is required and is the query key to generate options for.
+ */
 export function infiniteQueryOptions<
   TQueryFnData,
   TError = DefaultError,
@@ -96,6 +101,11 @@ export function infiniteQueryOptions<
 > &
   QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>
 
+/**
+ * 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`.
+ * `options.queryKey` is required and is the query key to generate options for.
+ */
 export function infiniteQueryOptions<
   TQueryFnData,
   TError = DefaultError,
@@ -119,6 +129,11 @@ export function infiniteQueryOptions<
 > &
   QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>
 
+/**
+ * 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`.
+ * `options.queryKey` is required and is the query key to generate options for.
+ */
 export function infiniteQueryOptions<
   TQueryFnData,
   TError = DefaultError,
diff --git a/packages/preact-query/src/mutationOptions.ts b/packages/preact-query/src/mutationOptions.ts
index 5c926a7e3d0..67556b7a79b 100644
--- a/packages/preact-query/src/mutationOptions.ts
+++ b/packages/preact-query/src/mutationOptions.ts
@@ -2,6 +2,9 @@ import type { DefaultError, WithRequired } from '@tanstack/query-core'
 
 import type { UseMutationOptions } from './types'
 
+/**
+ * You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`.
+ */
 export function mutationOptions<
   TData = unknown,
   TError = DefaultError,
@@ -16,6 +19,9 @@ export function mutationOptions<
   UseMutationOptions<TData, TError, TVariables, TOnMutateResult>,
   'mutationKey'
 >
+/**
+ * You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`.
+ */
 export function mutationOptions<
   TData = unknown,
   TError = DefaultError,
diff --git a/packages/preact-query/src/queryOptions.ts b/packages/preact-query/src/queryOptions.ts
index 3b61de09126..3883f9cf368 100644
--- a/packages/preact-query/src/queryOptions.ts
+++ b/packages/preact-query/src/queryOptions.ts
@@ -50,6 +50,24 @@ export type DefinedInitialDataOptions<
   queryFn?: QueryFunction<TQueryFnData, TQueryKey>
 }
 
+/**
+ * You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can
+ * be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and
+ * is the query key to generate options for.
+ *
+ * @example
+ * ```tsx
+ * import { queryOptions } from '@tanstack/preact-query'
+ *
+ * export const pokemonOptions = queryOptions({
+ *   queryKey: ['pokemon'],
+ *   queryFn: async () => {
+ *     const response = await fetch('https://pokeapi.co/api/v2/pokemon/25')
+ *     return response.json()
+ *   },
+ * })
+ * ```
+ */
 export function queryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -60,6 +78,24 @@ export function queryOptions<
 ): DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey> &
   QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>
 
+/**
+ * You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can
+ * be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and
+ * is the query key to generate options for.
+ *
+ * @example
+ * ```tsx
+ * import { queryOptions } from '@tanstack/preact-query'
+ *
+ * export const pokemonOptions = queryOptions({
+ *   queryKey: ['pokemon'],
+ *   queryFn: async () => {
+ *     const response = await fetch('https://pokeapi.co/api/v2/pokemon/25')
+ *     return response.json()
+ *   },
+ * })
+ * ```
+ */
 export function queryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -70,6 +106,24 @@ export function queryOptions<
 ): UnusedSkipTokenOptions<TQueryFnData, TError, TData, TQueryKey> &
   QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>
 
+/**
+ * You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can
+ * be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and
+ * is the query key to generate options for.
+ *
+ * @example
+ * ```tsx
+ * import { queryOptions } from '@tanstack/preact-query'
+ *
+ * export const pokemonOptions = queryOptions({
+ *   queryKey: ['pokemon'],
+ *   queryFn: async () => {
+ *     const response = await fetch('https://pokeapi.co/api/v2/pokemon/25')
+ *     return response.json()
+ *   },
+ * })
+ * ```
+ */
 export function queryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
diff --git a/packages/preact-query/src/useInfiniteQuery.ts b/packages/preact-query/src/useInfiniteQuery.ts
index f78c14a2375..548f9acbe6b 100644
--- a/packages/preact-query/src/useInfiniteQuery.ts
+++ b/packages/preact-query/src/useInfiniteQuery.ts
@@ -18,6 +18,13 @@ import type {
 } from './types'
 import { useBaseQuery } from './useBaseQuery'
 
+/**
+ * The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
+ * `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
+ *
+ * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
+ * be used.
+ */
 export function useInfiniteQuery<
   TQueryFnData,
   TError = DefaultError,
@@ -35,6 +42,13 @@ export function useInfiniteQuery<
   queryClient?: QueryClient,
 ): DefinedUseInfiniteQueryResult<TData, TError>
 
+/**
+ * The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
+ * `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
+ *
+ * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
+ * be used.
+ */
 export function useInfiniteQuery<
   TQueryFnData,
   TError = DefaultError,
@@ -52,6 +66,47 @@ export function useInfiniteQuery<
   queryClient?: QueryClient,
 ): UseInfiniteQueryResult<TData, TError>
 
+/**
+ * The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
+ * `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
+ *
+ * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
+ * be used.
+ * @returns The same properties as `useQuery`, with the addition of `data.pages`, `data.pageParams`,
+ * `fetchNextPage`, `fetchPreviousPage`, `hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and
+ * `isFetchingPreviousPage`.
+ *
+ * Keep in mind that imperative fetch calls, such as `fetchNextPage`, may interfere with the default refetch
+ * behaviour, resulting in outdated data. Make sure to call these functions only in response to user actions,
+ * or add conditions like `hasNextPage && !isFetching`.
+ *
+ * @example
+ * ```tsx
+ * import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
+ *
+ * const projectsOptions = infiniteQueryOptions({
+ *   queryKey: ['projects'],
+ *   queryFn: ({ pageParam }) =>
+ *     fetch(`/api/projects?cursor=${pageParam}`).then((r) => r.json()),
+ *   initialPageParam: 0,
+ *   getNextPageParam: (lastPage) => lastPage.nextId,
+ * })
+ *
+ * function Projects() {
+ *   const { data, fetchNextPage, hasNextPage, isFetchingNextPage } =
+ *     useInfiniteQuery(projectsOptions)
+ *
+ *   return (
+ *     <button
+ *       onClick={() => fetchNextPage()}
+ *       disabled={!hasNextPage || isFetchingNextPage}
+ *     >
+ *       Load More
+ *     </button>
+ *   )
+ * }
+ * ```
+ */
 export function useInfiniteQuery<
   TQueryFnData,
   TError = DefaultError,
diff --git a/packages/preact-query/src/useIsFetching.ts b/packages/preact-query/src/useIsFetching.ts
index 07be71c5953..e75f6ac2596 100644
--- a/packages/preact-query/src/useIsFetching.ts
+++ b/packages/preact-query/src/useIsFetching.ts
@@ -5,6 +5,26 @@ import { useCallback } from 'preact/hooks'
 import { useQueryClient } from './QueryClientProvider'
 import { useSyncExternalStore } from './utils'
 
+/**
+ * `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).
+ *
+ * @param filters - {@link QueryFilters}
+ * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
+ * be used.
+ * @returns Will be the `number` of the queries that your application is currently loading or fetching in the
+ * background.
+ *
+ * @example
+ * ```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'] })
+ * ```
+ */
 export function useIsFetching(
   filters?: QueryFilters,
   queryClient?: QueryClient,
diff --git a/packages/preact-query/src/useMutation.ts b/packages/preact-query/src/useMutation.ts
index 495aaadd910..dafc8806143 100644
--- a/packages/preact-query/src/useMutation.ts
+++ b/packages/preact-query/src/useMutation.ts
@@ -17,6 +17,28 @@ import { useSyncExternalStore } from './utils'
 
 // HOOK
 
+/**
+ * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
+ * be used.
+ *
+ * @example
+ * ```tsx
+ * import { useMutation, useQueryClient } from '@tanstack/preact-query'
+ *
+ * function Example() {
+ *   const queryClient = useQueryClient()
+ *
+ *   const addMutation = useMutation({
+ *     mutationFn: (add: string) => fetch(`/api/data?add=${add}`),
+ *     onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
+ *   })
+ *
+ *   return (
+ *     <button onClick={() => addMutation.mutate('Item')}>Add</button>
+ *   )
+ * }
+ * ```
+ */
 export function useMutation<
   TData = unknown,
   TError = DefaultError,
diff --git a/packages/preact-query/src/useMutationState.ts b/packages/preact-query/src/useMutationState.ts
index b998467925f..759174468ac 100644
--- a/packages/preact-query/src/useMutationState.ts
+++ b/packages/preact-query/src/useMutationState.ts
@@ -11,6 +11,25 @@ import { useCallback, useEffect, useRef } from 'preact/hooks'
 import { useQueryClient } from './QueryClientProvider'
 import { useSyncExternalStore } from './utils'
 
+/**
+ * `useIsMutating` is an optional hook that returns the `number` of mutations that your application is fetching
+ * (useful for app-wide loading indicators).
+ *
+ * @param filters - {@link MutationFilters}
+ * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
+ * be used.
+ * @returns Will be the `number` of the mutations that your application is currently fetching.
+ *
+ * @example
+ * ```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'] })
+ * ```
+ */
 export function useIsMutating(
   filters?: MutationFilters,
   queryClient?: QueryClient,
@@ -60,6 +79,49 @@ function getResult<
     )
 }
 
+/**
+ * `useMutationState` is a hook that gives you access to all mutations in the `MutationCache`. You can pass
+ * `filters` to it to narrow down your mutations, and `select` to transform the mutation state.
+ *
+ * @param options.filters - {@link MutationFilters}
+ * @param options.select - Use this to transform the mutation state.
+ * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
+ * be used.
+ * @returns Will be an Array of whatever `select` returns for each matching mutation.
+ *
+ * @example
+ * 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,
+ * })
+ * ```
+ *
+ * @example
+ * Get all data for specific mutations via the `mutationKey`:
+ * ```tsx
+ * 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: (newPost) => {
+ *     return axios.post('/posts', newPost)
+ *   },
+ * })
+ *
+ * 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,
+ * })
+ * ```
+ */
 export function useMutationState<
   TResult = MutationState,
   TMutation extends Mutation<any, any, any, any> =
diff --git a/packages/preact-query/src/usePrefetchInfiniteQuery.tsx b/packages/preact-query/src/usePrefetchInfiniteQuery.tsx
index acfdc2bd324..9526b2ef9e4 100644
--- a/packages/preact-query/src/usePrefetchInfiniteQuery.tsx
+++ b/packages/preact-query/src/usePrefetchInfiniteQuery.tsx
@@ -4,6 +4,18 @@ import { useQueryClient } from './QueryClientProvider'
 import type { DefaultError, QueryClient, QueryKey } from '@tanstack/query-core'
 import type { UsePrefetchInfiniteQueryOptions } from './types'
 
+/**
+ * `usePrefetchInfiniteQuery` does not return anything, it should be used just to fire a prefetch during render,
+ * before a suspense boundary that wraps a component that uses `useSuspenseInfiniteQuery`. You can pass
+ * everything to `usePrefetchInfiniteQuery` that you can pass to `queryClient.fetchInfiniteQuery`, though
+ * `queryKey`, `initialPageParam`, and `getNextPageParam` are always required, and `queryFn` is required unless
+ * a default query function has been defined.
+ *
+ * `getNextPageParam` receives both the last page of the infinite list of data and the full array of all pages,
+ * as well as pageParam information, and should return a single variable that will be passed as the last
+ * optional parameter to your query function. Return `undefined` or `null` to indicate there is no next page
+ * available.
+ */
 export function usePrefetchInfiniteQuery<
   TQueryFnData = unknown,
   TError = DefaultError,
diff --git a/packages/preact-query/src/usePrefetchQuery.tsx b/packages/preact-query/src/usePrefetchQuery.tsx
index 376bf157c5d..08cb1f69be9 100644
--- a/packages/preact-query/src/usePrefetchQuery.tsx
+++ b/packages/preact-query/src/usePrefetchQuery.tsx
@@ -4,6 +4,12 @@ import { useQueryClient } from './QueryClientProvider'
 import type { DefaultError, QueryClient, QueryKey } from '@tanstack/query-core'
 import type { UsePrefetchQueryOptions } from './types'
 
+/**
+ * `usePrefetchQuery` does not return anything, it should be used just to fire a prefetch during render, before
+ * a suspense boundary that wraps a component that uses `useSuspenseQuery`. You can pass everything to
+ * `usePrefetchQuery` that you can pass to `queryClient.fetchQuery`, though `queryKey` is always required, and
+ * `queryFn` is required unless a default query function has been defined.
+ */
 export function usePrefetchQuery<
   TQueryFnData = unknown,
   TError = DefaultError,
diff --git a/packages/preact-query/src/useQueries.ts b/packages/preact-query/src/useQueries.ts
index dac252d0109..4709b971a95 100644
--- a/packages/preact-query/src/useQueries.ts
+++ b/packages/preact-query/src/useQueries.ts
@@ -204,6 +204,55 @@ export type QueriesResults<
           >
         : { [K in keyof T]: GetUseQueryResult<T[K]> }
 
+/**
+ * The `useQueries` hook can be used to fetch a variable number of queries.
+ *
+ * The `queries` key accepts an array with query option objects identical to `useQuery` (excluding the
+ * `queryClient` option - because the `QueryClient` can be passed in on the top level).
+ *
+ * Having the same query key more than once in the array of query objects may cause some data to be shared
+ * between queries. To avoid this, consider de-duplicating the queries and map the results back to the desired
+ * structure.
+ *
+ * The `combine` option can be used to combine the results of the queries into a single value. The result will
+ * be structurally shared to be as referentially stable as possible.
+ *
+ * @param queryClient - Use this to provide a custom QueryClient. Otherwise, the one from the nearest context
+ * will be used.
+ * @returns An array with all the query results. The order returned is the same as the input order.
+ *
+ * @example
+ * ```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,
+ *   })),
+ * })
+ * ```
+ *
+ * @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),
+ *     }
+ *   },
+ * })
+ * ```
+ */
 export function useQueries<
   T extends Array<any>,
   TCombinedResult = QueriesResults<T>,
diff --git a/packages/preact-query/src/useQuery.ts b/packages/preact-query/src/useQuery.ts
index 2d6c5dcec1c..1877f068d58 100644
--- a/packages/preact-query/src/useQuery.ts
+++ b/packages/preact-query/src/useQuery.ts
@@ -12,6 +12,10 @@ import type {
 } from './types'
 import { useBaseQuery } from './useBaseQuery'
 
+/**
+ * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
+ * be used.
+ */
 export function useQuery<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -22,6 +26,10 @@ export function useQuery<
   queryClient?: QueryClient,
 ): DefinedUseQueryResult<TData, TError>
 
+/**
+ * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
+ * be used.
+ */
 export function useQuery<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -32,6 +40,39 @@ export function useQuery<
   queryClient?: QueryClient,
 ): UseQueryResult<TData, TError>
 
+/**
+ * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
+ * be used.
+ *
+ * @example
+ * ```tsx
+ * import { queryOptions, useQuery } from '@tanstack/preact-query'
+ *
+ * const postsOptions = queryOptions({
+ *   queryKey: ['posts'],
+ *   queryFn: async () => {
+ *     const response = await fetch('https://jsonplaceholder.typicode.com/posts')
+ *     return await response.json()
+ *   },
+ * })
+ *
+ * function Posts() {
+ *   const { status, data, error, isFetching } = useQuery(postsOptions)
+ *
+ *   if (status === 'pending') return 'Loading...'
+ *   if (status === 'error') return <span>Error: {error.message}</span>
+ *
+ *   return (
+ *     <div>
+ *       {data.map((post) => (
+ *         <p key={post.id}>{post.title}</p>
+ *       ))}
+ *       <div>{isFetching ? 'Background Updating...' : ' '}</div>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
 export function useQuery<
   TQueryFnData = unknown,
   TError = DefaultError,
diff --git a/packages/preact-query/src/useSuspenseInfiniteQuery.ts b/packages/preact-query/src/useSuspenseInfiniteQuery.ts
index 90a1c06d356..6aac2746af2 100644
--- a/packages/preact-query/src/useSuspenseInfiniteQuery.ts
+++ b/packages/preact-query/src/useSuspenseInfiniteQuery.ts
@@ -15,6 +15,16 @@ import type {
 } from './types'
 import { useBaseQuery } from './useBaseQuery'
 
+/**
+ * The options for `useSuspenseInfiniteQuery` are the same as for `useInfiniteQuery`, except for `throwOnError`,
+ * `enabled`, and `placeholderData`.
+ *
+ * @returns The same object as `useInfiniteQuery`, except that `data` is guaranteed to be defined,
+ * `isPlaceholderData` is missing, and `status` is either `success` or `error` (with the derived flags set
+ * accordingly).
+ *
+ * Caveat: cancellation does not work.
+ */
 export function useSuspenseInfiniteQuery<
   TQueryFnData,
   TError = DefaultError,
diff --git a/packages/preact-query/src/useSuspenseQueries.ts b/packages/preact-query/src/useSuspenseQueries.ts
index 191c25458c3..22c54583149 100644
--- a/packages/preact-query/src/useSuspenseQueries.ts
+++ b/packages/preact-query/src/useSuspenseQueries.ts
@@ -162,6 +162,18 @@ export type SuspenseQueriesResults<
           >
         : { [K in keyof T]: GetUseSuspenseQueryResult<T[K]> }
 
+/**
+ * The options for `useSuspenseQueries` are the same as for `useQueries`, except that each `query` can't have
+ * `throwOnError`, `enabled`, or `placeholderData`.
+ *
+ * @returns The same structure as `useQueries`, except that for each `query`, `data` is guaranteed to be
+ * defined, `isPlaceholderData` is missing, and `status` is either `success` or `error` (with the derived
+ * flags set accordingly).
+ *
+ * Caveat: the component will only re-mount after all queries have finished loading. Hence, if a query has gone
+ * stale in the time it took for all the queries to complete, it will be fetched again at re-mount. To avoid
+ * this, make sure to set a high enough `staleTime`. Cancellation does not work.
+ */
 export function useSuspenseQueries<
   T extends Array<any>,
   TCombinedResult = SuspenseQueriesResults<T>,
@@ -175,6 +187,18 @@ export function useSuspenseQueries<
   queryClient?: QueryClient,
 ): TCombinedResult
 
+/**
+ * The options for `useSuspenseQueries` are the same as for `useQueries`, except that each `query` can't have
+ * `throwOnError`, `enabled`, or `placeholderData`.
+ *
+ * @returns The same structure as `useQueries`, except that for each `query`, `data` is guaranteed to be
+ * defined, `isPlaceholderData` is missing, and `status` is either `success` or `error` (with the derived
+ * flags set accordingly).
+ *
+ * Caveat: the component will only re-mount after all queries have finished loading. Hence, if a query has gone
+ * stale in the time it took for all the queries to complete, it will be fetched again at re-mount. To avoid
+ * this, make sure to set a high enough `staleTime`. Cancellation does not work.
+ */
 export function useSuspenseQueries<
   T extends Array<any>,
   TCombinedResult = SuspenseQueriesResults<T>,
diff --git a/packages/preact-query/src/useSuspenseQuery.ts b/packages/preact-query/src/useSuspenseQuery.ts
index ad2ff4cca63..0b9879a40f9 100644
--- a/packages/preact-query/src/useSuspenseQuery.ts
+++ b/packages/preact-query/src/useSuspenseQuery.ts
@@ -5,6 +5,15 @@ import { defaultThrowOnError } from './suspense'
 import type { UseSuspenseQueryOptions, UseSuspenseQueryResult } from './types'
 import { useBaseQuery } from './useBaseQuery'
 
+/**
+ * The options for `useSuspenseQuery` are the same as for `useQuery`, except for `throwOnError`, `enabled`, and
+ * `placeholderData`.
+ *
+ * @returns The same object as `useQuery`, except that `data` is guaranteed to be defined, `isPlaceholderData`
+ * is missing, and `status` is either `success` or `error` (with the derived flags set accordingly).
+ *
+ * Caveat: cancellation does not work.
+ */
 export function useSuspenseQuery<
   TQueryFnData = unknown,
   TError = DefaultError,

From 0d88230f2f39cce2bf306f6e06585b2cbeb89b0d Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Tue, 25 Aug 2026 00:49:34 +0900
Subject: [PATCH 02/28] docs(preact-query): replace concrete API calls with
 abstract fetcher names in JSDoc examples

---
 .../reference/functions/queryOptions.md       | 33 +++++++------------
 .../reference/functions/useInfiniteQuery.md   |  5 ++-
 .../preact/reference/functions/useMutation.md |  4 +--
 .../reference/functions/useMutationState.md   |  6 ++--
 .../preact/reference/functions/useQuery.md    |  7 ++--
 packages/preact-query/src/queryOptions.ts     | 27 +++++----------
 packages/preact-query/src/useInfiniteQuery.ts |  3 +-
 packages/preact-query/src/useMutation.ts      |  4 +--
 packages/preact-query/src/useMutationState.ts |  4 +--
 packages/preact-query/src/useQuery.ts         |  5 +--
 10 files changed, 34 insertions(+), 64 deletions(-)

diff --git a/docs/framework/preact/reference/functions/queryOptions.md b/docs/framework/preact/reference/functions/queryOptions.md
index 69a8990dc53..9e3fec62381 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:71](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L71)
+Defined in: [preact-query/src/queryOptions.ts:68](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L68)
 
 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
@@ -48,12 +48,9 @@ is the query key to generate options for.
 ```tsx
 import { queryOptions } from '@tanstack/preact-query'
 
-export const pokemonOptions = queryOptions({
-  queryKey: ['pokemon'],
-  queryFn: async () => {
-    const response = await fetch('https://pokeapi.co/api/v2/pokemon/25')
-    return response.json()
-  },
+export const postsOptions = queryOptions({
+  queryKey: ['posts'],
+  queryFn: fetchPosts,
 })
 ```
 
@@ -63,7 +60,7 @@ export const pokemonOptions = queryOptions({
 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:99](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L99)
+Defined in: [preact-query/src/queryOptions.ts:93](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L93)
 
 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
@@ -102,12 +99,9 @@ is the query key to generate options for.
 ```tsx
 import { queryOptions } from '@tanstack/preact-query'
 
-export const pokemonOptions = queryOptions({
-  queryKey: ['pokemon'],
-  queryFn: async () => {
-    const response = await fetch('https://pokeapi.co/api/v2/pokemon/25')
-    return response.json()
-  },
+export const postsOptions = queryOptions({
+  queryKey: ['posts'],
+  queryFn: fetchPosts,
 })
 ```
 
@@ -117,7 +111,7 @@ export const pokemonOptions = queryOptions({
 function queryOptions<TQueryFnData, TError, TData, TQueryKey>(options): UseQueryOptions<TQueryFnData, TError, TData, TQueryKey> & object & QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>;
 ```
 
-Defined in: [preact-query/src/queryOptions.ts:127](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L127)
+Defined in: [preact-query/src/queryOptions.ts:118](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L118)
 
 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,11 +150,8 @@ is the query key to generate options for.
 ```tsx
 import { queryOptions } from '@tanstack/preact-query'
 
-export const pokemonOptions = queryOptions({
-  queryKey: ['pokemon'],
-  queryFn: async () => {
-    const response = await fetch('https://pokeapi.co/api/v2/pokemon/25')
-    return response.json()
-  },
+export const postsOptions = queryOptions({
+  queryKey: ['posts'],
+  queryFn: fetchPosts,
 })
 ```
diff --git a/docs/framework/preact/reference/functions/useInfiniteQuery.md b/docs/framework/preact/reference/functions/useInfiniteQuery.md
index 34a19a8d2af..72b453cd104 100644
--- a/docs/framework/preact/reference/functions/useInfiniteQuery.md
+++ b/docs/framework/preact/reference/functions/useInfiniteQuery.md
@@ -109,7 +109,7 @@ be used.
 function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): UseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useInfiniteQuery.ts:110](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L110)
+Defined in: [preact-query/src/useInfiniteQuery.ts:109](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L109)
 
 The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
 `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
@@ -168,8 +168,7 @@ import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
 
 const projectsOptions = infiniteQueryOptions({
   queryKey: ['projects'],
-  queryFn: ({ pageParam }) =>
-    fetch(`/api/projects?cursor=${pageParam}`).then((r) => r.json()),
+  queryFn: ({ pageParam }) => fetchProjects(pageParam),
   initialPageParam: 0,
   getNextPageParam: (lastPage) => lastPage.nextId,
 })
diff --git a/docs/framework/preact/reference/functions/useMutation.md b/docs/framework/preact/reference/functions/useMutation.md
index 11167112aed..6f35fd3136b 100644
--- a/docs/framework/preact/reference/functions/useMutation.md
+++ b/docs/framework/preact/reference/functions/useMutation.md
@@ -49,11 +49,11 @@ be used.
 ```tsx
 import { useMutation, useQueryClient } from '@tanstack/preact-query'
 
-function Example() {
+function AddTodo() {
   const queryClient = useQueryClient()
 
   const addMutation = useMutation({
-    mutationFn: (add: string) => fetch(`/api/data?add=${add}`),
+    mutationFn: addTodo,
     onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
   })
 
diff --git a/docs/framework/preact/reference/functions/useMutationState.md b/docs/framework/preact/reference/functions/useMutationState.md
index 00018c26a98..6a514715ad2 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:125](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useMutationState.ts#L125)
+Defined in: [preact-query/src/useMutationState.ts:123](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useMutationState.ts#L123)
 
 `useMutationState` is a hook that gives you access to all mutations in the `MutationCache`. You can pass
 `filters` to it to narrow down your mutations, and `select` to transform the mutation state.
@@ -62,9 +62,7 @@ const mutationKey = ['posts']
 // Some mutation that we want to get the state for
 const mutation = useMutation({
   mutationKey,
-  mutationFn: (newPost) => {
-    return axios.post('/posts', newPost)
-  },
+  mutationFn: createPost,
 })
 
 const data = useMutationState({
diff --git a/docs/framework/preact/reference/functions/useQuery.md b/docs/framework/preact/reference/functions/useQuery.md
index 5b77b97b868..5c3769a24c7 100644
--- a/docs/framework/preact/reference/functions/useQuery.md
+++ b/docs/framework/preact/reference/functions/useQuery.md
@@ -95,7 +95,7 @@ be used.
 function useQuery<TQueryFnData, TError, TData, TQueryKey>(options, queryClient?): UseQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useQuery.ts:76](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L76)
+Defined in: [preact-query/src/useQuery.ts:73](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L73)
 
 ### Type Parameters
 
@@ -139,10 +139,7 @@ import { queryOptions, useQuery } from '@tanstack/preact-query'
 
 const postsOptions = queryOptions({
   queryKey: ['posts'],
-  queryFn: async () => {
-    const response = await fetch('https://jsonplaceholder.typicode.com/posts')
-    return await response.json()
-  },
+  queryFn: fetchPosts,
 })
 
 function Posts() {
diff --git a/packages/preact-query/src/queryOptions.ts b/packages/preact-query/src/queryOptions.ts
index 3883f9cf368..2041149a6f0 100644
--- a/packages/preact-query/src/queryOptions.ts
+++ b/packages/preact-query/src/queryOptions.ts
@@ -59,12 +59,9 @@ export type DefinedInitialDataOptions<
  * ```tsx
  * import { queryOptions } from '@tanstack/preact-query'
  *
- * export const pokemonOptions = queryOptions({
- *   queryKey: ['pokemon'],
- *   queryFn: async () => {
- *     const response = await fetch('https://pokeapi.co/api/v2/pokemon/25')
- *     return response.json()
- *   },
+ * export const postsOptions = queryOptions({
+ *   queryKey: ['posts'],
+ *   queryFn: fetchPosts,
  * })
  * ```
  */
@@ -87,12 +84,9 @@ export function queryOptions<
  * ```tsx
  * import { queryOptions } from '@tanstack/preact-query'
  *
- * export const pokemonOptions = queryOptions({
- *   queryKey: ['pokemon'],
- *   queryFn: async () => {
- *     const response = await fetch('https://pokeapi.co/api/v2/pokemon/25')
- *     return response.json()
- *   },
+ * export const postsOptions = queryOptions({
+ *   queryKey: ['posts'],
+ *   queryFn: fetchPosts,
  * })
  * ```
  */
@@ -115,12 +109,9 @@ export function queryOptions<
  * ```tsx
  * import { queryOptions } from '@tanstack/preact-query'
  *
- * export const pokemonOptions = queryOptions({
- *   queryKey: ['pokemon'],
- *   queryFn: async () => {
- *     const response = await fetch('https://pokeapi.co/api/v2/pokemon/25')
- *     return response.json()
- *   },
+ * export const postsOptions = queryOptions({
+ *   queryKey: ['posts'],
+ *   queryFn: fetchPosts,
  * })
  * ```
  */
diff --git a/packages/preact-query/src/useInfiniteQuery.ts b/packages/preact-query/src/useInfiniteQuery.ts
index 548f9acbe6b..edd125f518e 100644
--- a/packages/preact-query/src/useInfiniteQuery.ts
+++ b/packages/preact-query/src/useInfiniteQuery.ts
@@ -86,8 +86,7 @@ export function useInfiniteQuery<
  *
  * const projectsOptions = infiniteQueryOptions({
  *   queryKey: ['projects'],
- *   queryFn: ({ pageParam }) =>
- *     fetch(`/api/projects?cursor=${pageParam}`).then((r) => r.json()),
+ *   queryFn: ({ pageParam }) => fetchProjects(pageParam),
  *   initialPageParam: 0,
  *   getNextPageParam: (lastPage) => lastPage.nextId,
  * })
diff --git a/packages/preact-query/src/useMutation.ts b/packages/preact-query/src/useMutation.ts
index dafc8806143..50f209bac81 100644
--- a/packages/preact-query/src/useMutation.ts
+++ b/packages/preact-query/src/useMutation.ts
@@ -25,11 +25,11 @@ import { useSyncExternalStore } from './utils'
  * ```tsx
  * import { useMutation, useQueryClient } from '@tanstack/preact-query'
  *
- * function Example() {
+ * function AddTodo() {
  *   const queryClient = useQueryClient()
  *
  *   const addMutation = useMutation({
- *     mutationFn: (add: string) => fetch(`/api/data?add=${add}`),
+ *     mutationFn: addTodo,
  *     onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
  *   })
  *
diff --git a/packages/preact-query/src/useMutationState.ts b/packages/preact-query/src/useMutationState.ts
index 759174468ac..324afc049cc 100644
--- a/packages/preact-query/src/useMutationState.ts
+++ b/packages/preact-query/src/useMutationState.ts
@@ -110,9 +110,7 @@ function getResult<
  * // Some mutation that we want to get the state for
  * const mutation = useMutation({
  *   mutationKey,
- *   mutationFn: (newPost) => {
- *     return axios.post('/posts', newPost)
- *   },
+ *   mutationFn: createPost,
  * })
  *
  * const data = useMutationState({
diff --git a/packages/preact-query/src/useQuery.ts b/packages/preact-query/src/useQuery.ts
index 1877f068d58..593dbfbffd6 100644
--- a/packages/preact-query/src/useQuery.ts
+++ b/packages/preact-query/src/useQuery.ts
@@ -50,10 +50,7 @@ export function useQuery<
  *
  * const postsOptions = queryOptions({
  *   queryKey: ['posts'],
- *   queryFn: async () => {
- *     const response = await fetch('https://jsonplaceholder.typicode.com/posts')
- *     return await response.json()
- *   },
+ *   queryFn: fetchPosts,
  * })
  *
  * function Posts() {

From b0c38c49d97d37d87247d027586204e5f0ec4f36 Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Tue, 25 Aug 2026 00:51:03 +0900
Subject: [PATCH 03/28] docs(preact-query): rename mutation example fetcher to
 be CRUD-neutral

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

diff --git a/docs/framework/preact/reference/functions/useMutationState.md b/docs/framework/preact/reference/functions/useMutationState.md
index 6a514715ad2..04768b6ddaf 100644
--- a/docs/framework/preact/reference/functions/useMutationState.md
+++ b/docs/framework/preact/reference/functions/useMutationState.md
@@ -62,7 +62,7 @@ const mutationKey = ['posts']
 // Some mutation that we want to get the state for
 const mutation = useMutation({
   mutationKey,
-  mutationFn: createPost,
+  mutationFn: mutatePost,
 })
 
 const data = useMutationState({
diff --git a/packages/preact-query/src/useMutationState.ts b/packages/preact-query/src/useMutationState.ts
index 324afc049cc..08b31a4f4d3 100644
--- a/packages/preact-query/src/useMutationState.ts
+++ b/packages/preact-query/src/useMutationState.ts
@@ -110,7 +110,7 @@ function getResult<
  * // Some mutation that we want to get the state for
  * const mutation = useMutation({
  *   mutationKey,
- *   mutationFn: createPost,
+ *   mutationFn: mutatePost,
  * })
  *
  * const data = useMutationState({

From 2f097caa39a28a83ad0f0728fca77dbd9ed1b07d Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Tue, 25 Aug 2026 00:51:50 +0900
Subject: [PATCH 04/28] docs(preact-query): rename mutation example fetcher to
 'createPosts'

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

diff --git a/docs/framework/preact/reference/functions/useMutationState.md b/docs/framework/preact/reference/functions/useMutationState.md
index 04768b6ddaf..56ad8e157db 100644
--- a/docs/framework/preact/reference/functions/useMutationState.md
+++ b/docs/framework/preact/reference/functions/useMutationState.md
@@ -62,7 +62,7 @@ const mutationKey = ['posts']
 // Some mutation that we want to get the state for
 const mutation = useMutation({
   mutationKey,
-  mutationFn: mutatePost,
+  mutationFn: createPosts,
 })
 
 const data = useMutationState({
diff --git a/packages/preact-query/src/useMutationState.ts b/packages/preact-query/src/useMutationState.ts
index 08b31a4f4d3..0c0f0dafd8d 100644
--- a/packages/preact-query/src/useMutationState.ts
+++ b/packages/preact-query/src/useMutationState.ts
@@ -110,7 +110,7 @@ function getResult<
  * // Some mutation that we want to get the state for
  * const mutation = useMutation({
  *   mutationKey,
- *   mutationFn: mutatePost,
+ *   mutationFn: createPosts,
  * })
  *
  * const data = useMutationState({

From f90b7cd36a460455f22e99bff82687fd7a27d27f Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Tue, 25 Aug 2026 00:55:37 +0900
Subject: [PATCH 05/28] docs(preact-query): add examples for Suspense,
 prefetch, and options-builder functions

---
 .../functions/infiniteQueryOptions.md         | 45 +++++++++++-
 .../reference/functions/mutationOptions.md    | 36 +++++++++-
 .../functions/usePrefetchInfiniteQuery.md     | 25 ++++++-
 .../reference/functions/usePrefetchQuery.md   | 23 +++++-
 .../functions/useSuspenseInfiniteQuery.md     | 38 +++++++++-
 .../reference/functions/useSuspenseQueries.md | 70 ++++++++++++++++++-
 .../reference/functions/useSuspenseQuery.md   | 34 ++++++++-
 .../preact-query/src/infiniteQueryOptions.ts  | 36 ++++++++++
 packages/preact-query/src/mutationOptions.ts  | 30 ++++++++
 .../src/usePrefetchInfiniteQuery.tsx          | 22 ++++++
 .../preact-query/src/usePrefetchQuery.tsx     | 20 ++++++
 .../src/useSuspenseInfiniteQuery.ts           | 35 ++++++++++
 .../preact-query/src/useSuspenseQueries.ts    | 64 +++++++++++++++++
 packages/preact-query/src/useSuspenseQuery.ts | 31 ++++++++
 14 files changed, 498 insertions(+), 11 deletions(-)

diff --git a/docs/framework/preact/reference/functions/infiniteQueryOptions.md b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
index b454d91a9ba..0ac072d98c6 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:81](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L81)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:93](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L93)
 
 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`.
@@ -47,13 +47,26 @@ These options can be shared across hooks and imperative APIs such as `queryClien
 
 [`UseInfiniteQueryOptions`](../interfaces/UseInfiniteQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & `object` & `QueryKeyWithDataTag`\<`TQueryKey`, `InfiniteData`\<`TQueryFnData`, `unknown`\>, `TError`\>
 
+### Example
+
+```tsx
+import { infiniteQueryOptions } from '@tanstack/preact-query'
+
+export const projectsOptions = infiniteQueryOptions({
+  queryKey: ['projects'],
+  queryFn: ({ pageParam }) => fetchProjects(pageParam),
+  initialPageParam: 0,
+  getNextPageParam: (lastPage) => lastPage.nextId,
+})
+```
+
 ## 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:109](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L109)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:133](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L133)
 
 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`.
@@ -91,13 +104,26 @@ These options can be shared across hooks and imperative APIs such as `queryClien
 
 `OmitKeyof`\<[`UseInfiniteQueryOptions`](../interfaces/UseInfiniteQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\>, `"queryFn"`\> & `object` & `QueryKeyWithDataTag`\<`TQueryKey`, `InfiniteData`\<`TQueryFnData`, `unknown`\>, `TError`\>
 
+### Example
+
+```tsx
+import { infiniteQueryOptions } from '@tanstack/preact-query'
+
+export const projectsOptions = infiniteQueryOptions({
+  queryKey: ['projects'],
+  queryFn: ({ pageParam }) => fetchProjects(pageParam),
+  initialPageParam: 0,
+  getNextPageParam: (lastPage) => lastPage.nextId,
+})
+```
+
 ## Call Signature
 
 ```ts
 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:137](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L137)
+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`.
@@ -134,3 +160,16 @@ These options can be shared across hooks and imperative APIs such as `queryClien
 ### Returns
 
 [`UseInfiniteQueryOptions`](../interfaces/UseInfiniteQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & `object` & `QueryKeyWithDataTag`\<`TQueryKey`, `InfiniteData`\<`TQueryFnData`, `unknown`\>, `TError`\>
+
+### Example
+
+```tsx
+import { infiniteQueryOptions } from '@tanstack/preact-query'
+
+export const projectsOptions = infiniteQueryOptions({
+  queryKey: ['projects'],
+  queryFn: ({ pageParam }) => fetchProjects(pageParam),
+  initialPageParam: 0,
+  getNextPageParam: (lastPage) => lastPage.nextId,
+})
+```
diff --git a/docs/framework/preact/reference/functions/mutationOptions.md b/docs/framework/preact/reference/functions/mutationOptions.md
index 5d3a146ed25..cdc67e6eadd 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:8](https://github.com/TanStack/query/blob/main/packages/preact-query/src/mutationOptions.ts#L8)
+Defined in: [preact-query/src/mutationOptions.ts:23](https://github.com/TanStack/query/blob/main/packages/preact-query/src/mutationOptions.ts#L23)
 
 You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`.
 
@@ -41,13 +41,29 @@ You can generally pass everything to `mutationOptions` that you can also pass to
 
 `WithRequired`\<[`UseMutationOptions`](../interfaces/UseMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\>
 
+### 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>
+}
+```
+
 ## Call Signature
 
 ```ts
 function mutationOptions<TData, TError, TVariables, TOnMutateResult>(options): Omit<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">;
 ```
 
-Defined in: [preact-query/src/mutationOptions.ts:25](https://github.com/TanStack/query/blob/main/packages/preact-query/src/mutationOptions.ts#L25)
+Defined in: [preact-query/src/mutationOptions.ts:55](https://github.com/TanStack/query/blob/main/packages/preact-query/src/mutationOptions.ts#L55)
 
 You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`.
 
@@ -78,3 +94,19 @@ You can generally pass everything to `mutationOptions` that you can also pass to
 ### Returns
 
 `Omit`\<[`UseMutationOptions`](../interfaces/UseMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\>
+
+### 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>
+}
+```
diff --git a/docs/framework/preact/reference/functions/usePrefetchInfiniteQuery.md b/docs/framework/preact/reference/functions/usePrefetchInfiniteQuery.md
index 6015b04667e..6eed4cddc2d 100644
--- a/docs/framework/preact/reference/functions/usePrefetchInfiniteQuery.md
+++ b/docs/framework/preact/reference/functions/usePrefetchInfiniteQuery.md
@@ -7,7 +7,7 @@ title: usePrefetchInfiniteQuery
 function usePrefetchInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): void;
 ```
 
-Defined in: [preact-query/src/usePrefetchInfiniteQuery.tsx:19](https://github.com/TanStack/query/blob/main/packages/preact-query/src/usePrefetchInfiniteQuery.tsx#L19)
+Defined in: [preact-query/src/usePrefetchInfiniteQuery.tsx:41](https://github.com/TanStack/query/blob/main/packages/preact-query/src/usePrefetchInfiniteQuery.tsx#L41)
 
 `usePrefetchInfiniteQuery` does not return anything, it should be used just to fire a prefetch during render,
 before a suspense boundary that wraps a component that uses `useSuspenseInfiniteQuery`. You can pass
@@ -55,3 +55,26 @@ available.
 ## Returns
 
 `void`
+
+## Example
+
+```tsx
+import { Suspense } from 'preact/compat'
+import { usePrefetchInfiniteQuery } from '@tanstack/preact-query'
+
+function App() {
+  // Fire the prefetch during render, before the suspense boundary below.
+  usePrefetchInfiniteQuery({
+    queryKey: ['projects'],
+    queryFn: ({ pageParam }) => fetchProjects(pageParam),
+    initialPageParam: 0,
+    getNextPageParam: (lastPage) => lastPage.nextId,
+  })
+
+  return (
+    <Suspense fallback={<h1>Loading projects...</h1>}>
+      <Projects />
+    </Suspense>
+  )
+}
+```
diff --git a/docs/framework/preact/reference/functions/usePrefetchQuery.md b/docs/framework/preact/reference/functions/usePrefetchQuery.md
index c6a0c767115..a2594d6ce4f 100644
--- a/docs/framework/preact/reference/functions/usePrefetchQuery.md
+++ b/docs/framework/preact/reference/functions/usePrefetchQuery.md
@@ -7,7 +7,7 @@ title: usePrefetchQuery
 function usePrefetchQuery<TQueryFnData, TError, TData, TQueryData, TQueryKey>(options, queryClient?): void;
 ```
 
-Defined in: [preact-query/src/usePrefetchQuery.tsx:13](https://github.com/TanStack/query/blob/main/packages/preact-query/src/usePrefetchQuery.tsx#L13)
+Defined in: [preact-query/src/usePrefetchQuery.tsx:33](https://github.com/TanStack/query/blob/main/packages/preact-query/src/usePrefetchQuery.tsx#L33)
 
 `usePrefetchQuery` does not return anything, it should be used just to fire a prefetch during render, before
 a suspense boundary that wraps a component that uses `useSuspenseQuery`. You can pass everything to
@@ -49,3 +49,24 @@ a suspense boundary that wraps a component that uses `useSuspenseQuery`. You can
 ## Returns
 
 `void`
+
+## Example
+
+```tsx
+import { Suspense } from 'preact/compat'
+import { usePrefetchQuery } from '@tanstack/preact-query'
+
+function App() {
+  // Fire the prefetch during render, before the suspense boundary below.
+  usePrefetchQuery({
+    queryKey: ['posts'],
+    queryFn: fetchPosts,
+  })
+
+  return (
+    <Suspense fallback={<h1>Loading posts...</h1>}>
+      <Posts />
+    </Suspense>
+  )
+}
+```
diff --git a/docs/framework/preact/reference/functions/useSuspenseInfiniteQuery.md b/docs/framework/preact/reference/functions/useSuspenseInfiniteQuery.md
index 7e7f3d5bfa6..551dd4035ee 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:28](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseInfiniteQuery.ts#L28)
+Defined in: [preact-query/src/useSuspenseInfiniteQuery.ts:63](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseInfiniteQuery.ts#L63)
 
 The options for `useSuspenseInfiniteQuery` are the same as for `useInfiniteQuery`, except for `throwOnError`,
 `enabled`, and `placeholderData`.
@@ -53,3 +53,39 @@ The same object as `useInfiniteQuery`, except that `data` is guaranteed to be de
 accordingly).
 
 Caveat: cancellation does not work.
+
+## Example
+
+```tsx
+import { Suspense } from 'preact/compat'
+import { useSuspenseInfiniteQuery } from '@tanstack/preact-query'
+
+function Projects() {
+  // `data` is guaranteed to be defined here — no `isPending` check needed.
+  const { data, fetchNextPage, hasNextPage } = useSuspenseInfiniteQuery({
+    queryKey: ['projects'],
+    queryFn: ({ pageParam }) => fetchProjects(pageParam),
+    initialPageParam: 0,
+    getNextPageParam: (lastPage) => lastPage.nextId,
+  })
+
+  return (
+    <div>
+      {data.pages.map((page) =>
+        page.projects.map((project) => <p key={project.id}>{project.name}</p>),
+      )}
+      <button onClick={() => fetchNextPage()} disabled={!hasNextPage}>
+        Load More
+      </button>
+    </div>
+  )
+}
+
+function App() {
+  return (
+    <Suspense fallback={<h1>Loading projects...</h1>}>
+      <Projects />
+    </Suspense>
+  )
+}
+```
diff --git a/docs/framework/preact/reference/functions/useSuspenseQueries.md b/docs/framework/preact/reference/functions/useSuspenseQueries.md
index 108937eb6fb..4855f0e4fb7 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:177](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseQueries.ts#L177)
+Defined in: [preact-query/src/useSuspenseQueries.ts:209](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseQueries.ts#L209)
 
 The options for `useSuspenseQueries` are the same as for `useQueries`, except that each `query` can't have
 `throwOnError`, `enabled`, or `placeholderData`.
@@ -53,13 +53,46 @@ Caveat: the component will only re-mount after all queries have finished loading
 stale in the time it took for all the queries to complete, it will be fetched again at re-mount. To avoid
 this, make sure to set a high enough `staleTime`. Cancellation does not work.
 
+### Example
+
+```tsx
+import { Suspense } from 'preact/compat'
+import { useSuspenseQueries } from '@tanstack/preact-query'
+
+function Posts({ ids }: { ids: Array<number> }) {
+  // Every result is guaranteed to be defined — no per-query `isPending` check needed.
+  const results = useSuspenseQueries({
+    queries: ids.map((id) => ({
+      queryKey: ['post', id],
+      queryFn: () => fetchPost(id),
+    })),
+  })
+
+  return (
+    <ul>
+      {results.map((result) => (
+        <li key={result.data.id}>{result.data.title}</li>
+      ))}
+    </ul>
+  )
+}
+
+function App() {
+  return (
+    <Suspense fallback={<h1>Loading posts...</h1>}>
+      <Posts ids={[1, 2, 3]} />
+    </Suspense>
+  )
+}
+```
+
 ## Call Signature
 
 ```ts
 function useSuspenseQueries<T, TCombinedResult>(options, queryClient?): TCombinedResult;
 ```
 
-Defined in: [preact-query/src/useSuspenseQueries.ts:202](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseQueries.ts#L202)
+Defined in: [preact-query/src/useSuspenseQueries.ts:266](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseQueries.ts#L266)
 
 The options for `useSuspenseQueries` are the same as for `useQueries`, except that each `query` can't have
 `throwOnError`, `enabled`, or `placeholderData`.
@@ -101,3 +134,36 @@ flags set accordingly).
 Caveat: the component will only re-mount after all queries have finished loading. Hence, if a query has gone
 stale in the time it took for all the queries to complete, it will be fetched again at re-mount. To avoid
 this, make sure to set a high enough `staleTime`. Cancellation does not work.
+
+### Example
+
+```tsx
+import { Suspense } from 'preact/compat'
+import { useSuspenseQueries } from '@tanstack/preact-query'
+
+function Posts({ ids }: { ids: Array<number> }) {
+  // Every result is guaranteed to be defined — no per-query `isPending` check needed.
+  const results = useSuspenseQueries({
+    queries: ids.map((id) => ({
+      queryKey: ['post', id],
+      queryFn: () => fetchPost(id),
+    })),
+  })
+
+  return (
+    <ul>
+      {results.map((result) => (
+        <li key={result.data.id}>{result.data.title}</li>
+      ))}
+    </ul>
+  )
+}
+
+function App() {
+  return (
+    <Suspense fallback={<h1>Loading posts...</h1>}>
+      <Posts ids={[1, 2, 3]} />
+    </Suspense>
+  )
+}
+```
diff --git a/docs/framework/preact/reference/functions/useSuspenseQuery.md b/docs/framework/preact/reference/functions/useSuspenseQuery.md
index b6dec950a43..b03d00231d6 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:17](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseQuery.ts#L17)
+Defined in: [preact-query/src/useSuspenseQuery.ts:48](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseQuery.ts#L48)
 
 The options for `useSuspenseQuery` are the same as for `useQuery`, except for `throwOnError`, `enabled`, and
 `placeholderData`.
@@ -48,3 +48,35 @@ The same object as `useQuery`, except that `data` is guaranteed to be defined, `
 is missing, and `status` is either `success` or `error` (with the derived flags set accordingly).
 
 Caveat: cancellation does not work.
+
+## Example
+
+```tsx
+import { Suspense } from 'preact/compat'
+import { useSuspenseQuery } from '@tanstack/preact-query'
+
+function Projects() {
+  // `data` is guaranteed to be defined here — no `isPending` check needed.
+  const { data, isFetching } = useSuspenseQuery({
+    queryKey: ['projects'],
+    queryFn: fetchProjects,
+  })
+
+  return (
+    <div>
+      <h1>Projects {isFetching ? <Spinner /> : null}</h1>
+      {data.map((project) => (
+        <p key={project.id}>{project.name}</p>
+      ))}
+    </div>
+  )
+}
+
+function App() {
+  return (
+    <Suspense fallback={<h1>Loading projects...</h1>}>
+      <Projects />
+    </Suspense>
+  )
+}
+```
diff --git a/packages/preact-query/src/infiniteQueryOptions.ts b/packages/preact-query/src/infiniteQueryOptions.ts
index 22d4f7068f6..3e26e75a512 100644
--- a/packages/preact-query/src/infiniteQueryOptions.ts
+++ b/packages/preact-query/src/infiniteQueryOptions.ts
@@ -77,6 +77,18 @@ export type DefinedInitialDataInfiniteOptions<
  * 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`.
  * `options.queryKey` is required and is the query key to generate options for.
+ *
+ * @example
+ * ```tsx
+ * import { infiniteQueryOptions } from '@tanstack/preact-query'
+ *
+ * export const projectsOptions = infiniteQueryOptions({
+ *   queryKey: ['projects'],
+ *   queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *   initialPageParam: 0,
+ *   getNextPageParam: (lastPage) => lastPage.nextId,
+ * })
+ * ```
  */
 export function infiniteQueryOptions<
   TQueryFnData,
@@ -105,6 +117,18 @@ export function infiniteQueryOptions<
  * 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`.
  * `options.queryKey` is required and is the query key to generate options for.
+ *
+ * @example
+ * ```tsx
+ * import { infiniteQueryOptions } from '@tanstack/preact-query'
+ *
+ * export const projectsOptions = infiniteQueryOptions({
+ *   queryKey: ['projects'],
+ *   queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *   initialPageParam: 0,
+ *   getNextPageParam: (lastPage) => lastPage.nextId,
+ * })
+ * ```
  */
 export function infiniteQueryOptions<
   TQueryFnData,
@@ -133,6 +157,18 @@ export function infiniteQueryOptions<
  * 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`.
  * `options.queryKey` is required and is the query key to generate options for.
+ *
+ * @example
+ * ```tsx
+ * import { infiniteQueryOptions } from '@tanstack/preact-query'
+ *
+ * export const projectsOptions = infiniteQueryOptions({
+ *   queryKey: ['projects'],
+ *   queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *   initialPageParam: 0,
+ *   getNextPageParam: (lastPage) => lastPage.nextId,
+ * })
+ * ```
  */
 export function infiniteQueryOptions<
   TQueryFnData,
diff --git a/packages/preact-query/src/mutationOptions.ts b/packages/preact-query/src/mutationOptions.ts
index 67556b7a79b..09940b9b369 100644
--- a/packages/preact-query/src/mutationOptions.ts
+++ b/packages/preact-query/src/mutationOptions.ts
@@ -4,6 +4,21 @@ import type { UseMutationOptions } from './types'
 
 /**
  * You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`.
+ *
+ * @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>
+ * }
+ * ```
  */
 export function mutationOptions<
   TData = unknown,
@@ -21,6 +36,21 @@ export function mutationOptions<
 >
 /**
  * You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`.
+ *
+ * @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>
+ * }
+ * ```
  */
 export function mutationOptions<
   TData = unknown,
diff --git a/packages/preact-query/src/usePrefetchInfiniteQuery.tsx b/packages/preact-query/src/usePrefetchInfiniteQuery.tsx
index 9526b2ef9e4..f00ffdc2683 100644
--- a/packages/preact-query/src/usePrefetchInfiniteQuery.tsx
+++ b/packages/preact-query/src/usePrefetchInfiniteQuery.tsx
@@ -15,6 +15,28 @@ import type { UsePrefetchInfiniteQueryOptions } from './types'
  * as well as pageParam information, and should return a single variable that will be passed as the last
  * optional parameter to your query function. Return `undefined` or `null` to indicate there is no next page
  * available.
+ *
+ * @example
+ * ```tsx
+ * import { Suspense } from 'preact/compat'
+ * import { usePrefetchInfiniteQuery } from '@tanstack/preact-query'
+ *
+ * function App() {
+ *   // Fire the prefetch during render, before the suspense boundary below.
+ *   usePrefetchInfiniteQuery({
+ *     queryKey: ['projects'],
+ *     queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *     initialPageParam: 0,
+ *     getNextPageParam: (lastPage) => lastPage.nextId,
+ *   })
+ *
+ *   return (
+ *     <Suspense fallback={<h1>Loading projects...</h1>}>
+ *       <Projects />
+ *     </Suspense>
+ *   )
+ * }
+ * ```
  */
 export function usePrefetchInfiniteQuery<
   TQueryFnData = unknown,
diff --git a/packages/preact-query/src/usePrefetchQuery.tsx b/packages/preact-query/src/usePrefetchQuery.tsx
index 08cb1f69be9..8dba5e851f8 100644
--- a/packages/preact-query/src/usePrefetchQuery.tsx
+++ b/packages/preact-query/src/usePrefetchQuery.tsx
@@ -9,6 +9,26 @@ import type { UsePrefetchQueryOptions } from './types'
  * a suspense boundary that wraps a component that uses `useSuspenseQuery`. You can pass everything to
  * `usePrefetchQuery` that you can pass to `queryClient.fetchQuery`, though `queryKey` is always required, and
  * `queryFn` is required unless a default query function has been defined.
+ *
+ * @example
+ * ```tsx
+ * import { Suspense } from 'preact/compat'
+ * import { usePrefetchQuery } from '@tanstack/preact-query'
+ *
+ * function App() {
+ *   // Fire the prefetch during render, before the suspense boundary below.
+ *   usePrefetchQuery({
+ *     queryKey: ['posts'],
+ *     queryFn: fetchPosts,
+ *   })
+ *
+ *   return (
+ *     <Suspense fallback={<h1>Loading posts...</h1>}>
+ *       <Posts />
+ *     </Suspense>
+ *   )
+ * }
+ * ```
  */
 export function usePrefetchQuery<
   TQueryFnData = unknown,
diff --git a/packages/preact-query/src/useSuspenseInfiniteQuery.ts b/packages/preact-query/src/useSuspenseInfiniteQuery.ts
index 6aac2746af2..f7e683741f3 100644
--- a/packages/preact-query/src/useSuspenseInfiniteQuery.ts
+++ b/packages/preact-query/src/useSuspenseInfiniteQuery.ts
@@ -24,6 +24,41 @@ import { useBaseQuery } from './useBaseQuery'
  * accordingly).
  *
  * Caveat: cancellation does not work.
+ *
+ * @example
+ * ```tsx
+ * import { Suspense } from 'preact/compat'
+ * import { useSuspenseInfiniteQuery } from '@tanstack/preact-query'
+ *
+ * function Projects() {
+ *   // `data` is guaranteed to be defined here — no `isPending` check needed.
+ *   const { data, fetchNextPage, hasNextPage } = useSuspenseInfiniteQuery({
+ *     queryKey: ['projects'],
+ *     queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *     initialPageParam: 0,
+ *     getNextPageParam: (lastPage) => lastPage.nextId,
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       {data.pages.map((page) =>
+ *         page.projects.map((project) => <p key={project.id}>{project.name}</p>),
+ *       )}
+ *       <button onClick={() => fetchNextPage()} disabled={!hasNextPage}>
+ *         Load More
+ *       </button>
+ *     </div>
+ *   )
+ * }
+ *
+ * function App() {
+ *   return (
+ *     <Suspense fallback={<h1>Loading projects...</h1>}>
+ *       <Projects />
+ *     </Suspense>
+ *   )
+ * }
+ * ```
  */
 export function useSuspenseInfiniteQuery<
   TQueryFnData,
diff --git a/packages/preact-query/src/useSuspenseQueries.ts b/packages/preact-query/src/useSuspenseQueries.ts
index 22c54583149..32b65453e3c 100644
--- a/packages/preact-query/src/useSuspenseQueries.ts
+++ b/packages/preact-query/src/useSuspenseQueries.ts
@@ -173,6 +173,38 @@ export type SuspenseQueriesResults<
  * Caveat: the component will only re-mount after all queries have finished loading. Hence, if a query has gone
  * stale in the time it took for all the queries to complete, it will be fetched again at re-mount. To avoid
  * this, make sure to set a high enough `staleTime`. Cancellation does not work.
+ *
+ * @example
+ * ```tsx
+ * import { Suspense } from 'preact/compat'
+ * import { useSuspenseQueries } from '@tanstack/preact-query'
+ *
+ * function Posts({ ids }: { ids: Array<number> }) {
+ *   // Every result is guaranteed to be defined — no per-query `isPending` check needed.
+ *   const results = useSuspenseQueries({
+ *     queries: ids.map((id) => ({
+ *       queryKey: ['post', id],
+ *       queryFn: () => fetchPost(id),
+ *     })),
+ *   })
+ *
+ *   return (
+ *     <ul>
+ *       {results.map((result) => (
+ *         <li key={result.data.id}>{result.data.title}</li>
+ *       ))}
+ *     </ul>
+ *   )
+ * }
+ *
+ * function App() {
+ *   return (
+ *     <Suspense fallback={<h1>Loading posts...</h1>}>
+ *       <Posts ids={[1, 2, 3]} />
+ *     </Suspense>
+ *   )
+ * }
+ * ```
  */
 export function useSuspenseQueries<
   T extends Array<any>,
@@ -198,6 +230,38 @@ export function useSuspenseQueries<
  * Caveat: the component will only re-mount after all queries have finished loading. Hence, if a query has gone
  * stale in the time it took for all the queries to complete, it will be fetched again at re-mount. To avoid
  * this, make sure to set a high enough `staleTime`. Cancellation does not work.
+ *
+ * @example
+ * ```tsx
+ * import { Suspense } from 'preact/compat'
+ * import { useSuspenseQueries } from '@tanstack/preact-query'
+ *
+ * function Posts({ ids }: { ids: Array<number> }) {
+ *   // Every result is guaranteed to be defined — no per-query `isPending` check needed.
+ *   const results = useSuspenseQueries({
+ *     queries: ids.map((id) => ({
+ *       queryKey: ['post', id],
+ *       queryFn: () => fetchPost(id),
+ *     })),
+ *   })
+ *
+ *   return (
+ *     <ul>
+ *       {results.map((result) => (
+ *         <li key={result.data.id}>{result.data.title}</li>
+ *       ))}
+ *     </ul>
+ *   )
+ * }
+ *
+ * function App() {
+ *   return (
+ *     <Suspense fallback={<h1>Loading posts...</h1>}>
+ *       <Posts ids={[1, 2, 3]} />
+ *     </Suspense>
+ *   )
+ * }
+ * ```
  */
 export function useSuspenseQueries<
   T extends Array<any>,
diff --git a/packages/preact-query/src/useSuspenseQuery.ts b/packages/preact-query/src/useSuspenseQuery.ts
index 0b9879a40f9..1c393f9affb 100644
--- a/packages/preact-query/src/useSuspenseQuery.ts
+++ b/packages/preact-query/src/useSuspenseQuery.ts
@@ -13,6 +13,37 @@ import { useBaseQuery } from './useBaseQuery'
  * is missing, and `status` is either `success` or `error` (with the derived flags set accordingly).
  *
  * Caveat: cancellation does not work.
+ *
+ * @example
+ * ```tsx
+ * import { Suspense } from 'preact/compat'
+ * import { useSuspenseQuery } from '@tanstack/preact-query'
+ *
+ * function Projects() {
+ *   // `data` is guaranteed to be defined here — no `isPending` check needed.
+ *   const { data, isFetching } = useSuspenseQuery({
+ *     queryKey: ['projects'],
+ *     queryFn: fetchProjects,
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <h1>Projects {isFetching ? <Spinner /> : null}</h1>
+ *       {data.map((project) => (
+ *         <p key={project.id}>{project.name}</p>
+ *       ))}
+ *     </div>
+ *   )
+ * }
+ *
+ * function App() {
+ *   return (
+ *     <Suspense fallback={<h1>Loading projects...</h1>}>
+ *       <Projects />
+ *     </Suspense>
+ *   )
+ * }
+ * ```
  */
 export function useSuspenseQuery<
   TQueryFnData = unknown,

From 3cd37f245f2a8b86ac6be6870642ece8f52f3327 Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Tue, 25 Aug 2026 00:58:37 +0900
Subject: [PATCH 06/28] docs(preact-query): add optimistic update, dependent
 query, and SSR hydration examples

---
 .../reference/functions/HydrationBoundary.md  | 24 +++++++++++--
 .../preact/reference/functions/useMutation.md | 36 +++++++++++++++++--
 .../preact/reference/functions/useQuery.md    | 19 ++++++++--
 .../preact-query/src/HydrationBoundary.tsx    | 21 +++++++++++
 packages/preact-query/src/useMutation.ts      | 33 +++++++++++++++++
 packages/preact-query/src/useQuery.ts         | 16 +++++++++
 6 files changed, 143 insertions(+), 6 deletions(-)

diff --git a/docs/framework/preact/reference/functions/HydrationBoundary.md b/docs/framework/preact/reference/functions/HydrationBoundary.md
index afcbdba0045..460c2b55748 100644
--- a/docs/framework/preact/reference/functions/HydrationBoundary.md
+++ b/docs/framework/preact/reference/functions/HydrationBoundary.md
@@ -7,7 +7,7 @@ title: HydrationBoundary
 function HydrationBoundary(__namedParameters): Element;
 ```
 
-Defined in: [preact-query/src/HydrationBoundary.tsx:51](https://github.com/TanStack/query/blob/main/packages/preact-query/src/HydrationBoundary.tsx#L51)
+Defined in: [preact-query/src/HydrationBoundary.tsx:72](https://github.com/TanStack/query/blob/main/packages/preact-query/src/HydrationBoundary.tsx#L72)
 
 `HydrationBoundary` adds a previously dehydrated state into the `queryClient` that would be returned by
 `useQueryClient()`. If the client already contains data, the new queries will be intelligently merged based on
@@ -25,7 +25,7 @@ Note: Only `queries` can be dehydrated with an `HydrationBoundary`.
 
 `Element`
 
-## Example
+## Examples
 
 ```tsx
 import { HydrationBoundary } from '@tanstack/preact-query'
@@ -34,3 +34,23 @@ function App() {
   return <HydrationBoundary state={dehydratedState}>...</HydrationBoundary>
 }
 ```
+
+Server-side prefetch handed off to the client via `dehydrate`:
+```tsx
+import { HydrationBoundary, dehydrate } from '@tanstack/preact-query'
+
+async function ServerComponent() {
+  const queryClient = getQueryClient()
+
+  await queryClient.prefetchQuery({
+    queryKey: ['posts'],
+    queryFn: fetchPosts,
+  })
+
+  return (
+    <HydrationBoundary state={dehydrate(queryClient)}>
+      <Posts />
+    </HydrationBoundary>
+  )
+}
+```
diff --git a/docs/framework/preact/reference/functions/useMutation.md b/docs/framework/preact/reference/functions/useMutation.md
index 6f35fd3136b..f5d86983c35 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:42](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useMutation.ts#L42)
+Defined in: [preact-query/src/useMutation.ts:75](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useMutation.ts#L75)
 
 ## Type Parameters
 
@@ -44,7 +44,7 @@ be used.
 
 [`UseMutationResult`](../type-aliases/UseMutationResult.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>
 
-## Example
+## Examples
 
 ```tsx
 import { useMutation, useQueryClient } from '@tanstack/preact-query'
@@ -62,3 +62,35 @@ function AddTodo() {
   )
 }
 ```
+
+Optimistic update via `onMutate`, rolling back on `onError`:
+```tsx
+import { useMutation, useQueryClient } from '@tanstack/preact-query'
+
+function AddTodo() {
+  const queryClient = useQueryClient()
+
+  const addMutation = useMutation({
+    mutationFn: addTodo,
+    onMutate: async (newTodo) => {
+      await queryClient.cancelQueries({ queryKey: ['todos'] })
+      const previousTodos = queryClient.getQueryData(['todos'])
+
+      queryClient.setQueryData(['todos'], (old) => [...old, newTodo])
+
+      // Passed to `onError` as `context` if the mutation fails.
+      return { previousTodos }
+    },
+    onError: (_err, _newTodo, context) => {
+      queryClient.setQueryData(['todos'], context.previousTodos)
+    },
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: ['todos'] })
+    },
+  })
+
+  return (
+    <button onClick={() => addMutation.mutate('Item')}>Add</button>
+  )
+}
+```
diff --git a/docs/framework/preact/reference/functions/useQuery.md b/docs/framework/preact/reference/functions/useQuery.md
index 5c3769a24c7..0ae8fbca55e 100644
--- a/docs/framework/preact/reference/functions/useQuery.md
+++ b/docs/framework/preact/reference/functions/useQuery.md
@@ -95,7 +95,7 @@ be used.
 function useQuery<TQueryFnData, TError, TData, TQueryKey>(options, queryClient?): UseQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useQuery.ts:73](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L73)
+Defined in: [preact-query/src/useQuery.ts:89](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L89)
 
 ### Type Parameters
 
@@ -132,7 +132,7 @@ be used.
 
 [`UseQueryResult`](../type-aliases/UseQueryResult.md)\<`TData`, `TError`\>
 
-### Example
+### Examples
 
 ```tsx
 import { queryOptions, useQuery } from '@tanstack/preact-query'
@@ -158,3 +158,18 @@ function Posts() {
   )
 }
 ```
+
+A dependent query, only enabled once `postId` is set:
+```tsx
+import { useQuery } from '@tanstack/preact-query'
+
+function Post({ postId }: { postId: number }) {
+  const { data } = useQuery({
+    queryKey: ['post', postId],
+    queryFn: () => fetchPost(postId),
+    enabled: !!postId,
+  })
+
+  return <h1>{data?.title}</h1>
+}
+```
diff --git a/packages/preact-query/src/HydrationBoundary.tsx b/packages/preact-query/src/HydrationBoundary.tsx
index 079782356e8..e5b5dcfaed7 100644
--- a/packages/preact-query/src/HydrationBoundary.tsx
+++ b/packages/preact-query/src/HydrationBoundary.tsx
@@ -47,6 +47,27 @@ export interface HydrationBoundaryProps {
  *   return <HydrationBoundary state={dehydratedState}>...</HydrationBoundary>
  * }
  * ```
+ *
+ * @example
+ * Server-side prefetch handed off to the client via `dehydrate`:
+ * ```tsx
+ * import { HydrationBoundary, dehydrate } from '@tanstack/preact-query'
+ *
+ * async function ServerComponent() {
+ *   const queryClient = getQueryClient()
+ *
+ *   await queryClient.prefetchQuery({
+ *     queryKey: ['posts'],
+ *     queryFn: fetchPosts,
+ *   })
+ *
+ *   return (
+ *     <HydrationBoundary state={dehydrate(queryClient)}>
+ *       <Posts />
+ *     </HydrationBoundary>
+ *   )
+ * }
+ * ```
  */
 export const HydrationBoundary = ({
   children,
diff --git a/packages/preact-query/src/useMutation.ts b/packages/preact-query/src/useMutation.ts
index 50f209bac81..a21454f55d2 100644
--- a/packages/preact-query/src/useMutation.ts
+++ b/packages/preact-query/src/useMutation.ts
@@ -38,6 +38,39 @@ import { useSyncExternalStore } from './utils'
  *   )
  * }
  * ```
+ *
+ * @example
+ * Optimistic update via `onMutate`, rolling back on `onError`:
+ * ```tsx
+ * import { useMutation, useQueryClient } from '@tanstack/preact-query'
+ *
+ * function AddTodo() {
+ *   const queryClient = useQueryClient()
+ *
+ *   const addMutation = useMutation({
+ *     mutationFn: addTodo,
+ *     onMutate: async (newTodo) => {
+ *       await queryClient.cancelQueries({ queryKey: ['todos'] })
+ *       const previousTodos = queryClient.getQueryData(['todos'])
+ *
+ *       queryClient.setQueryData(['todos'], (old) => [...old, newTodo])
+ *
+ *       // Passed to `onError` as `context` if the mutation fails.
+ *       return { previousTodos }
+ *     },
+ *     onError: (_err, _newTodo, context) => {
+ *       queryClient.setQueryData(['todos'], context.previousTodos)
+ *     },
+ *     onSettled: () => {
+ *       queryClient.invalidateQueries({ queryKey: ['todos'] })
+ *     },
+ *   })
+ *
+ *   return (
+ *     <button onClick={() => addMutation.mutate('Item')}>Add</button>
+ *   )
+ * }
+ * ```
  */
 export function useMutation<
   TData = unknown,
diff --git a/packages/preact-query/src/useQuery.ts b/packages/preact-query/src/useQuery.ts
index 593dbfbffd6..a585cdabe74 100644
--- a/packages/preact-query/src/useQuery.ts
+++ b/packages/preact-query/src/useQuery.ts
@@ -69,6 +69,22 @@ export function useQuery<
  *   )
  * }
  * ```
+ *
+ * @example
+ * A dependent query, only enabled once `postId` is set:
+ * ```tsx
+ * import { useQuery } from '@tanstack/preact-query'
+ *
+ * function Post({ postId }: { postId: number }) {
+ *   const { data } = useQuery({
+ *     queryKey: ['post', postId],
+ *     queryFn: () => fetchPost(postId),
+ *     enabled: !!postId,
+ *   })
+ *
+ *   return <h1>{data?.title}</h1>
+ * }
+ * ```
  */
 export function useQuery<
   TQueryFnData = unknown,

From ffd159b0d6cca92930a0600044c95de1c0b773a7 Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Tue, 25 Aug 2026 01:00:41 +0900
Subject: [PATCH 07/28] docs(preact-query): add parameterized factory and
 mutationKey lookup examples to queryOptions/mutationOptions

---
 .../reference/functions/mutationOptions.md    | 15 ++--
 .../reference/functions/queryOptions.md       | 69 +++++++++++++++++--
 packages/preact-query/src/mutationOptions.ts  | 11 ++-
 packages/preact-query/src/queryOptions.ts     | 60 ++++++++++++++++
 4 files changed, 143 insertions(+), 12 deletions(-)

diff --git a/docs/framework/preact/reference/functions/mutationOptions.md b/docs/framework/preact/reference/functions/mutationOptions.md
index cdc67e6eadd..e924ecf6710 100644
--- a/docs/framework/preact/reference/functions/mutationOptions.md
+++ b/docs/framework/preact/reference/functions/mutationOptions.md
@@ -9,9 +9,11 @@ title: mutationOptions
 function mutationOptions<TData, TError, TVariables, TOnMutateResult>(options): WithRequired<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">;
 ```
 
-Defined in: [preact-query/src/mutationOptions.ts:23](https://github.com/TanStack/query/blob/main/packages/preact-query/src/mutationOptions.ts#L23)
+Defined in: [preact-query/src/mutationOptions.ts:30](https://github.com/TanStack/query/blob/main/packages/preact-query/src/mutationOptions.ts#L30)
 
-You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`.
+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
+`useMutationState`.
 
 ### Type Parameters
 
@@ -44,7 +46,7 @@ You can generally pass everything to `mutationOptions` that you can also pass to
 ### Example
 
 ```tsx
-import { mutationOptions, useMutation } from '@tanstack/preact-query'
+import { mutationOptions, useMutation, useMutationState } from '@tanstack/preact-query'
 
 export const createPostOptions = mutationOptions({
   mutationKey: ['posts', 'create'],
@@ -55,6 +57,11 @@ function CreatePost() {
   const mutation = useMutation(createPostOptions)
   return <button onClick={() => mutation.mutate({ title: 'Hello' })}>Create</button>
 }
+
+// Elsewhere, e.g. to show a global "saving…" indicator:
+const isCreatingPost = useMutationState({
+  filters: { mutationKey: createPostOptions.mutationKey, status: 'pending' },
+}).length > 0
 ```
 
 ## Call Signature
@@ -63,7 +70,7 @@ function CreatePost() {
 function mutationOptions<TData, TError, TVariables, TOnMutateResult>(options): Omit<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">;
 ```
 
-Defined in: [preact-query/src/mutationOptions.ts:55](https://github.com/TanStack/query/blob/main/packages/preact-query/src/mutationOptions.ts#L55)
+Defined in: [preact-query/src/mutationOptions.ts:62](https://github.com/TanStack/query/blob/main/packages/preact-query/src/mutationOptions.ts#L62)
 
 You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`.
 
diff --git a/docs/framework/preact/reference/functions/queryOptions.md b/docs/framework/preact/reference/functions/queryOptions.md
index 9e3fec62381..9a3b00e85e7 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:68](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L68)
+Defined in: [preact-query/src/queryOptions.ts:88](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L88)
 
 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
@@ -43,7 +43,7 @@ is the query key to generate options for.
 
 `Omit`\<[`UseQueryOptions`](../interfaces/UseQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>, `"queryFn"`\> & `object` & `QueryKeyWithDataTag`\<`TQueryKey`, `TQueryFnData`, `TError`\>
 
-### Example
+### Examples
 
 ```tsx
 import { queryOptions } from '@tanstack/preact-query'
@@ -54,13 +54,32 @@ export const postsOptions = queryOptions({
 })
 ```
 
+A parameterized factory, reused across a hook and an imperative call with the same cache entry:
+```tsx
+import { queryOptions, useQuery } from '@tanstack/preact-query'
+
+export const postOptions = (id: string) =>
+  queryOptions({
+    queryKey: ['post', id],
+    queryFn: () => fetchPost(id),
+  })
+
+function Post({ id }: { id: string }) {
+  const { data } = useQuery(postOptions(id))
+  return <h1>{data?.title}</h1>
+}
+
+// Elsewhere, e.g. to warm the cache before rendering `<Post>`:
+queryClient.prefetchQuery(postOptions(id))
+```
+
 ## Call Signature
 
 ```ts
 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:93](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L93)
+Defined in: [preact-query/src/queryOptions.ts:133](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L133)
 
 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
@@ -94,7 +113,7 @@ is the query key to generate options for.
 
 `OmitKeyof`\<[`UseQueryOptions`](../interfaces/UseQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>, `"queryFn"`\> & `object` & `QueryKeyWithDataTag`\<`TQueryKey`, `TQueryFnData`, `TError`\>
 
-### Example
+### Examples
 
 ```tsx
 import { queryOptions } from '@tanstack/preact-query'
@@ -105,13 +124,32 @@ export const postsOptions = queryOptions({
 })
 ```
 
+A parameterized factory, reused across a hook and an imperative call with the same cache entry:
+```tsx
+import { queryOptions, useQuery } from '@tanstack/preact-query'
+
+export const postOptions = (id: string) =>
+  queryOptions({
+    queryKey: ['post', id],
+    queryFn: () => fetchPost(id),
+  })
+
+function Post({ id }: { id: string }) {
+  const { data } = useQuery(postOptions(id))
+  return <h1>{data?.title}</h1>
+}
+
+// Elsewhere, e.g. to warm the cache before rendering `<Post>`:
+queryClient.prefetchQuery(postOptions(id))
+```
+
 ## Call Signature
 
 ```ts
 function queryOptions<TQueryFnData, TError, TData, TQueryKey>(options): UseQueryOptions<TQueryFnData, TError, TData, TQueryKey> & object & QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>;
 ```
 
-Defined in: [preact-query/src/queryOptions.ts:118](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L118)
+Defined in: [preact-query/src/queryOptions.ts:178](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L178)
 
 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
@@ -145,7 +183,7 @@ is the query key to generate options for.
 
 [`UseQueryOptions`](../interfaces/UseQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & `object` & `QueryKeyWithDataTag`\<`TQueryKey`, `TQueryFnData`, `TError`\>
 
-### Example
+### Examples
 
 ```tsx
 import { queryOptions } from '@tanstack/preact-query'
@@ -155,3 +193,22 @@ export const postsOptions = queryOptions({
   queryFn: fetchPosts,
 })
 ```
+
+A parameterized factory, reused across a hook and an imperative call with the same cache entry:
+```tsx
+import { queryOptions, useQuery } from '@tanstack/preact-query'
+
+export const postOptions = (id: string) =>
+  queryOptions({
+    queryKey: ['post', id],
+    queryFn: () => fetchPost(id),
+  })
+
+function Post({ id }: { id: string }) {
+  const { data } = useQuery(postOptions(id))
+  return <h1>{data?.title}</h1>
+}
+
+// Elsewhere, e.g. to warm the cache before rendering `<Post>`:
+queryClient.prefetchQuery(postOptions(id))
+```
diff --git a/packages/preact-query/src/mutationOptions.ts b/packages/preact-query/src/mutationOptions.ts
index 09940b9b369..b2ec881dcd2 100644
--- a/packages/preact-query/src/mutationOptions.ts
+++ b/packages/preact-query/src/mutationOptions.ts
@@ -3,11 +3,13 @@ import type { DefaultError, WithRequired } from '@tanstack/query-core'
 import type { UseMutationOptions } from './types'
 
 /**
- * You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`.
+ * 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
+ * `useMutationState`.
  *
  * @example
  * ```tsx
- * import { mutationOptions, useMutation } from '@tanstack/preact-query'
+ * import { mutationOptions, useMutation, useMutationState } from '@tanstack/preact-query'
  *
  * export const createPostOptions = mutationOptions({
  *   mutationKey: ['posts', 'create'],
@@ -18,6 +20,11 @@ import type { UseMutationOptions } from './types'
  *   const mutation = useMutation(createPostOptions)
  *   return <button onClick={() => mutation.mutate({ title: 'Hello' })}>Create</button>
  * }
+ *
+ * // Elsewhere, e.g. to show a global "saving…" indicator:
+ * const isCreatingPost = useMutationState({
+ *   filters: { mutationKey: createPostOptions.mutationKey, status: 'pending' },
+ * }).length > 0
  * ```
  */
 export function mutationOptions<
diff --git a/packages/preact-query/src/queryOptions.ts b/packages/preact-query/src/queryOptions.ts
index 2041149a6f0..423776057f0 100644
--- a/packages/preact-query/src/queryOptions.ts
+++ b/packages/preact-query/src/queryOptions.ts
@@ -64,6 +64,26 @@ export type DefinedInitialDataOptions<
  *   queryFn: fetchPosts,
  * })
  * ```
+ *
+ * @example
+ * A parameterized factory, reused across a hook and an imperative call with the same cache entry:
+ * ```tsx
+ * import { queryOptions, useQuery } from '@tanstack/preact-query'
+ *
+ * export const postOptions = (id: string) =>
+ *   queryOptions({
+ *     queryKey: ['post', id],
+ *     queryFn: () => fetchPost(id),
+ *   })
+ *
+ * function Post({ id }: { id: string }) {
+ *   const { data } = useQuery(postOptions(id))
+ *   return <h1>{data?.title}</h1>
+ * }
+ *
+ * // Elsewhere, e.g. to warm the cache before rendering `<Post>`:
+ * queryClient.prefetchQuery(postOptions(id))
+ * ```
  */
 export function queryOptions<
   TQueryFnData = unknown,
@@ -89,6 +109,26 @@ export function queryOptions<
  *   queryFn: fetchPosts,
  * })
  * ```
+ *
+ * @example
+ * A parameterized factory, reused across a hook and an imperative call with the same cache entry:
+ * ```tsx
+ * import { queryOptions, useQuery } from '@tanstack/preact-query'
+ *
+ * export const postOptions = (id: string) =>
+ *   queryOptions({
+ *     queryKey: ['post', id],
+ *     queryFn: () => fetchPost(id),
+ *   })
+ *
+ * function Post({ id }: { id: string }) {
+ *   const { data } = useQuery(postOptions(id))
+ *   return <h1>{data?.title}</h1>
+ * }
+ *
+ * // Elsewhere, e.g. to warm the cache before rendering `<Post>`:
+ * queryClient.prefetchQuery(postOptions(id))
+ * ```
  */
 export function queryOptions<
   TQueryFnData = unknown,
@@ -114,6 +154,26 @@ export function queryOptions<
  *   queryFn: fetchPosts,
  * })
  * ```
+ *
+ * @example
+ * A parameterized factory, reused across a hook and an imperative call with the same cache entry:
+ * ```tsx
+ * import { queryOptions, useQuery } from '@tanstack/preact-query'
+ *
+ * export const postOptions = (id: string) =>
+ *   queryOptions({
+ *     queryKey: ['post', id],
+ *     queryFn: () => fetchPost(id),
+ *   })
+ *
+ * function Post({ id }: { id: string }) {
+ *   const { data } = useQuery(postOptions(id))
+ *   return <h1>{data?.title}</h1>
+ * }
+ *
+ * // Elsewhere, e.g. to warm the cache before rendering `<Post>`:
+ * queryClient.prefetchQuery(postOptions(id))
+ * ```
  */
 export function queryOptions<
   TQueryFnData = unknown,

From b68477a60d47f596f9c8cca21ff6d73abbce86ee Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Tue, 25 Aug 2026 01:03:45 +0900
Subject: [PATCH 08/28] docs(preact-query): add infiniteQueryOptions factory
 example and restore useMutationState's third example

---
 .../functions/infiniteQueryOptions.md         | 75 +++++++++++++++++--
 .../reference/functions/useMutationState.md   | 17 ++++-
 .../preact-query/src/infiniteQueryOptions.ts  | 66 ++++++++++++++++
 packages/preact-query/src/useMutationState.ts | 18 ++++-
 4 files changed, 167 insertions(+), 9 deletions(-)

diff --git a/docs/framework/preact/reference/functions/infiniteQueryOptions.md b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
index 0ac072d98c6..8df04186483 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:93](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L93)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:115](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L115)
 
 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`.
@@ -47,7 +47,7 @@ These options can be shared across hooks and imperative APIs such as `queryClien
 
 [`UseInfiniteQueryOptions`](../interfaces/UseInfiniteQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & `object` & `QueryKeyWithDataTag`\<`TQueryKey`, `InfiniteData`\<`TQueryFnData`, `unknown`\>, `TError`\>
 
-### Example
+### Examples
 
 ```tsx
 import { infiniteQueryOptions } from '@tanstack/preact-query'
@@ -60,13 +60,34 @@ export const projectsOptions = infiniteQueryOptions({
 })
 ```
 
+A parameterized factory, reused across a hook and an imperative call with the same cache entry:
+```tsx
+import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
+
+export 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 } = useInfiniteQuery(commentsOptions(postId))
+  return <>{data.pages.map((page) => page.comments.map((c) => <p key={c.id}>{c.text}</p>))}</>
+}
+
+// Elsewhere, e.g. to warm the cache before rendering `<Comments>`:
+queryClient.prefetchInfiniteQuery(commentsOptions(postId))
+```
+
 ## 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:133](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L133)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:177](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L177)
 
 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`.
@@ -104,7 +125,7 @@ These options can be shared across hooks and imperative APIs such as `queryClien
 
 `OmitKeyof`\<[`UseInfiniteQueryOptions`](../interfaces/UseInfiniteQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\>, `"queryFn"`\> & `object` & `QueryKeyWithDataTag`\<`TQueryKey`, `InfiniteData`\<`TQueryFnData`, `unknown`\>, `TError`\>
 
-### Example
+### Examples
 
 ```tsx
 import { infiniteQueryOptions } from '@tanstack/preact-query'
@@ -117,13 +138,34 @@ export const projectsOptions = infiniteQueryOptions({
 })
 ```
 
+A parameterized factory, reused across a hook and an imperative call with the same cache entry:
+```tsx
+import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
+
+export 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 } = useInfiniteQuery(commentsOptions(postId))
+  return <>{data.pages.map((page) => page.comments.map((c) => <p key={c.id}>{c.text}</p>))}</>
+}
+
+// Elsewhere, e.g. to warm the cache before rendering `<Comments>`:
+queryClient.prefetchInfiniteQuery(commentsOptions(postId))
+```
+
 ## Call Signature
 
 ```ts
 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: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`.
@@ -161,7 +203,7 @@ These options can be shared across hooks and imperative APIs such as `queryClien
 
 [`UseInfiniteQueryOptions`](../interfaces/UseInfiniteQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & `object` & `QueryKeyWithDataTag`\<`TQueryKey`, `InfiniteData`\<`TQueryFnData`, `unknown`\>, `TError`\>
 
-### Example
+### Examples
 
 ```tsx
 import { infiniteQueryOptions } from '@tanstack/preact-query'
@@ -173,3 +215,24 @@ export const projectsOptions = infiniteQueryOptions({
   getNextPageParam: (lastPage) => lastPage.nextId,
 })
 ```
+
+A parameterized factory, reused across a hook and an imperative call with the same cache entry:
+```tsx
+import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
+
+export 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 } = useInfiniteQuery(commentsOptions(postId))
+  return <>{data.pages.map((page) => page.comments.map((c) => <p key={c.id}>{c.text}</p>))}</>
+}
+
+// Elsewhere, e.g. to warm the cache before rendering `<Comments>`:
+queryClient.prefetchInfiniteQuery(commentsOptions(postId))
+```
diff --git a/docs/framework/preact/reference/functions/useMutationState.md b/docs/framework/preact/reference/functions/useMutationState.md
index 56ad8e157db..626810d33f3 100644
--- a/docs/framework/preact/reference/functions/useMutationState.md
+++ b/docs/framework/preact/reference/functions/useMutationState.md
@@ -7,11 +7,14 @@ title: useMutationState
 function useMutationState<TResult, TMutation>(options, queryClient?): TResult[];
 ```
 
-Defined in: [preact-query/src/useMutationState.ts:123](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useMutationState.ts#L123)
+Defined in: [preact-query/src/useMutationState.ts:137](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useMutationState.ts#L137)
 
 `useMutationState` is a hook that gives you access to all mutations in the `MutationCache`. You can pass
 `filters` to it to narrow down your mutations, and `select` to transform the mutation state.
 
+`options.filters` narrows down the matched mutations (MutationFilters), and `options.select` transforms
+the mutation state.
+
 ## Type Parameters
 
 ### TResult
@@ -71,3 +74,15 @@ const data = useMutationState({
   select: (mutation) => mutation.state.data,
 })
 ```
+
+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,
+})
+
+const latest = data[data.length - 1]
+```
diff --git a/packages/preact-query/src/infiniteQueryOptions.ts b/packages/preact-query/src/infiniteQueryOptions.ts
index 3e26e75a512..5965ac33fad 100644
--- a/packages/preact-query/src/infiniteQueryOptions.ts
+++ b/packages/preact-query/src/infiniteQueryOptions.ts
@@ -89,6 +89,28 @@ export type DefinedInitialDataInfiniteOptions<
  *   getNextPageParam: (lastPage) => lastPage.nextId,
  * })
  * ```
+ *
+ * @example
+ * A parameterized factory, reused across a hook and an imperative call with the same cache entry:
+ * ```tsx
+ * import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
+ *
+ * export 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 } = useInfiniteQuery(commentsOptions(postId))
+ *   return <>{data.pages.map((page) => page.comments.map((c) => <p key={c.id}>{c.text}</p>))}</>
+ * }
+ *
+ * // Elsewhere, e.g. to warm the cache before rendering `<Comments>`:
+ * queryClient.prefetchInfiniteQuery(commentsOptions(postId))
+ * ```
  */
 export function infiniteQueryOptions<
   TQueryFnData,
@@ -129,6 +151,28 @@ export function infiniteQueryOptions<
  *   getNextPageParam: (lastPage) => lastPage.nextId,
  * })
  * ```
+ *
+ * @example
+ * A parameterized factory, reused across a hook and an imperative call with the same cache entry:
+ * ```tsx
+ * import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
+ *
+ * export 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 } = useInfiniteQuery(commentsOptions(postId))
+ *   return <>{data.pages.map((page) => page.comments.map((c) => <p key={c.id}>{c.text}</p>))}</>
+ * }
+ *
+ * // Elsewhere, e.g. to warm the cache before rendering `<Comments>`:
+ * queryClient.prefetchInfiniteQuery(commentsOptions(postId))
+ * ```
  */
 export function infiniteQueryOptions<
   TQueryFnData,
@@ -169,6 +213,28 @@ export function infiniteQueryOptions<
  *   getNextPageParam: (lastPage) => lastPage.nextId,
  * })
  * ```
+ *
+ * @example
+ * A parameterized factory, reused across a hook and an imperative call with the same cache entry:
+ * ```tsx
+ * import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
+ *
+ * export 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 } = useInfiniteQuery(commentsOptions(postId))
+ *   return <>{data.pages.map((page) => page.comments.map((c) => <p key={c.id}>{c.text}</p>))}</>
+ * }
+ *
+ * // Elsewhere, e.g. to warm the cache before rendering `<Comments>`:
+ * queryClient.prefetchInfiniteQuery(commentsOptions(postId))
+ * ```
  */
 export function infiniteQueryOptions<
   TQueryFnData,
diff --git a/packages/preact-query/src/useMutationState.ts b/packages/preact-query/src/useMutationState.ts
index 0c0f0dafd8d..6919bfb832d 100644
--- a/packages/preact-query/src/useMutationState.ts
+++ b/packages/preact-query/src/useMutationState.ts
@@ -83,8 +83,9 @@ function getResult<
  * `useMutationState` is a hook that gives you access to all mutations in the `MutationCache`. You can pass
  * `filters` to it to narrow down your mutations, and `select` to transform the mutation state.
  *
- * @param options.filters - {@link MutationFilters}
- * @param options.select - Use this to transform the mutation state.
+ * `options.filters` narrows down the matched mutations ({@link MutationFilters}), and `options.select` transforms
+ * the mutation state.
+ *
  * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
  * be used.
  * @returns Will be an Array of whatever `select` returns for each matching mutation.
@@ -119,6 +120,19 @@ function getResult<
  *   select: (mutation) => mutation.state.data,
  * })
  * ```
+ *
+ * @example
+ * 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,
+ * })
+ *
+ * const latest = data[data.length - 1]
+ * ```
  */
 export function useMutationState<
   TResult = MutationState,

From 9c43e05789199d14de45eb9fa01db9f3d6c90b5f Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Tue, 25 Aug 2026 01:08:12 +0900
Subject: [PATCH 09/28] docs(preact-query): add TkDodo-inspired multi-API
 reuse, initialData, and per-call mutate callback examples

---
 .../reference/functions/queryOptions.md       | 51 +++++++++++++++++--
 .../preact/reference/functions/useMutation.md |  7 ++-
 .../preact/reference/functions/useQuery.md    | 22 +++++++-
 packages/preact-query/src/queryOptions.ts     | 48 +++++++++++++++++
 packages/preact-query/src/useMutation.ts      |  4 ++
 packages/preact-query/src/useQuery.ts         | 21 ++++++++
 6 files changed, 148 insertions(+), 5 deletions(-)

diff --git a/docs/framework/preact/reference/functions/queryOptions.md b/docs/framework/preact/reference/functions/queryOptions.md
index 9a3b00e85e7..e2feca184e9 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:88](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L88)
+Defined in: [preact-query/src/queryOptions.ts:104](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L104)
 
 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
@@ -73,13 +73,28 @@ function Post({ id }: { id: string }) {
 queryClient.prefetchQuery(postOptions(id))
 ```
 
+The same options object works with every API that accepts query options:
+```tsx
+import { queryOptions, useQuery, useSuspenseQuery } from '@tanstack/preact-query'
+
+const todosOptions = queryOptions({
+  queryKey: ['todos'],
+  queryFn: fetchTodos,
+})
+
+useQuery(todosOptions)
+useSuspenseQuery(todosOptions)
+queryClient.prefetchQuery(todosOptions)
+queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefined
+```
+
 ## Call Signature
 
 ```ts
 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:133](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L133)
+Defined in: [preact-query/src/queryOptions.ts:165](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L165)
 
 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
@@ -143,13 +158,28 @@ function Post({ id }: { id: string }) {
 queryClient.prefetchQuery(postOptions(id))
 ```
 
+The same options object works with every API that accepts query options:
+```tsx
+import { queryOptions, useQuery, useSuspenseQuery } from '@tanstack/preact-query'
+
+const todosOptions = queryOptions({
+  queryKey: ['todos'],
+  queryFn: fetchTodos,
+})
+
+useQuery(todosOptions)
+useSuspenseQuery(todosOptions)
+queryClient.prefetchQuery(todosOptions)
+queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefined
+```
+
 ## Call Signature
 
 ```ts
 function queryOptions<TQueryFnData, TError, TData, TQueryKey>(options): UseQueryOptions<TQueryFnData, TError, TData, TQueryKey> & object & QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>;
 ```
 
-Defined in: [preact-query/src/queryOptions.ts:178](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L178)
+Defined in: [preact-query/src/queryOptions.ts:226](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L226)
 
 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
@@ -212,3 +242,18 @@ function Post({ id }: { id: string }) {
 // Elsewhere, e.g. to warm the cache before rendering `<Post>`:
 queryClient.prefetchQuery(postOptions(id))
 ```
+
+The same options object works with every API that accepts query options:
+```tsx
+import { queryOptions, useQuery, useSuspenseQuery } from '@tanstack/preact-query'
+
+const todosOptions = queryOptions({
+  queryKey: ['todos'],
+  queryFn: fetchTodos,
+})
+
+useQuery(todosOptions)
+useSuspenseQuery(todosOptions)
+queryClient.prefetchQuery(todosOptions)
+queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefined
+```
diff --git a/docs/framework/preact/reference/functions/useMutation.md b/docs/framework/preact/reference/functions/useMutation.md
index f5d86983c35..2a33451105c 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:75](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useMutation.ts#L75)
+Defined in: [preact-query/src/useMutation.ts:79](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useMutation.ts#L79)
 
 ## Type Parameters
 
@@ -44,6 +44,11 @@ be used.
 
 [`UseMutationResult`](../type-aliases/UseMutationResult.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>
 
+`mutate`/`mutateAsync` also accept per-call `onSuccess`/`onError`/`onSettled` callbacks as a second
+argument, useful for triggering call-site side effects (e.g. navigation) without coupling them to the shared
+mutation definition. If you make multiple requests, `onSuccess` will fire only after the latest call you've
+made.
+
 ## Examples
 
 ```tsx
diff --git a/docs/framework/preact/reference/functions/useQuery.md b/docs/framework/preact/reference/functions/useQuery.md
index 0ae8fbca55e..084cb50bd8e 100644
--- a/docs/framework/preact/reference/functions/useQuery.md
+++ b/docs/framework/preact/reference/functions/useQuery.md
@@ -95,7 +95,7 @@ be used.
 function useQuery<TQueryFnData, TError, TData, TQueryKey>(options, queryClient?): UseQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useQuery.ts:89](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L89)
+Defined in: [preact-query/src/useQuery.ts:110](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L110)
 
 ### Type Parameters
 
@@ -173,3 +173,23 @@ function Post({ postId }: { postId: number }) {
   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'
+
+function Post({ postId }: { postId: number }) {
+  const queryClient = useQueryClient()
+
+  const { data } = useQuery({
+    queryKey: ['post', postId],
+    queryFn: () => fetchPost(postId),
+    initialData: () =>
+      queryClient
+        .getQueryData(['posts'])
+        ?.find((post) => post.id === postId),
+  })
+
+  return <h1>{data?.title}</h1>
+}
+```
diff --git a/packages/preact-query/src/queryOptions.ts b/packages/preact-query/src/queryOptions.ts
index 423776057f0..ca9c7c466e5 100644
--- a/packages/preact-query/src/queryOptions.ts
+++ b/packages/preact-query/src/queryOptions.ts
@@ -84,6 +84,22 @@ export type DefinedInitialDataOptions<
  * // Elsewhere, e.g. to warm the cache before rendering `<Post>`:
  * queryClient.prefetchQuery(postOptions(id))
  * ```
+ *
+ * @example
+ * The same options object works with every API that accepts query options:
+ * ```tsx
+ * import { queryOptions, useQuery, useSuspenseQuery } from '@tanstack/preact-query'
+ *
+ * const todosOptions = queryOptions({
+ *   queryKey: ['todos'],
+ *   queryFn: fetchTodos,
+ * })
+ *
+ * useQuery(todosOptions)
+ * useSuspenseQuery(todosOptions)
+ * queryClient.prefetchQuery(todosOptions)
+ * queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefined
+ * ```
  */
 export function queryOptions<
   TQueryFnData = unknown,
@@ -129,6 +145,22 @@ export function queryOptions<
  * // Elsewhere, e.g. to warm the cache before rendering `<Post>`:
  * queryClient.prefetchQuery(postOptions(id))
  * ```
+ *
+ * @example
+ * The same options object works with every API that accepts query options:
+ * ```tsx
+ * import { queryOptions, useQuery, useSuspenseQuery } from '@tanstack/preact-query'
+ *
+ * const todosOptions = queryOptions({
+ *   queryKey: ['todos'],
+ *   queryFn: fetchTodos,
+ * })
+ *
+ * useQuery(todosOptions)
+ * useSuspenseQuery(todosOptions)
+ * queryClient.prefetchQuery(todosOptions)
+ * queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefined
+ * ```
  */
 export function queryOptions<
   TQueryFnData = unknown,
@@ -174,6 +206,22 @@ export function queryOptions<
  * // Elsewhere, e.g. to warm the cache before rendering `<Post>`:
  * queryClient.prefetchQuery(postOptions(id))
  * ```
+ *
+ * @example
+ * The same options object works with every API that accepts query options:
+ * ```tsx
+ * import { queryOptions, useQuery, useSuspenseQuery } from '@tanstack/preact-query'
+ *
+ * const todosOptions = queryOptions({
+ *   queryKey: ['todos'],
+ *   queryFn: fetchTodos,
+ * })
+ *
+ * useQuery(todosOptions)
+ * useSuspenseQuery(todosOptions)
+ * queryClient.prefetchQuery(todosOptions)
+ * queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefined
+ * ```
  */
 export function queryOptions<
   TQueryFnData = unknown,
diff --git a/packages/preact-query/src/useMutation.ts b/packages/preact-query/src/useMutation.ts
index a21454f55d2..535e06b2563 100644
--- a/packages/preact-query/src/useMutation.ts
+++ b/packages/preact-query/src/useMutation.ts
@@ -20,6 +20,10 @@ import { useSyncExternalStore } from './utils'
 /**
  * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
  * be used.
+ * @returns `mutate`/`mutateAsync` also accept per-call `onSuccess`/`onError`/`onSettled` callbacks as a second
+ * argument, useful for triggering call-site side effects (e.g. navigation) without coupling them to the shared
+ * mutation definition. If you make multiple requests, `onSuccess` will fire only after the latest call you've
+ * made.
  *
  * @example
  * ```tsx
diff --git a/packages/preact-query/src/useQuery.ts b/packages/preact-query/src/useQuery.ts
index a585cdabe74..7d24e696344 100644
--- a/packages/preact-query/src/useQuery.ts
+++ b/packages/preact-query/src/useQuery.ts
@@ -85,6 +85,27 @@ export function useQuery<
  *   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'
+ *
+ * function Post({ postId }: { postId: number }) {
+ *   const queryClient = useQueryClient()
+ *
+ *   const { data } = useQuery({
+ *     queryKey: ['post', postId],
+ *     queryFn: () => fetchPost(postId),
+ *     initialData: () =>
+ *       queryClient
+ *         .getQueryData(['posts'])
+ *         ?.find((post) => post.id === postId),
+ *   })
+ *
+ *   return <h1>{data?.title}</h1>
+ * }
+ * ```
  */
 export function useQuery<
   TQueryFnData = unknown,

From dcf64a9fd7a6b700253bb14d7318c27cfe96ade4 Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Tue, 25 Aug 2026 01:12:49 +0900
Subject: [PATCH 10/28] docs(preact-query): document useIsRestoring,
 initialData, mutateAsync, and skipToken-excluded queryFn fields

---
 .../functions/infiniteQueryOptions.md          | 12 +++---------
 .../preact/reference/functions/queryOptions.md | 12 +++---------
 .../reference/functions/useIsRestoring.md      |  6 +++++-
 .../interfaces/UseInfiniteQueryOptions.md      |  4 ++--
 .../reference/interfaces/UseMutationOptions.md |  2 +-
 .../reference/interfaces/UseQueryOptions.md    |  2 +-
 .../UseSuspenseInfiniteQueryOptions.md         |  9 ++++++---
 .../interfaces/UseSuspenseQueryOptions.md      |  7 +++++--
 .../type-aliases/AnyUseInfiniteQueryOptions.md |  2 +-
 .../type-aliases/AnyUseMutationOptions.md      |  2 +-
 .../type-aliases/AnyUseQueryOptions.md         |  2 +-
 .../AnyUseSuspenseInfiniteQueryOptions.md      |  2 +-
 .../type-aliases/AnyUseSuspenseQueryOptions.md |  2 +-
 .../DefinedInitialDataInfiniteOptions.md       |  8 +++++++-
 .../type-aliases/DefinedInitialDataOptions.md  |  8 +++++++-
 .../DefinedUseInfiniteQueryResult.md           |  2 +-
 .../type-aliases/DefinedUseQueryResult.md      |  2 +-
 .../UndefinedInitialDataInfiniteOptions.md     |  6 ++++++
 .../UndefinedInitialDataOptions.md             |  6 ++++++
 .../UnusedSkipTokenInfiniteOptions.md          |  5 ++++-
 .../type-aliases/UnusedSkipTokenOptions.md     |  5 ++++-
 .../type-aliases/UseBaseMutationResult.md      |  4 +++-
 .../type-aliases/UseBaseQueryResult.md         |  2 +-
 .../type-aliases/UseInfiniteQueryResult.md     |  2 +-
 .../type-aliases/UseMutateAsyncFunction.md     |  2 +-
 .../type-aliases/UseMutateFunction.md          |  2 +-
 .../type-aliases/UseMutationResult.md          |  2 +-
 .../UsePrefetchInfiniteQueryOptions.md         |  4 +++-
 .../type-aliases/UsePrefetchQueryOptions.md    |  2 ++
 .../reference/type-aliases/UseQueryResult.md   |  2 +-
 .../UseSuspenseInfiniteQueryResult.md          |  2 +-
 .../type-aliases/UseSuspenseQueryResult.md     |  2 +-
 .../reference/variables/IsRestoringProvider.md |  2 +-
 .../preact-query/src/IsRestoringProvider.ts    |  5 +++++
 .../preact-query/src/infiniteQueryOptions.ts   | 18 ++++++++++++++++++
 packages/preact-query/src/queryOptions.ts      | 18 ++++++++++++++++++
 packages/preact-query/src/types.ts             | 17 +++++++++++++++++
 37 files changed, 142 insertions(+), 50 deletions(-)

diff --git a/docs/framework/preact/reference/functions/infiniteQueryOptions.md b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
index 8df04186483..d251f171a68 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:115](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L115)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:133](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L133)
 
 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`.
@@ -45,8 +45,6 @@ These options can be shared across hooks and imperative APIs such as `queryClien
 
 ### Returns
 
-[`UseInfiniteQueryOptions`](../interfaces/UseInfiniteQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & `object` & `QueryKeyWithDataTag`\<`TQueryKey`, `InfiniteData`\<`TQueryFnData`, `unknown`\>, `TError`\>
-
 ### Examples
 
 ```tsx
@@ -87,7 +85,7 @@ queryClient.prefetchInfiniteQuery(commentsOptions(postId))
 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:177](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L177)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:195](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L195)
 
 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,8 +121,6 @@ These options can be shared across hooks and imperative APIs such as `queryClien
 
 ### Returns
 
-`OmitKeyof`\<[`UseInfiniteQueryOptions`](../interfaces/UseInfiniteQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\>, `"queryFn"`\> & `object` & `QueryKeyWithDataTag`\<`TQueryKey`, `InfiniteData`\<`TQueryFnData`, `unknown`\>, `TError`\>
-
 ### Examples
 
 ```tsx
@@ -165,7 +161,7 @@ queryClient.prefetchInfiniteQuery(commentsOptions(postId))
 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:239](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L239)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:257](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L257)
 
 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`.
@@ -201,8 +197,6 @@ These options can be shared across hooks and imperative APIs such as `queryClien
 
 ### Returns
 
-[`UseInfiniteQueryOptions`](../interfaces/UseInfiniteQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & `object` & `QueryKeyWithDataTag`\<`TQueryKey`, `InfiniteData`\<`TQueryFnData`, `unknown`\>, `TError`\>
-
 ### Examples
 
 ```tsx
diff --git a/docs/framework/preact/reference/functions/queryOptions.md b/docs/framework/preact/reference/functions/queryOptions.md
index e2feca184e9..abd77b8f5b1 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:104](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L104)
+Defined in: [preact-query/src/queryOptions.ts:122](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L122)
 
 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
@@ -41,8 +41,6 @@ is the query key to generate options for.
 
 ### Returns
 
-`Omit`\<[`UseQueryOptions`](../interfaces/UseQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>, `"queryFn"`\> & `object` & `QueryKeyWithDataTag`\<`TQueryKey`, `TQueryFnData`, `TError`\>
-
 ### Examples
 
 ```tsx
@@ -94,7 +92,7 @@ queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefi
 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:165](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L165)
+Defined in: [preact-query/src/queryOptions.ts:183](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L183)
 
 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
@@ -126,8 +124,6 @@ is the query key to generate options for.
 
 ### Returns
 
-`OmitKeyof`\<[`UseQueryOptions`](../interfaces/UseQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>, `"queryFn"`\> & `object` & `QueryKeyWithDataTag`\<`TQueryKey`, `TQueryFnData`, `TError`\>
-
 ### Examples
 
 ```tsx
@@ -179,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:226](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L226)
+Defined in: [preact-query/src/queryOptions.ts:244](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L244)
 
 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
@@ -211,8 +207,6 @@ is the query key to generate options for.
 
 ### Returns
 
-[`UseQueryOptions`](../interfaces/UseQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & `object` & `QueryKeyWithDataTag`\<`TQueryKey`, `TQueryFnData`, `TError`\>
-
 ### Examples
 
 ```tsx
diff --git a/docs/framework/preact/reference/functions/useIsRestoring.md b/docs/framework/preact/reference/functions/useIsRestoring.md
index 5b3b14ecd7d..328d641ab52 100644
--- a/docs/framework/preact/reference/functions/useIsRestoring.md
+++ b/docs/framework/preact/reference/functions/useIsRestoring.md
@@ -7,7 +7,11 @@ title: useIsRestoring
 function useIsRestoring(): boolean;
 ```
 
-Defined in: [preact-query/src/IsRestoringProvider.ts:6](https://github.com/TanStack/query/blob/main/packages/preact-query/src/IsRestoringProvider.ts#L6)
+Defined in: [preact-query/src/IsRestoringProvider.ts:11](https://github.com/TanStack/query/blob/main/packages/preact-query/src/IsRestoringProvider.ts#L11)
+
+If you are using `PersistQueryClientProvider`, you can also use the `useIsRestoring` hook alongside it to
+check if a restore is currently in progress. `useQuery` and friends also check this internally to avoid
+race conditions between the restore and mounting queries.
 
 ## Returns
 
diff --git a/docs/framework/preact/reference/interfaces/UseInfiniteQueryOptions.md b/docs/framework/preact/reference/interfaces/UseInfiniteQueryOptions.md
index c13265b1abe..ff860eb0aa3 100644
--- a/docs/framework/preact/reference/interfaces/UseInfiniteQueryOptions.md
+++ b/docs/framework/preact/reference/interfaces/UseInfiniteQueryOptions.md
@@ -3,7 +3,7 @@ id: UseInfiniteQueryOptions
 title: UseInfiniteQueryOptions
 ---
 
-Defined in: [preact-query/src/types.ts:139](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L139)
+Defined in: [preact-query/src/types.ts:149](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L149)
 
 ## Extends
 
@@ -39,7 +39,7 @@ Defined in: [preact-query/src/types.ts:139](https://github.com/TanStack/query/bl
 optional subscribed: boolean;
 ```
 
-Defined in: [preact-query/src/types.ts:159](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L159)
+Defined in: [preact-query/src/types.ts:169](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L169)
 
 Set this to `false` to unsubscribe this observer from updates to the query cache.
 Defaults to `true`.
diff --git a/docs/framework/preact/reference/interfaces/UseMutationOptions.md b/docs/framework/preact/reference/interfaces/UseMutationOptions.md
index fd9c51ee29a..67dc05c6ded 100644
--- a/docs/framework/preact/reference/interfaces/UseMutationOptions.md
+++ b/docs/framework/preact/reference/interfaces/UseMutationOptions.md
@@ -3,7 +3,7 @@ id: UseMutationOptions
 title: UseMutationOptions
 ---
 
-Defined in: [preact-query/src/types.ts:228](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L228)
+Defined in: [preact-query/src/types.ts:242](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L242)
 
 ## Extends
 
diff --git a/docs/framework/preact/reference/interfaces/UseQueryOptions.md b/docs/framework/preact/reference/interfaces/UseQueryOptions.md
index 184bf223a73..927b0c40b88 100644
--- a/docs/framework/preact/reference/interfaces/UseQueryOptions.md
+++ b/docs/framework/preact/reference/interfaces/UseQueryOptions.md
@@ -3,7 +3,7 @@ id: UseQueryOptions
 title: UseQueryOptions
 ---
 
-Defined in: [preact-query/src/types.ts:101](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L101)
+Defined in: [preact-query/src/types.ts:107](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L107)
 
 ## Extends
 
diff --git a/docs/framework/preact/reference/interfaces/UseSuspenseInfiniteQueryOptions.md b/docs/framework/preact/reference/interfaces/UseSuspenseInfiniteQueryOptions.md
index 08bc5e0b80d..78bde153d30 100644
--- a/docs/framework/preact/reference/interfaces/UseSuspenseInfiniteQueryOptions.md
+++ b/docs/framework/preact/reference/interfaces/UseSuspenseInfiniteQueryOptions.md
@@ -3,7 +3,7 @@ id: UseSuspenseInfiniteQueryOptions
 title: UseSuspenseInfiniteQueryOptions
 ---
 
-Defined in: [preact-query/src/types.ts:164](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L164)
+Defined in: [preact-query/src/types.ts:174](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L174)
 
 ## Extends
 
@@ -39,7 +39,10 @@ Defined in: [preact-query/src/types.ts:164](https://github.com/TanStack/query/bl
 optional queryFn: QueryFunction<TQueryFnData, TQueryKey, TPageParam>;
 ```
 
-Defined in: [preact-query/src/types.ts:174](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L174)
+Defined in: [preact-query/src/types.ts:188](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L188)
+
+`skipToken` is not allowed here — Suspense hooks cannot render a "disabled" state, so a query function
+must always be provided.
 
 ***
 
@@ -49,7 +52,7 @@ Defined in: [preact-query/src/types.ts:174](https://github.com/TanStack/query/bl
 optional subscribed: boolean;
 ```
 
-Defined in: [preact-query/src/types.ts:159](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L159)
+Defined in: [preact-query/src/types.ts:169](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L169)
 
 Set this to `false` to unsubscribe this observer from updates to the query cache.
 Defaults to `true`.
diff --git a/docs/framework/preact/reference/interfaces/UseSuspenseQueryOptions.md b/docs/framework/preact/reference/interfaces/UseSuspenseQueryOptions.md
index f140aea4329..b3b39b20770 100644
--- a/docs/framework/preact/reference/interfaces/UseSuspenseQueryOptions.md
+++ b/docs/framework/preact/reference/interfaces/UseSuspenseQueryOptions.md
@@ -3,7 +3,7 @@ id: UseSuspenseQueryOptions
 title: UseSuspenseQueryOptions
 ---
 
-Defined in: [preact-query/src/types.ts:117](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L117)
+Defined in: [preact-query/src/types.ts:123](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L123)
 
 ## Extends
 
@@ -35,7 +35,10 @@ Defined in: [preact-query/src/types.ts:117](https://github.com/TanStack/query/bl
 optional queryFn: QueryFunction<TQueryFnData, TQueryKey, never>;
 ```
 
-Defined in: [preact-query/src/types.ts:126](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L126)
+Defined in: [preact-query/src/types.ts:136](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L136)
+
+`skipToken` is not allowed here — Suspense hooks cannot render a "disabled" state, so a query function
+must always be provided.
 
 ***
 
diff --git a/docs/framework/preact/reference/type-aliases/AnyUseInfiniteQueryOptions.md b/docs/framework/preact/reference/type-aliases/AnyUseInfiniteQueryOptions.md
index 68ab8da3784..c2eb5ecc4a6 100644
--- a/docs/framework/preact/reference/type-aliases/AnyUseInfiniteQueryOptions.md
+++ b/docs/framework/preact/reference/type-aliases/AnyUseInfiniteQueryOptions.md
@@ -7,4 +7,4 @@ title: AnyUseInfiniteQueryOptions
 type AnyUseInfiniteQueryOptions = UseInfiniteQueryOptions<any, any, any, any, any>;
 ```
 
-Defined in: [preact-query/src/types.ts:132](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L132)
+Defined in: [preact-query/src/types.ts:142](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L142)
diff --git a/docs/framework/preact/reference/type-aliases/AnyUseMutationOptions.md b/docs/framework/preact/reference/type-aliases/AnyUseMutationOptions.md
index d467a5948e2..6d4327820ee 100644
--- a/docs/framework/preact/reference/type-aliases/AnyUseMutationOptions.md
+++ b/docs/framework/preact/reference/type-aliases/AnyUseMutationOptions.md
@@ -7,4 +7,4 @@ title: AnyUseMutationOptions
 type AnyUseMutationOptions = UseMutationOptions<any, any, any, any>;
 ```
 
-Defined in: [preact-query/src/types.ts:227](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L227)
+Defined in: [preact-query/src/types.ts:241](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L241)
diff --git a/docs/framework/preact/reference/type-aliases/AnyUseQueryOptions.md b/docs/framework/preact/reference/type-aliases/AnyUseQueryOptions.md
index 443742b7aa0..bd66a02d947 100644
--- a/docs/framework/preact/reference/type-aliases/AnyUseQueryOptions.md
+++ b/docs/framework/preact/reference/type-aliases/AnyUseQueryOptions.md
@@ -7,4 +7,4 @@ title: AnyUseQueryOptions
 type AnyUseQueryOptions = UseQueryOptions<any, any, any, any>;
 ```
 
-Defined in: [preact-query/src/types.ts:100](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L100)
+Defined in: [preact-query/src/types.ts:106](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L106)
diff --git a/docs/framework/preact/reference/type-aliases/AnyUseSuspenseInfiniteQueryOptions.md b/docs/framework/preact/reference/type-aliases/AnyUseSuspenseInfiniteQueryOptions.md
index 61163fa2537..fd8ceb5bb7e 100644
--- a/docs/framework/preact/reference/type-aliases/AnyUseSuspenseInfiniteQueryOptions.md
+++ b/docs/framework/preact/reference/type-aliases/AnyUseSuspenseInfiniteQueryOptions.md
@@ -7,4 +7,4 @@ title: AnyUseSuspenseInfiniteQueryOptions
 type AnyUseSuspenseInfiniteQueryOptions = UseSuspenseInfiniteQueryOptions<any, any, any, any, any>;
 ```
 
-Defined in: [preact-query/src/types.ts:162](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L162)
+Defined in: [preact-query/src/types.ts:172](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L172)
diff --git a/docs/framework/preact/reference/type-aliases/AnyUseSuspenseQueryOptions.md b/docs/framework/preact/reference/type-aliases/AnyUseSuspenseQueryOptions.md
index d74b006fe1c..708b7db3080 100644
--- a/docs/framework/preact/reference/type-aliases/AnyUseSuspenseQueryOptions.md
+++ b/docs/framework/preact/reference/type-aliases/AnyUseSuspenseQueryOptions.md
@@ -7,4 +7,4 @@ title: AnyUseSuspenseQueryOptions
 type AnyUseSuspenseQueryOptions = UseSuspenseQueryOptions<any, any, any, any>;
 ```
 
-Defined in: [preact-query/src/types.ts:111](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L111)
+Defined in: [preact-query/src/types.ts:117](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L117)
diff --git a/docs/framework/preact/reference/type-aliases/DefinedInitialDataInfiniteOptions.md b/docs/framework/preact/reference/type-aliases/DefinedInitialDataInfiniteOptions.md
index 38bd4b91fad..c82ed9d6886 100644
--- a/docs/framework/preact/reference/type-aliases/DefinedInitialDataInfiniteOptions.md
+++ b/docs/framework/preact/reference/type-aliases/DefinedInitialDataInfiniteOptions.md
@@ -7,7 +7,7 @@ title: DefinedInitialDataInfiniteOptions
 type DefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> = UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & object;
 ```
 
-Defined in: [preact-query/src/infiniteQueryOptions.ts:57](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L57)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:68](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L68)
 
 ## Type Declaration
 
@@ -20,6 +20,12 @@ initialData:
   | undefined;
 ```
 
+If set, this value will be used as the initial data for the query cache (as long as the query hasn't been
+created or cached yet). If set to a function, the function will be called **once** during the shared/root
+query initialization, and be expected to synchronously return the initial data. Initial data is
+considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the
+cache.
+
 ## Type Parameters
 
 ### TQueryFnData
diff --git a/docs/framework/preact/reference/type-aliases/DefinedInitialDataOptions.md b/docs/framework/preact/reference/type-aliases/DefinedInitialDataOptions.md
index d91681471c8..e0f93e4fb02 100644
--- a/docs/framework/preact/reference/type-aliases/DefinedInitialDataOptions.md
+++ b/docs/framework/preact/reference/type-aliases/DefinedInitialDataOptions.md
@@ -7,7 +7,7 @@ title: DefinedInitialDataOptions
 type DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey> = Omit<UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>, "queryFn"> & object;
 ```
 
-Defined in: [preact-query/src/queryOptions.ts:41](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L41)
+Defined in: [preact-query/src/queryOptions.ts:52](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L52)
 
 ## Type Declaration
 
@@ -19,6 +19,12 @@ initialData:
 | () => NonUndefinedGuard<TQueryFnData>;
 ```
 
+If set, this value will be used as the initial data for the query cache (as long as the query hasn't been
+created or cached yet). If set to a function, the function will be called **once** during the shared/root
+query initialization, and be expected to synchronously return the initial data. Initial data is
+considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the
+cache.
+
 ### queryFn?
 
 ```ts
diff --git a/docs/framework/preact/reference/type-aliases/DefinedUseInfiniteQueryResult.md b/docs/framework/preact/reference/type-aliases/DefinedUseInfiniteQueryResult.md
index d822ef4aed4..f0afce9d8dc 100644
--- a/docs/framework/preact/reference/type-aliases/DefinedUseInfiniteQueryResult.md
+++ b/docs/framework/preact/reference/type-aliases/DefinedUseInfiniteQueryResult.md
@@ -7,7 +7,7 @@ title: DefinedUseInfiniteQueryResult
 type DefinedUseInfiniteQueryResult<TData, TError> = DefinedInfiniteQueryObserverResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/types.ts:214](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L214)
+Defined in: [preact-query/src/types.ts:228](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L228)
 
 ## Type Parameters
 
diff --git a/docs/framework/preact/reference/type-aliases/DefinedUseQueryResult.md b/docs/framework/preact/reference/type-aliases/DefinedUseQueryResult.md
index b49de08fc70..b8739df6a31 100644
--- a/docs/framework/preact/reference/type-aliases/DefinedUseQueryResult.md
+++ b/docs/framework/preact/reference/type-aliases/DefinedUseQueryResult.md
@@ -7,7 +7,7 @@ title: DefinedUseQueryResult
 type DefinedUseQueryResult<TData, TError> = DefinedQueryObserverResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/types.ts:204](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L204)
+Defined in: [preact-query/src/types.ts:218](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L218)
 
 ## Type Parameters
 
diff --git a/docs/framework/preact/reference/type-aliases/UndefinedInitialDataInfiniteOptions.md b/docs/framework/preact/reference/type-aliases/UndefinedInitialDataInfiniteOptions.md
index 74d4863c67a..a36016349f2 100644
--- a/docs/framework/preact/reference/type-aliases/UndefinedInitialDataInfiniteOptions.md
+++ b/docs/framework/preact/reference/type-aliases/UndefinedInitialDataInfiniteOptions.md
@@ -19,6 +19,12 @@ optional initialData:
 | InitialDataFunction<NonUndefinedGuard<InfiniteData<TQueryFnData, TPageParam>>>;
 ```
 
+If set, this value will be used as the initial data for the query cache (as long as the query hasn't been
+created or cached yet). If set to a function, the function will be called **once** during the shared/root
+query initialization, and be expected to synchronously return the initial data. Initial data is
+considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the
+cache.
+
 ## Type Parameters
 
 ### TQueryFnData
diff --git a/docs/framework/preact/reference/type-aliases/UndefinedInitialDataOptions.md b/docs/framework/preact/reference/type-aliases/UndefinedInitialDataOptions.md
index 97523af5117..6f6a4cae550 100644
--- a/docs/framework/preact/reference/type-aliases/UndefinedInitialDataOptions.md
+++ b/docs/framework/preact/reference/type-aliases/UndefinedInitialDataOptions.md
@@ -19,6 +19,12 @@ optional initialData:
 | NonUndefinedGuard<TQueryFnData>;
 ```
 
+If set, this value will be used as the initial data for the query cache (as long as the query hasn't been
+created or cached yet). If set to a function, the function will be called **once** during the shared/root
+query initialization, and be expected to synchronously return the initial data. Initial data is
+considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the
+cache.
+
 ## Type Parameters
 
 ### TQueryFnData
diff --git a/docs/framework/preact/reference/type-aliases/UnusedSkipTokenInfiniteOptions.md b/docs/framework/preact/reference/type-aliases/UnusedSkipTokenInfiniteOptions.md
index d5a6f8a4553..0fb50efbad3 100644
--- a/docs/framework/preact/reference/type-aliases/UnusedSkipTokenInfiniteOptions.md
+++ b/docs/framework/preact/reference/type-aliases/UnusedSkipTokenInfiniteOptions.md
@@ -7,7 +7,7 @@ title: UnusedSkipTokenInfiniteOptions
 type UnusedSkipTokenInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> = OmitKeyof<UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, "queryFn"> & object;
 ```
 
-Defined in: [preact-query/src/infiniteQueryOptions.ts:35](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L35)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:42](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L42)
 
 ## Type Declaration
 
@@ -17,6 +17,9 @@ Defined in: [preact-query/src/infiniteQueryOptions.ts:35](https://github.com/Tan
 optional queryFn: Exclude<UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>["queryFn"], SkipToken | undefined>;
 ```
 
+`skipToken` is not allowed here — this overload is selected when no `initialData` is set, so the query
+always needs a function to actually run.
+
 ## Type Parameters
 
 ### TQueryFnData
diff --git a/docs/framework/preact/reference/type-aliases/UnusedSkipTokenOptions.md b/docs/framework/preact/reference/type-aliases/UnusedSkipTokenOptions.md
index f298f01c8c6..55bb73dd6f6 100644
--- a/docs/framework/preact/reference/type-aliases/UnusedSkipTokenOptions.md
+++ b/docs/framework/preact/reference/type-aliases/UnusedSkipTokenOptions.md
@@ -7,7 +7,7 @@ title: UnusedSkipTokenOptions
 type UnusedSkipTokenOptions<TQueryFnData, TError, TData, TQueryKey> = OmitKeyof<UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>, "queryFn"> & object;
 ```
 
-Defined in: [preact-query/src/queryOptions.ts:26](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L26)
+Defined in: [preact-query/src/queryOptions.ts:33](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L33)
 
 ## Type Declaration
 
@@ -17,6 +17,9 @@ Defined in: [preact-query/src/queryOptions.ts:26](https://github.com/TanStack/qu
 optional queryFn: Exclude<UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>["queryFn"], SkipToken | undefined>;
 ```
 
+`skipToken` is not allowed here — this overload is selected when no `initialData` is set, so the query
+always needs a function to actually run.
+
 ## Type Parameters
 
 ### TQueryFnData
diff --git a/docs/framework/preact/reference/type-aliases/UseBaseMutationResult.md b/docs/framework/preact/reference/type-aliases/UseBaseMutationResult.md
index 603ed6faf39..b7c3a4ba4d9 100644
--- a/docs/framework/preact/reference/type-aliases/UseBaseMutationResult.md
+++ b/docs/framework/preact/reference/type-aliases/UseBaseMutationResult.md
@@ -9,7 +9,7 @@ type UseBaseMutationResult<TData, TError, TVariables, TOnMutateResult> = Overrid
 }> & object;
 ```
 
-Defined in: [preact-query/src/types.ts:256](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L256)
+Defined in: [preact-query/src/types.ts:270](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L270)
 
 ## Type Declaration
 
@@ -19,6 +19,8 @@ Defined in: [preact-query/src/types.ts:256](https://github.com/TanStack/query/bl
 mutateAsync: UseMutateAsyncFunction<TData, TError, TVariables, TOnMutateResult>;
 ```
 
+Similar to `mutate`, but returns a promise which can be awaited.
+
 ## Type Parameters
 
 ### TData
diff --git a/docs/framework/preact/reference/type-aliases/UseBaseQueryResult.md b/docs/framework/preact/reference/type-aliases/UseBaseQueryResult.md
index b93999edcbf..b13cf83a324 100644
--- a/docs/framework/preact/reference/type-aliases/UseBaseQueryResult.md
+++ b/docs/framework/preact/reference/type-aliases/UseBaseQueryResult.md
@@ -7,7 +7,7 @@ title: UseBaseQueryResult
 type UseBaseQueryResult<TData, TError> = QueryObserverResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/types.ts:186](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L186)
+Defined in: [preact-query/src/types.ts:200](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L200)
 
 ## Type Parameters
 
diff --git a/docs/framework/preact/reference/type-aliases/UseInfiniteQueryResult.md b/docs/framework/preact/reference/type-aliases/UseInfiniteQueryResult.md
index a0a7cfe492d..8b8e7203c04 100644
--- a/docs/framework/preact/reference/type-aliases/UseInfiniteQueryResult.md
+++ b/docs/framework/preact/reference/type-aliases/UseInfiniteQueryResult.md
@@ -7,7 +7,7 @@ title: UseInfiniteQueryResult
 type UseInfiniteQueryResult<TData, TError> = InfiniteQueryObserverResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/types.ts:209](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L209)
+Defined in: [preact-query/src/types.ts:223](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L223)
 
 ## Type Parameters
 
diff --git a/docs/framework/preact/reference/type-aliases/UseMutateAsyncFunction.md b/docs/framework/preact/reference/type-aliases/UseMutateAsyncFunction.md
index 3e3b26c24f1..3d41f5d6c33 100644
--- a/docs/framework/preact/reference/type-aliases/UseMutateAsyncFunction.md
+++ b/docs/framework/preact/reference/type-aliases/UseMutateAsyncFunction.md
@@ -7,7 +7,7 @@ title: UseMutateAsyncFunction
 type UseMutateAsyncFunction<TData, TError, TVariables, TOnMutateResult> = MutateFunction<TData, TError, TVariables, TOnMutateResult>;
 ```
 
-Defined in: [preact-query/src/types.ts:249](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L249)
+Defined in: [preact-query/src/types.ts:263](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L263)
 
 ## Type Parameters
 
diff --git a/docs/framework/preact/reference/type-aliases/UseMutateFunction.md b/docs/framework/preact/reference/type-aliases/UseMutateFunction.md
index d38ea3e0aab..6dc8e6734eb 100644
--- a/docs/framework/preact/reference/type-aliases/UseMutateFunction.md
+++ b/docs/framework/preact/reference/type-aliases/UseMutateFunction.md
@@ -7,7 +7,7 @@ title: UseMutateFunction
 type UseMutateFunction<TData, TError, TVariables, TOnMutateResult> = (...args) => void;
 ```
 
-Defined in: [preact-query/src/types.ts:238](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L238)
+Defined in: [preact-query/src/types.ts:252](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L252)
 
 ## Type Parameters
 
diff --git a/docs/framework/preact/reference/type-aliases/UseMutationResult.md b/docs/framework/preact/reference/type-aliases/UseMutationResult.md
index b84dd9fe85a..b6002b9a8d7 100644
--- a/docs/framework/preact/reference/type-aliases/UseMutationResult.md
+++ b/docs/framework/preact/reference/type-aliases/UseMutationResult.md
@@ -7,7 +7,7 @@ title: UseMutationResult
 type UseMutationResult<TData, TError, TVariables, TOnMutateResult> = UseBaseMutationResult<TData, TError, TVariables, TOnMutateResult>;
 ```
 
-Defined in: [preact-query/src/types.ts:273](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L273)
+Defined in: [preact-query/src/types.ts:290](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L290)
 
 ## Type Parameters
 
diff --git a/docs/framework/preact/reference/type-aliases/UsePrefetchInfiniteQueryOptions.md b/docs/framework/preact/reference/type-aliases/UsePrefetchInfiniteQueryOptions.md
index a8a5e15acc4..8680dc32223 100644
--- a/docs/framework/preact/reference/type-aliases/UsePrefetchInfiniteQueryOptions.md
+++ b/docs/framework/preact/reference/type-aliases/UsePrefetchInfiniteQueryOptions.md
@@ -7,7 +7,7 @@ title: UsePrefetchInfiniteQueryOptions
 type UsePrefetchInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> = DistributiveOmit<InfiniteQueryExecuteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, "queryFn"> & object;
 ```
 
-Defined in: [preact-query/src/types.ts:72](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L72)
+Defined in: [preact-query/src/types.ts:75](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L75)
 
 ## Type Declaration
 
@@ -17,6 +17,8 @@ Defined in: [preact-query/src/types.ts:72](https://github.com/TanStack/query/blo
 optional queryFn: Exclude<InfiniteQueryExecuteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>["queryFn"], SkipToken>;
 ```
 
+`skipToken` is not allowed here — a prefetch always needs a query function to actually run.
+
 ## Type Parameters
 
 ### TQueryFnData
diff --git a/docs/framework/preact/reference/type-aliases/UsePrefetchQueryOptions.md b/docs/framework/preact/reference/type-aliases/UsePrefetchQueryOptions.md
index 12023e9d75e..f147535ebd3 100644
--- a/docs/framework/preact/reference/type-aliases/UsePrefetchQueryOptions.md
+++ b/docs/framework/preact/reference/type-aliases/UsePrefetchQueryOptions.md
@@ -17,6 +17,8 @@ Defined in: [preact-query/src/types.ts:50](https://github.com/TanStack/query/blo
 optional queryFn: Exclude<QueryExecuteOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey>["queryFn"], SkipToken>;
 ```
 
+`skipToken` is not allowed here — a prefetch always needs a query function to actually run.
+
 ## Type Parameters
 
 ### TQueryFnData
diff --git a/docs/framework/preact/reference/type-aliases/UseQueryResult.md b/docs/framework/preact/reference/type-aliases/UseQueryResult.md
index 8c3a3f7e31e..b46d463da25 100644
--- a/docs/framework/preact/reference/type-aliases/UseQueryResult.md
+++ b/docs/framework/preact/reference/type-aliases/UseQueryResult.md
@@ -7,7 +7,7 @@ title: UseQueryResult
 type UseQueryResult<TData, TError> = UseBaseQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/types.ts:191](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L191)
+Defined in: [preact-query/src/types.ts:205](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L205)
 
 ## Type Parameters
 
diff --git a/docs/framework/preact/reference/type-aliases/UseSuspenseInfiniteQueryResult.md b/docs/framework/preact/reference/type-aliases/UseSuspenseInfiniteQueryResult.md
index 5f5db5b1bd7..f285e10e9dd 100644
--- a/docs/framework/preact/reference/type-aliases/UseSuspenseInfiniteQueryResult.md
+++ b/docs/framework/preact/reference/type-aliases/UseSuspenseInfiniteQueryResult.md
@@ -7,7 +7,7 @@ title: UseSuspenseInfiniteQueryResult
 type UseSuspenseInfiniteQueryResult<TData, TError> = OmitKeyof<DefinedInfiniteQueryObserverResult<TData, TError>, "isPlaceholderData">;
 ```
 
-Defined in: [preact-query/src/types.ts:219](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L219)
+Defined in: [preact-query/src/types.ts:233](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L233)
 
 ## Type Parameters
 
diff --git a/docs/framework/preact/reference/type-aliases/UseSuspenseQueryResult.md b/docs/framework/preact/reference/type-aliases/UseSuspenseQueryResult.md
index 42320c3f6f7..aa6f5b6bbda 100644
--- a/docs/framework/preact/reference/type-aliases/UseSuspenseQueryResult.md
+++ b/docs/framework/preact/reference/type-aliases/UseSuspenseQueryResult.md
@@ -7,7 +7,7 @@ title: UseSuspenseQueryResult
 type UseSuspenseQueryResult<TData, TError> = DistributiveOmit<DefinedQueryObserverResult<TData, TError>, "isPlaceholderData">;
 ```
 
-Defined in: [preact-query/src/types.ts:196](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L196)
+Defined in: [preact-query/src/types.ts:210](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L210)
 
 ## Type Parameters
 
diff --git a/docs/framework/preact/reference/variables/IsRestoringProvider.md b/docs/framework/preact/reference/variables/IsRestoringProvider.md
index e7844f01c88..49ebbe9770a 100644
--- a/docs/framework/preact/reference/variables/IsRestoringProvider.md
+++ b/docs/framework/preact/reference/variables/IsRestoringProvider.md
@@ -7,4 +7,4 @@ title: IsRestoringProvider
 const IsRestoringProvider: Provider<boolean> = IsRestoringContext.Provider;
 ```
 
-Defined in: [preact-query/src/IsRestoringProvider.ts:7](https://github.com/TanStack/query/blob/main/packages/preact-query/src/IsRestoringProvider.ts#L7)
+Defined in: [preact-query/src/IsRestoringProvider.ts:12](https://github.com/TanStack/query/blob/main/packages/preact-query/src/IsRestoringProvider.ts#L12)
diff --git a/packages/preact-query/src/IsRestoringProvider.ts b/packages/preact-query/src/IsRestoringProvider.ts
index a412ada08d9..35ef669c77f 100644
--- a/packages/preact-query/src/IsRestoringProvider.ts
+++ b/packages/preact-query/src/IsRestoringProvider.ts
@@ -3,5 +3,10 @@ import { useContext } from 'preact/hooks'
 
 const IsRestoringContext = createContext(false)
 
+/**
+ * If you are using `PersistQueryClientProvider`, you can also use the `useIsRestoring` hook alongside it to
+ * check if a restore is currently in progress. `useQuery` and friends also check this internally to avoid
+ * race conditions between the restore and mounting queries.
+ */
 export const useIsRestoring = () => useContext(IsRestoringContext)
 export const IsRestoringProvider = IsRestoringContext.Provider
diff --git a/packages/preact-query/src/infiniteQueryOptions.ts b/packages/preact-query/src/infiniteQueryOptions.ts
index 5965ac33fad..f5f4ac4430b 100644
--- a/packages/preact-query/src/infiniteQueryOptions.ts
+++ b/packages/preact-query/src/infiniteQueryOptions.ts
@@ -24,6 +24,13 @@ export type UndefinedInitialDataInfiniteOptions<
   TQueryKey,
   TPageParam
 > & {
+  /**
+   * If set, this value will be used as the initial data for the query cache (as long as the query hasn't been
+   * created or cached yet). If set to a function, the function will be called **once** during the shared/root
+   * query initialization, and be expected to synchronously return the initial data. Initial data is
+   * considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the
+   * cache.
+   */
   initialData?:
     | undefined
     | NonUndefinedGuard<InfiniteData<TQueryFnData, TPageParam>>
@@ -42,6 +49,10 @@ export type UnusedSkipTokenInfiniteOptions<
   UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>,
   'queryFn'
 > & {
+  /**
+   * `skipToken` is not allowed here — this overload is selected when no `initialData` is set, so the query
+   * always needs a function to actually run.
+   */
   queryFn?: Exclude<
     UseInfiniteQueryOptions<
       TQueryFnData,
@@ -67,6 +78,13 @@ export type DefinedInitialDataInfiniteOptions<
   TQueryKey,
   TPageParam
 > & {
+  /**
+   * If set, this value will be used as the initial data for the query cache (as long as the query hasn't been
+   * created or cached yet). If set to a function, the function will be called **once** during the shared/root
+   * query initialization, and be expected to synchronously return the initial data. Initial data is
+   * considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the
+   * cache.
+   */
   initialData:
     | NonUndefinedGuard<InfiniteData<TQueryFnData, TPageParam>>
     | (() => NonUndefinedGuard<InfiniteData<TQueryFnData, TPageParam>>)
diff --git a/packages/preact-query/src/queryOptions.ts b/packages/preact-query/src/queryOptions.ts
index ca9c7c466e5..d869e1e7945 100644
--- a/packages/preact-query/src/queryOptions.ts
+++ b/packages/preact-query/src/queryOptions.ts
@@ -17,6 +17,13 @@ export type UndefinedInitialDataOptions<
   TData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
 > = UseQueryOptions<TQueryFnData, TError, TData, TQueryKey> & {
+  /**
+   * If set, this value will be used as the initial data for the query cache (as long as the query hasn't been
+   * created or cached yet). If set to a function, the function will be called **once** during the shared/root
+   * query initialization, and be expected to synchronously return the initial data. Initial data is
+   * considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the
+   * cache.
+   */
   initialData?:
     | undefined
     | InitialDataFunction<NonUndefinedGuard<TQueryFnData>>
@@ -32,6 +39,10 @@ export type UnusedSkipTokenOptions<
   UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
   'queryFn'
 > & {
+  /**
+   * `skipToken` is not allowed here — this overload is selected when no `initialData` is set, so the query
+   * always needs a function to actually run.
+   */
   queryFn?: Exclude<
     UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>['queryFn'],
     SkipToken | undefined
@@ -44,6 +55,13 @@ export type DefinedInitialDataOptions<
   TData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
 > = Omit<UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>, 'queryFn'> & {
+  /**
+   * If set, this value will be used as the initial data for the query cache (as long as the query hasn't been
+   * created or cached yet). If set to a function, the function will be called **once** during the shared/root
+   * query initialization, and be expected to synchronously return the initial data. Initial data is
+   * considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the
+   * cache.
+   */
   initialData:
     | NonUndefinedGuard<TQueryFnData>
     | (() => NonUndefinedGuard<TQueryFnData>)
diff --git a/packages/preact-query/src/types.ts b/packages/preact-query/src/types.ts
index 9a9b646e9e8..1c85505211b 100644
--- a/packages/preact-query/src/types.ts
+++ b/packages/preact-query/src/types.ts
@@ -57,6 +57,9 @@ export type UsePrefetchQueryOptions<
   QueryExecuteOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>,
   'queryFn'
 > & {
+  /**
+   * `skipToken` is not allowed here — a prefetch always needs a query function to actually run.
+   */
   queryFn?: Exclude<
     QueryExecuteOptions<
       TQueryFnData,
@@ -85,6 +88,9 @@ export type UsePrefetchInfiniteQueryOptions<
   >,
   'queryFn'
 > & {
+  /**
+   * `skipToken` is not allowed here — a prefetch always needs a query function to actually run.
+   */
   queryFn?: Exclude<
     InfiniteQueryExecuteOptions<
       TQueryFnData,
@@ -123,6 +129,10 @@ export interface UseSuspenseQueryOptions<
   UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
   'queryFn' | 'enabled' | 'throwOnError' | 'placeholderData'
 > {
+  /**
+   * `skipToken` is not allowed here — Suspense hooks cannot render a "disabled" state, so a query function
+   * must always be provided.
+   */
   queryFn?: Exclude<
     UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>['queryFn'],
     SkipToken
@@ -171,6 +181,10 @@ export interface UseSuspenseInfiniteQueryOptions<
   UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>,
   'queryFn' | 'enabled' | 'throwOnError' | 'placeholderData'
 > {
+  /**
+   * `skipToken` is not allowed here — Suspense hooks cannot render a "disabled" state, so a query function
+   * must always be provided.
+   */
   queryFn?: Exclude<
     UseInfiniteQueryOptions<
       TQueryFnData,
@@ -262,6 +276,9 @@ export type UseBaseMutationResult<
   MutationObserverResult<TData, TError, TVariables, TOnMutateResult>,
   { mutate: UseMutateFunction<TData, TError, TVariables, TOnMutateResult> }
 > & {
+  /**
+   * Similar to `mutate`, but returns a promise which can be awaited.
+   */
   mutateAsync: UseMutateAsyncFunction<
     TData,
     TError,

From a3486e47a470269650c10b1218a239490ccd71af Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Tue, 25 Aug 2026 01:15:54 +0900
Subject: [PATCH 11/28] docs(preact-query): fill in empty Returns sections for
 hooks and options builders

---
 .../reference/functions/QueryClientProvider.md       |  2 +-
 .../reference/functions/QueryErrorResetBoundary.md   |  2 +-
 .../reference/functions/infiniteQueryOptions.md      | 12 +++++++++---
 .../preact/reference/functions/queryOptions.md       | 12 +++++++++---
 .../preact/reference/functions/useIsRestoring.md     |  4 +++-
 .../reference/functions/usePrefetchInfiniteQuery.md  |  4 +++-
 .../preact/reference/functions/usePrefetchQuery.md   |  4 +++-
 .../preact/reference/functions/useQueryClient.md     |  4 +++-
 .../functions/useQueryErrorResetBoundary.md          |  4 +++-
 .../interfaces/QueryErrorResetBoundaryProps.md       |  4 ++--
 .../type-aliases/QueryClientProviderProps.md         |  6 +++---
 .../type-aliases/QueryErrorResetBoundaryFunction.md  |  2 +-
 .../reference/variables/IsRestoringProvider.md       |  2 +-
 packages/preact-query/src/IsRestoringProvider.ts     |  2 ++
 packages/preact-query/src/QueryClientProvider.tsx    |  1 +
 .../preact-query/src/QueryErrorResetBoundary.tsx     | 11 +++++++++++
 packages/preact-query/src/infiniteQueryOptions.ts    |  6 ++++++
 packages/preact-query/src/queryOptions.ts            |  6 ++++++
 .../preact-query/src/usePrefetchInfiniteQuery.tsx    |  2 ++
 packages/preact-query/src/usePrefetchQuery.tsx       |  2 ++
 20 files changed, 72 insertions(+), 20 deletions(-)

diff --git a/docs/framework/preact/reference/functions/QueryClientProvider.md b/docs/framework/preact/reference/functions/QueryClientProvider.md
index b680a16f538..d7c5423ce0f 100644
--- a/docs/framework/preact/reference/functions/QueryClientProvider.md
+++ b/docs/framework/preact/reference/functions/QueryClientProvider.md
@@ -7,7 +7,7 @@ title: QueryClientProvider
 function QueryClientProvider(__namedParameters): VNode;
 ```
 
-Defined in: [preact-query/src/QueryClientProvider.tsx:54](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryClientProvider.tsx#L54)
+Defined in: [preact-query/src/QueryClientProvider.tsx:55](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryClientProvider.tsx#L55)
 
 Use the `QueryClientProvider` component to connect and provide a `QueryClient` to your application.
 
diff --git a/docs/framework/preact/reference/functions/QueryErrorResetBoundary.md b/docs/framework/preact/reference/functions/QueryErrorResetBoundary.md
index acba933862c..3e6c8945dfd 100644
--- a/docs/framework/preact/reference/functions/QueryErrorResetBoundary.md
+++ b/docs/framework/preact/reference/functions/QueryErrorResetBoundary.md
@@ -7,7 +7,7 @@ title: QueryErrorResetBoundary
 function QueryErrorResetBoundary(__namedParameters): Element;
 ```
 
-Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:116](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L116)
+Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:127](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L127)
 
 When using **suspense** or **throwOnError** in your queries, you need a way to let queries know that you want to
 try again when re-rendering after some error occurred. With the `QueryErrorResetBoundary` component you can
diff --git a/docs/framework/preact/reference/functions/infiniteQueryOptions.md b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
index d251f171a68..6bed19d76ce 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:133](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L133)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:135](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L135)
 
 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`.
@@ -45,6 +45,8 @@ These options can be shared across hooks and imperative APIs such as `queryClien
 
 ### Returns
 
+The same options object, typed so that `queryKey` carries the inferred data type.
+
 ### Examples
 
 ```tsx
@@ -85,7 +87,7 @@ queryClient.prefetchInfiniteQuery(commentsOptions(postId))
 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:195](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L195)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:199](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L199)
 
 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`.
@@ -121,6 +123,8 @@ These options can be shared across hooks and imperative APIs such as `queryClien
 
 ### Returns
 
+The same options object, typed so that `queryKey` carries the inferred data type.
+
 ### Examples
 
 ```tsx
@@ -161,7 +165,7 @@ queryClient.prefetchInfiniteQuery(commentsOptions(postId))
 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:257](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L257)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:263](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L263)
 
 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`.
@@ -197,6 +201,8 @@ These options can be shared across hooks and imperative APIs such as `queryClien
 
 ### Returns
 
+The same options object, typed so that `queryKey` carries the inferred data type.
+
 ### Examples
 
 ```tsx
diff --git a/docs/framework/preact/reference/functions/queryOptions.md b/docs/framework/preact/reference/functions/queryOptions.md
index abd77b8f5b1..5f57a8dce81 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:122](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L122)
+Defined in: [preact-query/src/queryOptions.ts:124](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L124)
 
 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
@@ -41,6 +41,8 @@ is the query key to generate options for.
 
 ### Returns
 
+The same options object, typed so that `queryKey` carries the inferred data type.
+
 ### Examples
 
 ```tsx
@@ -92,7 +94,7 @@ queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefi
 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:183](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L183)
+Defined in: [preact-query/src/queryOptions.ts:187](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L187)
 
 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,6 +126,8 @@ is the query key to generate options for.
 
 ### Returns
 
+The same options object, typed so that `queryKey` carries the inferred data type.
+
 ### Examples
 
 ```tsx
@@ -175,7 +179,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:244](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L244)
+Defined in: [preact-query/src/queryOptions.ts:250](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L250)
 
 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
@@ -207,6 +211,8 @@ is the query key to generate options for.
 
 ### Returns
 
+The same options object, typed so that `queryKey` carries the inferred data type.
+
 ### Examples
 
 ```tsx
diff --git a/docs/framework/preact/reference/functions/useIsRestoring.md b/docs/framework/preact/reference/functions/useIsRestoring.md
index 328d641ab52..e81909e2221 100644
--- a/docs/framework/preact/reference/functions/useIsRestoring.md
+++ b/docs/framework/preact/reference/functions/useIsRestoring.md
@@ -7,7 +7,7 @@ title: useIsRestoring
 function useIsRestoring(): boolean;
 ```
 
-Defined in: [preact-query/src/IsRestoringProvider.ts:11](https://github.com/TanStack/query/blob/main/packages/preact-query/src/IsRestoringProvider.ts#L11)
+Defined in: [preact-query/src/IsRestoringProvider.ts:13](https://github.com/TanStack/query/blob/main/packages/preact-query/src/IsRestoringProvider.ts#L13)
 
 If you are using `PersistQueryClientProvider`, you can also use the `useIsRestoring` hook alongside it to
 check if a restore is currently in progress. `useQuery` and friends also check this internally to avoid
@@ -16,3 +16,5 @@ race conditions between the restore and mounting queries.
 ## Returns
 
 `boolean`
+
+`true` while a persisted client is being restored, `false` otherwise.
diff --git a/docs/framework/preact/reference/functions/usePrefetchInfiniteQuery.md b/docs/framework/preact/reference/functions/usePrefetchInfiniteQuery.md
index 6eed4cddc2d..12d8e50a30e 100644
--- a/docs/framework/preact/reference/functions/usePrefetchInfiniteQuery.md
+++ b/docs/framework/preact/reference/functions/usePrefetchInfiniteQuery.md
@@ -7,7 +7,7 @@ title: usePrefetchInfiniteQuery
 function usePrefetchInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): void;
 ```
 
-Defined in: [preact-query/src/usePrefetchInfiniteQuery.tsx:41](https://github.com/TanStack/query/blob/main/packages/preact-query/src/usePrefetchInfiniteQuery.tsx#L41)
+Defined in: [preact-query/src/usePrefetchInfiniteQuery.tsx:43](https://github.com/TanStack/query/blob/main/packages/preact-query/src/usePrefetchInfiniteQuery.tsx#L43)
 
 `usePrefetchInfiniteQuery` does not return anything, it should be used just to fire a prefetch during render,
 before a suspense boundary that wraps a component that uses `useSuspenseInfiniteQuery`. You can pass
@@ -56,6 +56,8 @@ available.
 
 `void`
 
+`void` — nothing is returned.
+
 ## Example
 
 ```tsx
diff --git a/docs/framework/preact/reference/functions/usePrefetchQuery.md b/docs/framework/preact/reference/functions/usePrefetchQuery.md
index a2594d6ce4f..9f16c64bd7c 100644
--- a/docs/framework/preact/reference/functions/usePrefetchQuery.md
+++ b/docs/framework/preact/reference/functions/usePrefetchQuery.md
@@ -7,7 +7,7 @@ title: usePrefetchQuery
 function usePrefetchQuery<TQueryFnData, TError, TData, TQueryData, TQueryKey>(options, queryClient?): void;
 ```
 
-Defined in: [preact-query/src/usePrefetchQuery.tsx:33](https://github.com/TanStack/query/blob/main/packages/preact-query/src/usePrefetchQuery.tsx#L33)
+Defined in: [preact-query/src/usePrefetchQuery.tsx:35](https://github.com/TanStack/query/blob/main/packages/preact-query/src/usePrefetchQuery.tsx#L35)
 
 `usePrefetchQuery` does not return anything, it should be used just to fire a prefetch during render, before
 a suspense boundary that wraps a component that uses `useSuspenseQuery`. You can pass everything to
@@ -50,6 +50,8 @@ a suspense boundary that wraps a component that uses `useSuspenseQuery`. You can
 
 `void`
 
+`void` — nothing is returned.
+
 ## Example
 
 ```tsx
diff --git a/docs/framework/preact/reference/functions/useQueryClient.md b/docs/framework/preact/reference/functions/useQueryClient.md
index dd4a572d39b..d750430a6f3 100644
--- a/docs/framework/preact/reference/functions/useQueryClient.md
+++ b/docs/framework/preact/reference/functions/useQueryClient.md
@@ -7,7 +7,7 @@ title: useQueryClient
 function useQueryClient(queryClient?): QueryClient;
 ```
 
-Defined in: [preact-query/src/QueryClientProvider.tsx:16](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryClientProvider.tsx#L16)
+Defined in: [preact-query/src/QueryClientProvider.tsx:17](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryClientProvider.tsx#L17)
 
 The `useQueryClient` hook returns the current `QueryClient` instance.
 
@@ -23,3 +23,5 @@ be used.
 ## Returns
 
 `QueryClient`
+
+The current `QueryClient` instance.
diff --git a/docs/framework/preact/reference/functions/useQueryErrorResetBoundary.md b/docs/framework/preact/reference/functions/useQueryErrorResetBoundary.md
index 62ebccdc088..eefa6c0eb6a 100644
--- a/docs/framework/preact/reference/functions/useQueryErrorResetBoundary.md
+++ b/docs/framework/preact/reference/functions/useQueryErrorResetBoundary.md
@@ -7,7 +7,7 @@ title: useQueryErrorResetBoundary
 function useQueryErrorResetBoundary(): QueryErrorResetBoundaryValue;
 ```
 
-Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:61](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L61)
+Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:72](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L72)
 
 This hook will reset any query errors within the closest `QueryErrorResetBoundary`. If there is no boundary
 defined it will reset them globally.
@@ -16,6 +16,8 @@ defined it will reset them globally.
 
 `QueryErrorResetBoundaryValue`
 
+The boundary's QueryErrorResetBoundaryValue.
+
 ## Example
 
 ```tsx
diff --git a/docs/framework/preact/reference/interfaces/QueryErrorResetBoundaryProps.md b/docs/framework/preact/reference/interfaces/QueryErrorResetBoundaryProps.md
index dab7497f1cf..4dc3ea7129b 100644
--- a/docs/framework/preact/reference/interfaces/QueryErrorResetBoundaryProps.md
+++ b/docs/framework/preact/reference/interfaces/QueryErrorResetBoundaryProps.md
@@ -3,7 +3,7 @@ id: QueryErrorResetBoundaryProps
 title: QueryErrorResetBoundaryProps
 ---
 
-Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:70](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L70)
+Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:81](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L81)
 
 ## Properties
 
@@ -15,4 +15,4 @@ children:
   | QueryErrorResetBoundaryFunction;
 ```
 
-Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:71](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L71)
+Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:82](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L82)
diff --git a/docs/framework/preact/reference/type-aliases/QueryClientProviderProps.md b/docs/framework/preact/reference/type-aliases/QueryClientProviderProps.md
index d13af4859ca..07eb00de464 100644
--- a/docs/framework/preact/reference/type-aliases/QueryClientProviderProps.md
+++ b/docs/framework/preact/reference/type-aliases/QueryClientProviderProps.md
@@ -7,7 +7,7 @@ title: QueryClientProviderProps
 type QueryClientProviderProps = object;
 ```
 
-Defined in: [preact-query/src/QueryClientProvider.tsx:30](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryClientProvider.tsx#L30)
+Defined in: [preact-query/src/QueryClientProvider.tsx:31](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryClientProvider.tsx#L31)
 
 ## Properties
 
@@ -17,7 +17,7 @@ Defined in: [preact-query/src/QueryClientProvider.tsx:30](https://github.com/Tan
 optional children: ComponentChildren;
 ```
 
-Defined in: [preact-query/src/QueryClientProvider.tsx:37](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryClientProvider.tsx#L37)
+Defined in: [preact-query/src/QueryClientProvider.tsx:38](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryClientProvider.tsx#L38)
 
 ***
 
@@ -27,7 +27,7 @@ Defined in: [preact-query/src/QueryClientProvider.tsx:37](https://github.com/Tan
 client: QueryClient;
 ```
 
-Defined in: [preact-query/src/QueryClientProvider.tsx:36](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryClientProvider.tsx#L36)
+Defined in: [preact-query/src/QueryClientProvider.tsx:37](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryClientProvider.tsx#L37)
 
 **Required**
 
diff --git a/docs/framework/preact/reference/type-aliases/QueryErrorResetBoundaryFunction.md b/docs/framework/preact/reference/type-aliases/QueryErrorResetBoundaryFunction.md
index f44fc3d5f75..048dac086e2 100644
--- a/docs/framework/preact/reference/type-aliases/QueryErrorResetBoundaryFunction.md
+++ b/docs/framework/preact/reference/type-aliases/QueryErrorResetBoundaryFunction.md
@@ -7,7 +7,7 @@ title: QueryErrorResetBoundaryFunction
 type QueryErrorResetBoundaryFunction = (value) => ComponentChildren;
 ```
 
-Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:66](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L66)
+Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:77](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L77)
 
 ## Parameters
 
diff --git a/docs/framework/preact/reference/variables/IsRestoringProvider.md b/docs/framework/preact/reference/variables/IsRestoringProvider.md
index 49ebbe9770a..895ae6eb25c 100644
--- a/docs/framework/preact/reference/variables/IsRestoringProvider.md
+++ b/docs/framework/preact/reference/variables/IsRestoringProvider.md
@@ -7,4 +7,4 @@ title: IsRestoringProvider
 const IsRestoringProvider: Provider<boolean> = IsRestoringContext.Provider;
 ```
 
-Defined in: [preact-query/src/IsRestoringProvider.ts:12](https://github.com/TanStack/query/blob/main/packages/preact-query/src/IsRestoringProvider.ts#L12)
+Defined in: [preact-query/src/IsRestoringProvider.ts:14](https://github.com/TanStack/query/blob/main/packages/preact-query/src/IsRestoringProvider.ts#L14)
diff --git a/packages/preact-query/src/IsRestoringProvider.ts b/packages/preact-query/src/IsRestoringProvider.ts
index 35ef669c77f..84d55326a1d 100644
--- a/packages/preact-query/src/IsRestoringProvider.ts
+++ b/packages/preact-query/src/IsRestoringProvider.ts
@@ -7,6 +7,8 @@ const IsRestoringContext = createContext(false)
  * If you are using `PersistQueryClientProvider`, you can also use the `useIsRestoring` hook alongside it to
  * check if a restore is currently in progress. `useQuery` and friends also check this internally to avoid
  * race conditions between the restore and mounting queries.
+ *
+ * @returns `true` while a persisted client is being restored, `false` otherwise.
  */
 export const useIsRestoring = () => useContext(IsRestoringContext)
 export const IsRestoringProvider = IsRestoringContext.Provider
diff --git a/packages/preact-query/src/QueryClientProvider.tsx b/packages/preact-query/src/QueryClientProvider.tsx
index 9d438e3fba0..eb1ad3d3fe6 100644
--- a/packages/preact-query/src/QueryClientProvider.tsx
+++ b/packages/preact-query/src/QueryClientProvider.tsx
@@ -12,6 +12,7 @@ export const QueryClientContext = createContext<QueryClient | undefined>(
  *
  * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
  * be used.
+ * @returns The current `QueryClient` instance.
  */
 export const useQueryClient = (queryClient?: QueryClient) => {
   const client = useContext(QueryClientContext)
diff --git a/packages/preact-query/src/QueryErrorResetBoundary.tsx b/packages/preact-query/src/QueryErrorResetBoundary.tsx
index f3329d6790a..c41a943e531 100644
--- a/packages/preact-query/src/QueryErrorResetBoundary.tsx
+++ b/packages/preact-query/src/QueryErrorResetBoundary.tsx
@@ -8,8 +8,17 @@ export type QueryErrorIsResetFunction = () => boolean
 export type QueryErrorClearResetFunction = () => void
 
 export interface QueryErrorResetBoundaryValue {
+  /**
+   * Clears the reset state, so queries know not to try again until the boundary is reset again.
+   */
   clearReset: QueryErrorClearResetFunction
+  /**
+   * Returns whether the boundary has been reset and not yet cleared.
+   */
   isReset: QueryErrorIsResetFunction
+  /**
+   * Resets any query errors within the boundary, so queries know they can try again.
+   */
   reset: QueryErrorResetFunction
 }
 
@@ -36,6 +45,8 @@ const QueryErrorResetBoundaryContext = createContext(createValue())
  * This hook will reset any query errors within the closest `QueryErrorResetBoundary`. If there is no boundary
  * defined it will reset them globally.
  *
+ * @returns The boundary's {@link QueryErrorResetBoundaryValue}.
+ *
  * @example
  * ```tsx
  * import { useErrorBoundary } from 'preact/hooks'
diff --git a/packages/preact-query/src/infiniteQueryOptions.ts b/packages/preact-query/src/infiniteQueryOptions.ts
index f5f4ac4430b..c74a6aa0193 100644
--- a/packages/preact-query/src/infiniteQueryOptions.ts
+++ b/packages/preact-query/src/infiniteQueryOptions.ts
@@ -96,6 +96,8 @@ export type DefinedInitialDataInfiniteOptions<
  * These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
  * `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.
+ *
  * @example
  * ```tsx
  * import { infiniteQueryOptions } from '@tanstack/preact-query'
@@ -158,6 +160,8 @@ export function infiniteQueryOptions<
  * These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
  * `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.
+ *
  * @example
  * ```tsx
  * import { infiniteQueryOptions } from '@tanstack/preact-query'
@@ -220,6 +224,8 @@ export function infiniteQueryOptions<
  * These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
  * `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.
+ *
  * @example
  * ```tsx
  * import { infiniteQueryOptions } from '@tanstack/preact-query'
diff --git a/packages/preact-query/src/queryOptions.ts b/packages/preact-query/src/queryOptions.ts
index d869e1e7945..77e74201264 100644
--- a/packages/preact-query/src/queryOptions.ts
+++ b/packages/preact-query/src/queryOptions.ts
@@ -73,6 +73,8 @@ export type DefinedInitialDataOptions<
  * be shared across hooks and imperative APIs such as `queryClient.query`. `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.
+ *
  * @example
  * ```tsx
  * import { queryOptions } from '@tanstack/preact-query'
@@ -134,6 +136,8 @@ export function queryOptions<
  * be shared across hooks and imperative APIs such as `queryClient.query`. `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.
+ *
  * @example
  * ```tsx
  * import { queryOptions } from '@tanstack/preact-query'
@@ -195,6 +199,8 @@ export function queryOptions<
  * be shared across hooks and imperative APIs such as `queryClient.query`. `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.
+ *
  * @example
  * ```tsx
  * import { queryOptions } from '@tanstack/preact-query'
diff --git a/packages/preact-query/src/usePrefetchInfiniteQuery.tsx b/packages/preact-query/src/usePrefetchInfiniteQuery.tsx
index f00ffdc2683..b4bc5e6ad69 100644
--- a/packages/preact-query/src/usePrefetchInfiniteQuery.tsx
+++ b/packages/preact-query/src/usePrefetchInfiniteQuery.tsx
@@ -16,6 +16,8 @@ import type { UsePrefetchInfiniteQueryOptions } from './types'
  * optional parameter to your query function. Return `undefined` or `null` to indicate there is no next page
  * available.
  *
+ * @returns `void` — nothing is returned.
+ *
  * @example
  * ```tsx
  * import { Suspense } from 'preact/compat'
diff --git a/packages/preact-query/src/usePrefetchQuery.tsx b/packages/preact-query/src/usePrefetchQuery.tsx
index 8dba5e851f8..893707e676e 100644
--- a/packages/preact-query/src/usePrefetchQuery.tsx
+++ b/packages/preact-query/src/usePrefetchQuery.tsx
@@ -10,6 +10,8 @@ import type { UsePrefetchQueryOptions } from './types'
  * `usePrefetchQuery` that you can pass to `queryClient.fetchQuery`, though `queryKey` is always required, and
  * `queryFn` is required unless a default query function has been defined.
  *
+ * @returns `void` — nothing is returned.
+ *
  * @example
  * ```tsx
  * import { Suspense } from 'preact/compat'

From b1dae6ab986ba2184b8dc005a3347de50dfed67e Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Tue, 25 Aug 2026 01:19:22 +0900
Subject: [PATCH 12/28] docs(preact-query): systematic sweep of generated pages
 for missing field descriptions and fix mismatched mutationOptions example

---
 .../reference/functions/mutationOptions.md     |  7 ++++---
 .../preact/reference/functions/queryOptions.md |  6 +++---
 .../reference/functions/useInfiniteQuery.md    | 14 +++++++++++---
 .../preact/reference/functions/useQuery.md     | 18 +++++++++++++++---
 .../type-aliases/DefinedInitialDataOptions.md  |  2 ++
 packages/preact-query/src/mutationOptions.ts   |  5 +++--
 packages/preact-query/src/queryOptions.ts      |  3 +++
 packages/preact-query/src/useInfiniteQuery.ts  |  6 ++++++
 packages/preact-query/src/useQuery.ts          |  9 +++++++++
 9 files changed, 56 insertions(+), 14 deletions(-)

diff --git a/docs/framework/preact/reference/functions/mutationOptions.md b/docs/framework/preact/reference/functions/mutationOptions.md
index e924ecf6710..4ee6d46c9c9 100644
--- a/docs/framework/preact/reference/functions/mutationOptions.md
+++ b/docs/framework/preact/reference/functions/mutationOptions.md
@@ -70,9 +70,11 @@ const isCreatingPost = useMutationState({
 function mutationOptions<TData, TError, TVariables, TOnMutateResult>(options): Omit<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">;
 ```
 
-Defined in: [preact-query/src/mutationOptions.ts:62](https://github.com/TanStack/query/blob/main/packages/preact-query/src/mutationOptions.ts#L62)
+Defined in: [preact-query/src/mutationOptions.ts:63](https://github.com/TanStack/query/blob/main/packages/preact-query/src/mutationOptions.ts#L63)
 
-You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`.
+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
+(e.g. with `useMutationState`).
 
 ### Type Parameters
 
@@ -108,7 +110,6 @@ You can generally pass everything to `mutationOptions` that you can also pass to
 import { mutationOptions, useMutation } from '@tanstack/preact-query'
 
 export const createPostOptions = mutationOptions({
-  mutationKey: ['posts', 'create'],
   mutationFn: createPost,
 })
 
diff --git a/docs/framework/preact/reference/functions/queryOptions.md b/docs/framework/preact/reference/functions/queryOptions.md
index 5f57a8dce81..1b1ee4ae7d5 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:124](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L124)
+Defined in: [preact-query/src/queryOptions.ts:127](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L127)
 
 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
@@ -94,7 +94,7 @@ queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefi
 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:187](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L187)
+Defined in: [preact-query/src/queryOptions.ts:190](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L190)
 
 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
@@ -179,7 +179,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:250](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L250)
+Defined in: [preact-query/src/queryOptions.ts:253](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L253)
 
 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 72b453cd104..aedc4544c85 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:28](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L28)
+Defined in: [preact-query/src/useInfiniteQuery.ts:31](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L31)
 
 The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
 `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
@@ -53,13 +53,17 @@ be used.
 
 [`DefinedUseInfiniteQueryResult`](../type-aliases/DefinedUseInfiniteQueryResult.md)\<`TData`, `TError`\>
 
+The same properties as `useQuery`, with the addition of `data.pages`, `data.pageParams`,
+`fetchNextPage`, `fetchPreviousPage`, `hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and
+`isFetchingPreviousPage`.
+
 ## Call Signature
 
 ```ts
 function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): UseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useInfiniteQuery.ts:52](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L52)
+Defined in: [preact-query/src/useInfiniteQuery.ts:58](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L58)
 
 The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
 `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
@@ -103,13 +107,17 @@ be used.
 
 [`UseInfiniteQueryResult`](../type-aliases/UseInfiniteQueryResult.md)\<`TData`, `TError`\>
 
+The same properties as `useQuery`, with the addition of `data.pages`, `data.pageParams`,
+`fetchNextPage`, `fetchPreviousPage`, `hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and
+`isFetchingPreviousPage`.
+
 ## Call Signature
 
 ```ts
 function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): UseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useInfiniteQuery.ts:109](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L109)
+Defined in: [preact-query/src/useInfiniteQuery.ts:115](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L115)
 
 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 084cb50bd8e..372ae952eac 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:19](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L19)
+Defined in: [preact-query/src/useQuery.ts:22](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L22)
 
 ### Type Parameters
 
@@ -46,13 +46,17 @@ be used.
 
 [`DefinedUseQueryResult`](../type-aliases/DefinedUseQueryResult.md)\<`TData`, `TError`\>
 
+The current query result. `status` is `pending` if there is no cached data and no query attempt
+has finished yet, `error` if the query attempt resulted in an error, or `success` if the query has data to
+display. `isPending`/`isSuccess`/`isError` are derived booleans for convenience.
+
 ## Call Signature
 
 ```ts
 function useQuery<TQueryFnData, TError, TData, TQueryKey>(options, queryClient?): UseQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useQuery.ts:33](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L33)
+Defined in: [preact-query/src/useQuery.ts:39](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L39)
 
 ### Type Parameters
 
@@ -89,13 +93,17 @@ be used.
 
 [`UseQueryResult`](../type-aliases/UseQueryResult.md)\<`TData`, `TError`\>
 
+The current query result. `status` is `pending` if there is no cached data and no query attempt
+has finished yet, `error` if the query attempt resulted in an error, or `success` if the query has data to
+display. `isPending`/`isSuccess`/`isError` are derived booleans for convenience.
+
 ## Call Signature
 
 ```ts
 function useQuery<TQueryFnData, TError, TData, TQueryKey>(options, queryClient?): UseQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useQuery.ts:110](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L110)
+Defined in: [preact-query/src/useQuery.ts:119](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L119)
 
 ### Type Parameters
 
@@ -132,6 +140,10 @@ be used.
 
 [`UseQueryResult`](../type-aliases/UseQueryResult.md)\<`TData`, `TError`\>
 
+The current query result. `status` is `pending` if there is no cached data and no query attempt
+has finished yet, `error` if the query attempt resulted in an error, or `success` if the query has data to
+display. `isPending`/`isSuccess`/`isError` are derived booleans for convenience.
+
 ### Examples
 
 ```tsx
diff --git a/docs/framework/preact/reference/type-aliases/DefinedInitialDataOptions.md b/docs/framework/preact/reference/type-aliases/DefinedInitialDataOptions.md
index e0f93e4fb02..d73bb22cbc0 100644
--- a/docs/framework/preact/reference/type-aliases/DefinedInitialDataOptions.md
+++ b/docs/framework/preact/reference/type-aliases/DefinedInitialDataOptions.md
@@ -31,6 +31,8 @@ cache.
 optional queryFn: QueryFunction<TQueryFnData, TQueryKey>;
 ```
 
+Optional here — since `initialData` is set, the query already has data to display without a query function.
+
 ## Type Parameters
 
 ### TQueryFnData
diff --git a/packages/preact-query/src/mutationOptions.ts b/packages/preact-query/src/mutationOptions.ts
index b2ec881dcd2..f477c1c3e09 100644
--- a/packages/preact-query/src/mutationOptions.ts
+++ b/packages/preact-query/src/mutationOptions.ts
@@ -42,14 +42,15 @@ export function mutationOptions<
   'mutationKey'
 >
 /**
- * You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`.
+ * 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
+ * (e.g. with `useMutationState`).
  *
  * @example
  * ```tsx
  * import { mutationOptions, useMutation } from '@tanstack/preact-query'
  *
  * export const createPostOptions = mutationOptions({
- *   mutationKey: ['posts', 'create'],
  *   mutationFn: createPost,
  * })
  *
diff --git a/packages/preact-query/src/queryOptions.ts b/packages/preact-query/src/queryOptions.ts
index 77e74201264..70506dcc078 100644
--- a/packages/preact-query/src/queryOptions.ts
+++ b/packages/preact-query/src/queryOptions.ts
@@ -65,6 +65,9 @@ export type DefinedInitialDataOptions<
   initialData:
     | NonUndefinedGuard<TQueryFnData>
     | (() => NonUndefinedGuard<TQueryFnData>)
+  /**
+   * Optional here — since `initialData` is set, the query already has data to display without a query function.
+   */
   queryFn?: QueryFunction<TQueryFnData, TQueryKey>
 }
 
diff --git a/packages/preact-query/src/useInfiniteQuery.ts b/packages/preact-query/src/useInfiniteQuery.ts
index edd125f518e..ddc0dcaecef 100644
--- a/packages/preact-query/src/useInfiniteQuery.ts
+++ b/packages/preact-query/src/useInfiniteQuery.ts
@@ -24,6 +24,9 @@ import { useBaseQuery } from './useBaseQuery'
  *
  * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
  * be used.
+ * @returns The same properties as `useQuery`, with the addition of `data.pages`, `data.pageParams`,
+ * `fetchNextPage`, `fetchPreviousPage`, `hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and
+ * `isFetchingPreviousPage`.
  */
 export function useInfiniteQuery<
   TQueryFnData,
@@ -48,6 +51,9 @@ export function useInfiniteQuery<
  *
  * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
  * be used.
+ * @returns The same properties as `useQuery`, with the addition of `data.pages`, `data.pageParams`,
+ * `fetchNextPage`, `fetchPreviousPage`, `hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and
+ * `isFetchingPreviousPage`.
  */
 export function useInfiniteQuery<
   TQueryFnData,
diff --git a/packages/preact-query/src/useQuery.ts b/packages/preact-query/src/useQuery.ts
index 7d24e696344..4d67ec749ed 100644
--- a/packages/preact-query/src/useQuery.ts
+++ b/packages/preact-query/src/useQuery.ts
@@ -15,6 +15,9 @@ import { useBaseQuery } from './useBaseQuery'
 /**
  * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
  * be used.
+ * @returns The current query result. `status` is `pending` if there is no cached data and no query attempt
+ * has finished yet, `error` if the query attempt resulted in an error, or `success` if the query has data to
+ * display. `isPending`/`isSuccess`/`isError` are derived booleans for convenience.
  */
 export function useQuery<
   TQueryFnData = unknown,
@@ -29,6 +32,9 @@ export function useQuery<
 /**
  * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
  * be used.
+ * @returns The current query result. `status` is `pending` if there is no cached data and no query attempt
+ * has finished yet, `error` if the query attempt resulted in an error, or `success` if the query has data to
+ * display. `isPending`/`isSuccess`/`isError` are derived booleans for convenience.
  */
 export function useQuery<
   TQueryFnData = unknown,
@@ -43,6 +49,9 @@ export function useQuery<
 /**
  * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
  * be used.
+ * @returns The current query result. `status` is `pending` if there is no cached data and no query attempt
+ * has finished yet, `error` if the query attempt resulted in an error, or `success` if the query has data to
+ * display. `isPending`/`isSuccess`/`isError` are derived booleans for convenience.
  *
  * @example
  * ```tsx

From ae3438abb10cf83bb643a0794f4563e650d09a79 Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Tue, 25 Aug 2026 01:20:39 +0900
Subject: [PATCH 13/28] docs(preact-query): split mutationOptions' mutationKey
 overload into basic usage and lookup examples

---
 .../reference/functions/mutationOptions.md    | 19 ++++++++++++++-----
 packages/preact-query/src/mutationOptions.ts  | 14 ++++++++++++--
 2 files changed, 26 insertions(+), 7 deletions(-)

diff --git a/docs/framework/preact/reference/functions/mutationOptions.md b/docs/framework/preact/reference/functions/mutationOptions.md
index 4ee6d46c9c9..34a597b4d2b 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:30](https://github.com/TanStack/query/blob/main/packages/preact-query/src/mutationOptions.ts#L30)
+Defined in: [preact-query/src/mutationOptions.ts:40](https://github.com/TanStack/query/blob/main/packages/preact-query/src/mutationOptions.ts#L40)
 
 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
@@ -43,10 +43,10 @@ You can generally pass everything to `mutationOptions` that you can also pass to
 
 `WithRequired`\<[`UseMutationOptions`](../interfaces/UseMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\>
 
-### Example
+### Examples
 
 ```tsx
-import { mutationOptions, useMutation, useMutationState } from '@tanstack/preact-query'
+import { mutationOptions, useMutation } from '@tanstack/preact-query'
 
 export const createPostOptions = mutationOptions({
   mutationKey: ['posts', 'create'],
@@ -57,8 +57,17 @@ function CreatePost() {
   const mutation = useMutation(createPostOptions)
   return <button onClick={() => mutation.mutate({ title: 'Hello' })}>Create</button>
 }
+```
+
+Looking the mutation up elsewhere via its `mutationKey`, e.g. for a global "saving…" indicator:
+```tsx
+import { mutationOptions, useMutationState } from '@tanstack/preact-query'
+
+const createPostOptions = mutationOptions({
+  mutationKey: ['posts', 'create'],
+  mutationFn: createPost,
+})
 
-// Elsewhere, e.g. to show a global "saving…" indicator:
 const isCreatingPost = useMutationState({
   filters: { mutationKey: createPostOptions.mutationKey, status: 'pending' },
 }).length > 0
@@ -70,7 +79,7 @@ const isCreatingPost = useMutationState({
 function mutationOptions<TData, TError, TVariables, TOnMutateResult>(options): Omit<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">;
 ```
 
-Defined in: [preact-query/src/mutationOptions.ts:63](https://github.com/TanStack/query/blob/main/packages/preact-query/src/mutationOptions.ts#L63)
+Defined in: [preact-query/src/mutationOptions.ts:73](https://github.com/TanStack/query/blob/main/packages/preact-query/src/mutationOptions.ts#L73)
 
 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
diff --git a/packages/preact-query/src/mutationOptions.ts b/packages/preact-query/src/mutationOptions.ts
index f477c1c3e09..9392eb27211 100644
--- a/packages/preact-query/src/mutationOptions.ts
+++ b/packages/preact-query/src/mutationOptions.ts
@@ -9,7 +9,7 @@ import type { UseMutationOptions } from './types'
  *
  * @example
  * ```tsx
- * import { mutationOptions, useMutation, useMutationState } from '@tanstack/preact-query'
+ * import { mutationOptions, useMutation } from '@tanstack/preact-query'
  *
  * export const createPostOptions = mutationOptions({
  *   mutationKey: ['posts', 'create'],
@@ -20,8 +20,18 @@ import type { UseMutationOptions } from './types'
  *   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'
+ *
+ * const createPostOptions = mutationOptions({
+ *   mutationKey: ['posts', 'create'],
+ *   mutationFn: createPost,
+ * })
  *
- * // Elsewhere, e.g. to show a global "saving…" indicator:
  * const isCreatingPost = useMutationState({
  *   filters: { mutationKey: createPostOptions.mutationKey, status: 'pending' },
  * }).length > 0

From 91553e174be5923f5ca9d6296f276a4c15112435 Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Tue, 25 Aug 2026 01:24:34 +0900
Subject: [PATCH 14/28] docs(preact-query): fix overloads whose example didn't
 match their initialData-required type

---
 .../functions/infiniteQueryOptions.md         | 37 +++++---------
 .../reference/functions/queryOptions.md       | 50 +++++--------------
 .../reference/functions/useInfiniteQuery.md   | 27 ++++++++--
 .../preact/reference/functions/useQuery.md    | 25 ++++++++--
 .../preact-query/src/infiniteQueryOptions.ts  | 30 ++++-------
 packages/preact-query/src/queryOptions.ts     | 44 ++++------------
 packages/preact-query/src/useInfiniteQuery.ts | 20 ++++++++
 packages/preact-query/src/useQuery.ts         | 18 +++++++
 8 files changed, 128 insertions(+), 123 deletions(-)

diff --git a/docs/framework/preact/reference/functions/infiniteQueryOptions.md b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
index 6bed19d76ce..66492a66a22 100644
--- a/docs/framework/preact/reference/functions/infiniteQueryOptions.md
+++ b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
@@ -9,12 +9,15 @@ 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:135](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L135)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:123](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L123)
 
 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`.
 `options.queryKey` is required and is the query key to generate options for.
 
+This overload is selected when `initialData` is set, so `queryFn` is optional and the resulting `data` is
+never `undefined`.
+
 ### Type Parameters
 
 #### TQueryFnData
@@ -47,38 +50,24 @@ These options can be shared across hooks and imperative APIs such as `queryClien
 
 The same options object, typed so that `queryKey` carries the inferred data type.
 
-### Examples
+### Example
 
 ```tsx
-import { infiniteQueryOptions } from '@tanstack/preact-query'
+import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
 
 export const projectsOptions = infiniteQueryOptions({
   queryKey: ['projects'],
   queryFn: ({ pageParam }) => fetchProjects(pageParam),
   initialPageParam: 0,
   getNextPageParam: (lastPage) => lastPage.nextId,
+  initialData: { pages: [], pageParams: [] },
 })
-```
-
-A parameterized factory, reused across a hook and an imperative call with the same cache entry:
-```tsx
-import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
 
-export 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 } = useInfiniteQuery(commentsOptions(postId))
-  return <>{data.pages.map((page) => page.comments.map((c) => <p key={c.id}>{c.text}</p>))}</>
+function Projects() {
+  // `data` is never `undefined`, thanks to `initialData`.
+  const { data } = useInfiniteQuery(projectsOptions)
+  return <>{data.pages.map((page) => page.projects.map((p) => <p key={p.id}>{p.name}</p>))}</>
 }
-
-// Elsewhere, e.g. to warm the cache before rendering `<Comments>`:
-queryClient.prefetchInfiniteQuery(commentsOptions(postId))
 ```
 
 ## Call Signature
@@ -87,7 +76,7 @@ queryClient.prefetchInfiniteQuery(commentsOptions(postId))
 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:199](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L199)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:187](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L187)
 
 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`.
@@ -165,7 +154,7 @@ queryClient.prefetchInfiniteQuery(commentsOptions(postId))
 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:263](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L263)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:251](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L251)
 
 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 1b1ee4ae7d5..9fc6b0c7749 100644
--- a/docs/framework/preact/reference/functions/queryOptions.md
+++ b/docs/framework/preact/reference/functions/queryOptions.md
@@ -9,12 +9,15 @@ 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:127](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L127)
+Defined in: [preact-query/src/queryOptions.ts:101](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L101)
 
 You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can
 be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and
 is the query key to generate options for.
 
+This overload is selected when `initialData` is set, so `queryFn` is optional and the resulting `data` is
+never `undefined`.
+
 ### Type Parameters
 
 #### TQueryFnData
@@ -43,49 +46,22 @@ is the query key to generate options for.
 
 The same options object, typed so that `queryKey` carries the inferred data type.
 
-### Examples
+### Example
 
 ```tsx
-import { queryOptions } from '@tanstack/preact-query'
+import { queryOptions, useQuery } from '@tanstack/preact-query'
 
 export const postsOptions = queryOptions({
   queryKey: ['posts'],
   queryFn: fetchPosts,
+  initialData: [],
 })
-```
-
-A parameterized factory, reused across a hook and an imperative call with the same cache entry:
-```tsx
-import { queryOptions, useQuery } from '@tanstack/preact-query'
 
-export const postOptions = (id: string) =>
-  queryOptions({
-    queryKey: ['post', id],
-    queryFn: () => fetchPost(id),
-  })
-
-function Post({ id }: { id: string }) {
-  const { data } = useQuery(postOptions(id))
-  return <h1>{data?.title}</h1>
+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>)}</>
 }
-
-// Elsewhere, e.g. to warm the cache before rendering `<Post>`:
-queryClient.prefetchQuery(postOptions(id))
-```
-
-The same options object works with every API that accepts query options:
-```tsx
-import { queryOptions, useQuery, useSuspenseQuery } from '@tanstack/preact-query'
-
-const todosOptions = queryOptions({
-  queryKey: ['todos'],
-  queryFn: fetchTodos,
-})
-
-useQuery(todosOptions)
-useSuspenseQuery(todosOptions)
-queryClient.prefetchQuery(todosOptions)
-queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefined
 ```
 
 ## Call Signature
@@ -94,7 +70,7 @@ queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefi
 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:190](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L190)
+Defined in: [preact-query/src/queryOptions.ts:164](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L164)
 
 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
@@ -179,7 +155,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:253](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L253)
+Defined in: [preact-query/src/queryOptions.ts:227](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L227)
 
 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 aedc4544c85..e21c46d2f89 100644
--- a/docs/framework/preact/reference/functions/useInfiniteQuery.md
+++ b/docs/framework/preact/reference/functions/useInfiniteQuery.md
@@ -9,11 +9,13 @@ title: useInfiniteQuery
 function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): DefinedUseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useInfiniteQuery.ts:31](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L31)
+Defined in: [preact-query/src/useInfiniteQuery.ts:51](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L51)
 
 The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
 `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
 
+This overload is selected when `initialData` is set, so the resulting `data` is never `undefined`.
+
 ### Type Parameters
 
 #### TQueryFnData
@@ -57,13 +59,32 @@ The same properties as `useQuery`, with the addition of `data.pages`, `data.page
 `fetchNextPage`, `fetchPreviousPage`, `hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and
 `isFetchingPreviousPage`.
 
+### Example
+
+```tsx
+import { useInfiniteQuery } from '@tanstack/preact-query'
+
+function Projects() {
+  // `data` is never `undefined`, thanks to `initialData`.
+  const { data } = useInfiniteQuery({
+    queryKey: ['projects'],
+    queryFn: ({ pageParam }) => fetchProjects(pageParam),
+    initialPageParam: 0,
+    getNextPageParam: (lastPage) => lastPage.nextId,
+    initialData: { pages: [], pageParams: [] },
+  })
+
+  return <>{data.pages.map((page) => page.projects.map((p) => <p key={p.id}>{p.name}</p>))}</>
+}
+```
+
 ## Call Signature
 
 ```ts
 function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): UseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useInfiniteQuery.ts:58](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L58)
+Defined in: [preact-query/src/useInfiniteQuery.ts:78](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L78)
 
 The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
 `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
@@ -117,7 +138,7 @@ The same properties as `useQuery`, with the addition of `data.pages`, `data.page
 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:135](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L135)
 
 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 372ae952eac..0b0f481099d 100644
--- a/docs/framework/preact/reference/functions/useQuery.md
+++ b/docs/framework/preact/reference/functions/useQuery.md
@@ -9,7 +9,9 @@ title: useQuery
 function useQuery<TQueryFnData, TError, TData, TQueryKey>(options, queryClient?): DefinedUseQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useQuery.ts:22](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L22)
+Defined in: [preact-query/src/useQuery.ts:40](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L40)
+
+This overload is selected when `initialData` is set, so the resulting `data` is never `undefined`.
 
 ### Type Parameters
 
@@ -50,13 +52,30 @@ The current query result. `status` is `pending` if there is no cached data and n
 has finished yet, `error` if the query attempt resulted in an error, or `success` if the query has data to
 display. `isPending`/`isSuccess`/`isError` are derived booleans for convenience.
 
+### Example
+
+```tsx
+import { useQuery } from '@tanstack/preact-query'
+
+function Posts() {
+  // `data` is `Post[]`, never `undefined`, thanks to `initialData`.
+  const { data } = useQuery({
+    queryKey: ['posts'],
+    queryFn: fetchPosts,
+    initialData: [],
+  })
+
+  return <>{data.map((post) => <p key={post.id}>{post.title}</p>)}</>
+}
+```
+
 ## Call Signature
 
 ```ts
 function useQuery<TQueryFnData, TError, TData, TQueryKey>(options, queryClient?): UseQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useQuery.ts:39](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L39)
+Defined in: [preact-query/src/useQuery.ts:57](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L57)
 
 ### Type Parameters
 
@@ -103,7 +122,7 @@ display. `isPending`/`isSuccess`/`isError` are derived booleans for convenience.
 function useQuery<TQueryFnData, TError, TData, TQueryKey>(options, queryClient?): UseQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useQuery.ts:119](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L119)
+Defined in: [preact-query/src/useQuery.ts:137](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L137)
 
 ### Type Parameters
 
diff --git a/packages/preact-query/src/infiniteQueryOptions.ts b/packages/preact-query/src/infiniteQueryOptions.ts
index c74a6aa0193..d174f461f45 100644
--- a/packages/preact-query/src/infiniteQueryOptions.ts
+++ b/packages/preact-query/src/infiniteQueryOptions.ts
@@ -96,40 +96,28 @@ export type DefinedInitialDataInfiniteOptions<
  * These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
  * `options.queryKey` is required and is the query key to generate options for.
  *
+ * This overload is selected when `initialData` is set, so `queryFn` is optional and the resulting `data` is
+ * never `undefined`.
+ *
  * @returns The same options object, typed so that `queryKey` carries the inferred data type.
  *
  * @example
  * ```tsx
- * import { infiniteQueryOptions } from '@tanstack/preact-query'
+ * import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
  *
  * export const projectsOptions = infiniteQueryOptions({
  *   queryKey: ['projects'],
  *   queryFn: ({ pageParam }) => fetchProjects(pageParam),
  *   initialPageParam: 0,
  *   getNextPageParam: (lastPage) => lastPage.nextId,
+ *   initialData: { pages: [], pageParams: [] },
  * })
- * ```
- *
- * @example
- * A parameterized factory, reused across a hook and an imperative call with the same cache entry:
- * ```tsx
- * import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
  *
- * export 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 } = useInfiniteQuery(commentsOptions(postId))
- *   return <>{data.pages.map((page) => page.comments.map((c) => <p key={c.id}>{c.text}</p>))}</>
+ * function Projects() {
+ *   // `data` is never `undefined`, thanks to `initialData`.
+ *   const { data } = useInfiniteQuery(projectsOptions)
+ *   return <>{data.pages.map((page) => page.projects.map((p) => <p key={p.id}>{p.name}</p>))}</>
  * }
- *
- * // Elsewhere, e.g. to warm the cache before rendering `<Comments>`:
- * queryClient.prefetchInfiniteQuery(commentsOptions(postId))
  * ```
  */
 export function infiniteQueryOptions<
diff --git a/packages/preact-query/src/queryOptions.ts b/packages/preact-query/src/queryOptions.ts
index 70506dcc078..891a52f0218 100644
--- a/packages/preact-query/src/queryOptions.ts
+++ b/packages/preact-query/src/queryOptions.ts
@@ -76,52 +76,26 @@ export type DefinedInitialDataOptions<
  * be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and
  * is the query key to generate options for.
  *
+ * This overload is selected when `initialData` is set, so `queryFn` is optional and the resulting `data` is
+ * never `undefined`.
+ *
  * @returns The same options object, typed so that `queryKey` carries the inferred data type.
  *
  * @example
  * ```tsx
- * import { queryOptions } from '@tanstack/preact-query'
+ * import { queryOptions, useQuery } from '@tanstack/preact-query'
  *
  * export const postsOptions = queryOptions({
  *   queryKey: ['posts'],
  *   queryFn: fetchPosts,
+ *   initialData: [],
  * })
- * ```
- *
- * @example
- * A parameterized factory, reused across a hook and an imperative call with the same cache entry:
- * ```tsx
- * import { queryOptions, useQuery } from '@tanstack/preact-query'
  *
- * export const postOptions = (id: string) =>
- *   queryOptions({
- *     queryKey: ['post', id],
- *     queryFn: () => fetchPost(id),
- *   })
- *
- * function Post({ id }: { id: string }) {
- *   const { data } = useQuery(postOptions(id))
- *   return <h1>{data?.title}</h1>
+ * 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>)}</>
  * }
- *
- * // Elsewhere, e.g. to warm the cache before rendering `<Post>`:
- * queryClient.prefetchQuery(postOptions(id))
- * ```
- *
- * @example
- * The same options object works with every API that accepts query options:
- * ```tsx
- * import { queryOptions, useQuery, useSuspenseQuery } from '@tanstack/preact-query'
- *
- * const todosOptions = queryOptions({
- *   queryKey: ['todos'],
- *   queryFn: fetchTodos,
- * })
- *
- * useQuery(todosOptions)
- * useSuspenseQuery(todosOptions)
- * queryClient.prefetchQuery(todosOptions)
- * 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 ddc0dcaecef..bfb8873d39e 100644
--- a/packages/preact-query/src/useInfiniteQuery.ts
+++ b/packages/preact-query/src/useInfiniteQuery.ts
@@ -22,11 +22,31 @@ import { useBaseQuery } from './useBaseQuery'
  * The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
  * `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
  *
+ * This overload is selected when `initialData` is set, so the resulting `data` is never `undefined`.
+ *
  * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
  * be used.
  * @returns The same properties as `useQuery`, with the addition of `data.pages`, `data.pageParams`,
  * `fetchNextPage`, `fetchPreviousPage`, `hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and
  * `isFetchingPreviousPage`.
+ *
+ * @example
+ * ```tsx
+ * import { useInfiniteQuery } from '@tanstack/preact-query'
+ *
+ * function Projects() {
+ *   // `data` is never `undefined`, thanks to `initialData`.
+ *   const { data } = useInfiniteQuery({
+ *     queryKey: ['projects'],
+ *     queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *     initialPageParam: 0,
+ *     getNextPageParam: (lastPage) => lastPage.nextId,
+ *     initialData: { pages: [], pageParams: [] },
+ *   })
+ *
+ *   return <>{data.pages.map((page) => page.projects.map((p) => <p key={p.id}>{p.name}</p>))}</>
+ * }
+ * ```
  */
 export function useInfiniteQuery<
   TQueryFnData,
diff --git a/packages/preact-query/src/useQuery.ts b/packages/preact-query/src/useQuery.ts
index 4d67ec749ed..d20cb15da3b 100644
--- a/packages/preact-query/src/useQuery.ts
+++ b/packages/preact-query/src/useQuery.ts
@@ -13,11 +13,29 @@ import type {
 import { useBaseQuery } from './useBaseQuery'
 
 /**
+ * This overload is selected when `initialData` is set, so the resulting `data` is never `undefined`.
+ *
  * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
  * be used.
  * @returns The current query result. `status` is `pending` if there is no cached data and no query attempt
  * has finished yet, `error` if the query attempt resulted in an error, or `success` if the query has data to
  * display. `isPending`/`isSuccess`/`isError` are derived booleans for convenience.
+ *
+ * @example
+ * ```tsx
+ * import { useQuery } from '@tanstack/preact-query'
+ *
+ * function Posts() {
+ *   // `data` is `Post[]`, never `undefined`, thanks to `initialData`.
+ *   const { data } = useQuery({
+ *     queryKey: ['posts'],
+ *     queryFn: fetchPosts,
+ *     initialData: [],
+ *   })
+ *
+ *   return <>{data.map((post) => <p key={post.id}>{post.title}</p>)}</>
+ * }
+ * ```
  */
 export function useQuery<
   TQueryFnData = unknown,

From d653d0c8df85618f638190a51347870adb53ee9b Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Tue, 25 Aug 2026 01:27:35 +0900
Subject: [PATCH 15/28] docs(preact-query): fill overloads missing examples and
 useSuspenseQueries' queryClient param description

---
 .../reference/functions/useInfiniteQuery.md   | 31 +++++++++++++++++--
 .../preact/reference/functions/useQuery.md    | 31 +++++++++++++++++--
 .../reference/functions/useSuspenseQueries.md | 10 ++++--
 packages/preact-query/src/useInfiniteQuery.ts | 26 ++++++++++++++++
 packages/preact-query/src/useQuery.ts         | 26 ++++++++++++++++
 .../preact-query/src/useSuspenseQueries.ts    |  4 +++
 6 files changed, 122 insertions(+), 6 deletions(-)

diff --git a/docs/framework/preact/reference/functions/useInfiniteQuery.md b/docs/framework/preact/reference/functions/useInfiniteQuery.md
index e21c46d2f89..26d1472e9a9 100644
--- a/docs/framework/preact/reference/functions/useInfiniteQuery.md
+++ b/docs/framework/preact/reference/functions/useInfiniteQuery.md
@@ -84,7 +84,7 @@ function Projects() {
 function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): UseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useInfiniteQuery.ts:78](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L78)
+Defined in: [preact-query/src/useInfiniteQuery.ts:104](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L104)
 
 The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
 `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
@@ -132,13 +132,40 @@ The same properties as `useQuery`, with the addition of `data.pages`, `data.page
 `fetchNextPage`, `fetchPreviousPage`, `hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and
 `isFetchingPreviousPage`.
 
+### Example
+
+```tsx
+import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
+
+const projectsOptions = infiniteQueryOptions({
+  queryKey: ['projects'],
+  queryFn: ({ pageParam }) => fetchProjects(pageParam),
+  initialPageParam: 0,
+  getNextPageParam: (lastPage) => lastPage.nextId,
+})
+
+function Projects() {
+  const { data, fetchNextPage, hasNextPage, isFetchingNextPage } =
+    useInfiniteQuery(projectsOptions)
+
+  return (
+    <button
+      onClick={() => fetchNextPage()}
+      disabled={!hasNextPage || isFetchingNextPage}
+    >
+      Load More
+    </button>
+  )
+}
+```
+
 ## Call Signature
 
 ```ts
 function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): UseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useInfiniteQuery.ts:135](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L135)
+Defined in: [preact-query/src/useInfiniteQuery.ts:161](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L161)
 
 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 0b0f481099d..0d2b74e764d 100644
--- a/docs/framework/preact/reference/functions/useQuery.md
+++ b/docs/framework/preact/reference/functions/useQuery.md
@@ -75,7 +75,7 @@ function Posts() {
 function useQuery<TQueryFnData, TError, TData, TQueryKey>(options, queryClient?): UseQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useQuery.ts:57](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L57)
+Defined in: [preact-query/src/useQuery.ts:83](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L83)
 
 ### Type Parameters
 
@@ -116,13 +116,40 @@ The current query result. `status` is `pending` if there is no cached data and n
 has finished yet, `error` if the query attempt resulted in an error, or `success` if the query has data to
 display. `isPending`/`isSuccess`/`isError` are derived booleans for convenience.
 
+### Example
+
+```tsx
+import { queryOptions, useQuery } from '@tanstack/preact-query'
+
+const postsOptions = queryOptions({
+  queryKey: ['posts'],
+  queryFn: fetchPosts,
+})
+
+function Posts() {
+  const { status, data, error, isFetching } = useQuery(postsOptions)
+
+  if (status === 'pending') return 'Loading...'
+  if (status === 'error') return <span>Error: {error.message}</span>
+
+  return (
+    <div>
+      {data.map((post) => (
+        <p key={post.id}>{post.title}</p>
+      ))}
+      <div>{isFetching ? 'Background Updating...' : ' '}</div>
+    </div>
+  )
+}
+```
+
 ## Call Signature
 
 ```ts
 function useQuery<TQueryFnData, TError, TData, TQueryKey>(options, queryClient?): UseQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useQuery.ts:137](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L137)
+Defined in: [preact-query/src/useQuery.ts:163](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L163)
 
 ### Type Parameters
 
diff --git a/docs/framework/preact/reference/functions/useSuspenseQueries.md b/docs/framework/preact/reference/functions/useSuspenseQueries.md
index 4855f0e4fb7..8281abc2294 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:209](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseQueries.ts#L209)
+Defined in: [preact-query/src/useSuspenseQueries.ts:211](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseQueries.ts#L211)
 
 The options for `useSuspenseQueries` are the same as for `useQueries`, except that each `query` can't have
 `throwOnError`, `enabled`, or `placeholderData`.
@@ -41,6 +41,9 @@ The options for `useSuspenseQueries` are the same as for `useQueries`, except th
 
 `QueryClient`
 
+Use this to provide a custom QueryClient. Otherwise, the one from the nearest context
+will be used.
+
 ### Returns
 
 `TCombinedResult`
@@ -92,7 +95,7 @@ function App() {
 function useSuspenseQueries<T, TCombinedResult>(options, queryClient?): TCombinedResult;
 ```
 
-Defined in: [preact-query/src/useSuspenseQueries.ts:266](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseQueries.ts#L266)
+Defined in: [preact-query/src/useSuspenseQueries.ts:270](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseQueries.ts#L270)
 
 The options for `useSuspenseQueries` are the same as for `useQueries`, except that each `query` can't have
 `throwOnError`, `enabled`, or `placeholderData`.
@@ -123,6 +126,9 @@ readonly \[`T` *extends* \[\] ? \[\] : `T` *extends* \[`Head`\] ? \[`GetUseSuspe
 
 `QueryClient`
 
+Use this to provide a custom QueryClient. Otherwise, the one from the nearest context
+will be used.
+
 ### Returns
 
 `TCombinedResult`
diff --git a/packages/preact-query/src/useInfiniteQuery.ts b/packages/preact-query/src/useInfiniteQuery.ts
index bfb8873d39e..974c23eb9f4 100644
--- a/packages/preact-query/src/useInfiniteQuery.ts
+++ b/packages/preact-query/src/useInfiniteQuery.ts
@@ -74,6 +74,32 @@ export function useInfiniteQuery<
  * @returns The same properties as `useQuery`, with the addition of `data.pages`, `data.pageParams`,
  * `fetchNextPage`, `fetchPreviousPage`, `hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and
  * `isFetchingPreviousPage`.
+ *
+ * @example
+ * ```tsx
+ * import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
+ *
+ * const projectsOptions = infiniteQueryOptions({
+ *   queryKey: ['projects'],
+ *   queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *   initialPageParam: 0,
+ *   getNextPageParam: (lastPage) => lastPage.nextId,
+ * })
+ *
+ * function Projects() {
+ *   const { data, fetchNextPage, hasNextPage, isFetchingNextPage } =
+ *     useInfiniteQuery(projectsOptions)
+ *
+ *   return (
+ *     <button
+ *       onClick={() => fetchNextPage()}
+ *       disabled={!hasNextPage || isFetchingNextPage}
+ *     >
+ *       Load More
+ *     </button>
+ *   )
+ * }
+ * ```
  */
 export function useInfiniteQuery<
   TQueryFnData,
diff --git a/packages/preact-query/src/useQuery.ts b/packages/preact-query/src/useQuery.ts
index d20cb15da3b..f8b0a420201 100644
--- a/packages/preact-query/src/useQuery.ts
+++ b/packages/preact-query/src/useQuery.ts
@@ -53,6 +53,32 @@ export function useQuery<
  * @returns The current query result. `status` is `pending` if there is no cached data and no query attempt
  * has finished yet, `error` if the query attempt resulted in an error, or `success` if the query has data to
  * display. `isPending`/`isSuccess`/`isError` are derived booleans for convenience.
+ *
+ * @example
+ * ```tsx
+ * import { queryOptions, useQuery } from '@tanstack/preact-query'
+ *
+ * const postsOptions = queryOptions({
+ *   queryKey: ['posts'],
+ *   queryFn: fetchPosts,
+ * })
+ *
+ * function Posts() {
+ *   const { status, data, error, isFetching } = useQuery(postsOptions)
+ *
+ *   if (status === 'pending') return 'Loading...'
+ *   if (status === 'error') return <span>Error: {error.message}</span>
+ *
+ *   return (
+ *     <div>
+ *       {data.map((post) => (
+ *         <p key={post.id}>{post.title}</p>
+ *       ))}
+ *       <div>{isFetching ? 'Background Updating...' : ' '}</div>
+ *     </div>
+ *   )
+ * }
+ * ```
  */
 export function useQuery<
   TQueryFnData = unknown,
diff --git a/packages/preact-query/src/useSuspenseQueries.ts b/packages/preact-query/src/useSuspenseQueries.ts
index 32b65453e3c..c29688a7c63 100644
--- a/packages/preact-query/src/useSuspenseQueries.ts
+++ b/packages/preact-query/src/useSuspenseQueries.ts
@@ -166,6 +166,8 @@ export type SuspenseQueriesResults<
  * The options for `useSuspenseQueries` are the same as for `useQueries`, except that each `query` can't have
  * `throwOnError`, `enabled`, or `placeholderData`.
  *
+ * @param queryClient - Use this to provide a custom QueryClient. Otherwise, the one from the nearest context
+ * will be used.
  * @returns The same structure as `useQueries`, except that for each `query`, `data` is guaranteed to be
  * defined, `isPlaceholderData` is missing, and `status` is either `success` or `error` (with the derived
  * flags set accordingly).
@@ -223,6 +225,8 @@ export function useSuspenseQueries<
  * The options for `useSuspenseQueries` are the same as for `useQueries`, except that each `query` can't have
  * `throwOnError`, `enabled`, or `placeholderData`.
  *
+ * @param queryClient - Use this to provide a custom QueryClient. Otherwise, the one from the nearest context
+ * will be used.
  * @returns The same structure as `useQueries`, except that for each `query`, `data` is guaranteed to be
  * defined, `isPlaceholderData` is missing, and `status` is either `success` or `error` (with the derived
  * flags set accordingly).

From e0c128117947d6a5c4b16c5cffd0bbda6e9a8c45 Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Tue, 25 Aug 2026 01:41:44 +0900
Subject: [PATCH 16/28] docs(preact-query): remove duplicated overload example
 and fix examples that failed type-checking

---
 .../functions/infiniteQueryOptions.md         | 22 +++++++++----
 .../reference/functions/mutationOptions.md    | 14 +++++---
 .../reference/functions/useInfiniteQuery.md   | 31 ++---------------
 .../preact/reference/functions/useMutation.md | 11 ++++---
 .../functions/usePrefetchInfiniteQuery.md     | 18 +++++-----
 .../preact/reference/functions/useQuery.md    | 33 ++-----------------
 .../reference/functions/useSuspenseQuery.md   | 16 ++++-----
 .../preact-query/src/infiniteQueryOptions.ts  | 18 +++++++---
 packages/preact-query/src/mutationOptions.ts  | 10 ++++--
 packages/preact-query/src/useInfiniteQuery.ts | 26 ---------------
 packages/preact-query/src/useMutation.ts      |  9 +++--
 .../src/usePrefetchInfiniteQuery.tsx          | 16 +++++----
 packages/preact-query/src/useQuery.ts         | 28 +---------------
 packages/preact-query/src/useSuspenseQuery.ts | 16 ++++-----
 14 files changed, 100 insertions(+), 168 deletions(-)

diff --git a/docs/framework/preact/reference/functions/infiniteQueryOptions.md b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
index 66492a66a22..5b189071c22 100644
--- a/docs/framework/preact/reference/functions/infiniteQueryOptions.md
+++ b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
@@ -76,7 +76,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:187](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L187)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:192](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L192)
 
 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`.
@@ -140,8 +140,13 @@ export const commentsOptions = (postId: string) =>
   })
 
 function Comments({ postId }: { postId: string }) {
-  const { data } = useInfiniteQuery(commentsOptions(postId))
-  return <>{data.pages.map((page) => page.comments.map((c) => <p key={c.id}>{c.text}</p>))}</>
+  const result = useInfiniteQuery(commentsOptions(postId))
+  if (!result.isSuccess) return 'Loading...'
+  return (
+    <>
+      {result.data.pages.map((page) => page.comments.map((c) => <p key={c.id}>{c.text}</p>))}
+    </>
+  )
 }
 
 // Elsewhere, e.g. to warm the cache before rendering `<Comments>`:
@@ -154,7 +159,7 @@ queryClient.prefetchInfiniteQuery(commentsOptions(postId))
 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:251](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L251)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:261](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L261)
 
 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`.
@@ -218,8 +223,13 @@ export const commentsOptions = (postId: string) =>
   })
 
 function Comments({ postId }: { postId: string }) {
-  const { data } = useInfiniteQuery(commentsOptions(postId))
-  return <>{data.pages.map((page) => page.comments.map((c) => <p key={c.id}>{c.text}</p>))}</>
+  const result = useInfiniteQuery(commentsOptions(postId))
+  if (!result.isSuccess) return 'Loading...'
+  return (
+    <>
+      {result.data.pages.map((page) => page.comments.map((c) => <p key={c.id}>{c.text}</p>))}
+    </>
+  )
 }
 
 // Elsewhere, e.g. to warm the cache before rendering `<Comments>`:
diff --git a/docs/framework/preact/reference/functions/mutationOptions.md b/docs/framework/preact/reference/functions/mutationOptions.md
index 34a597b4d2b..e4385a5eea8 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:40](https://github.com/TanStack/query/blob/main/packages/preact-query/src/mutationOptions.ts#L40)
+Defined in: [preact-query/src/mutationOptions.ts:44](https://github.com/TanStack/query/blob/main/packages/preact-query/src/mutationOptions.ts#L44)
 
 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
@@ -68,9 +68,13 @@ const createPostOptions = mutationOptions({
   mutationFn: createPost,
 })
 
-const isCreatingPost = useMutationState({
-  filters: { mutationKey: createPostOptions.mutationKey, status: 'pending' },
-}).length > 0
+function SavingIndicator() {
+  const isCreatingPost = useMutationState({
+    filters: { mutationKey: createPostOptions.mutationKey, status: 'pending' },
+  }).length > 0
+
+  return isCreatingPost ? <span>Saving…</span> : null
+}
 ```
 
 ## Call Signature
@@ -79,7 +83,7 @@ const isCreatingPost = useMutationState({
 function mutationOptions<TData, TError, TVariables, TOnMutateResult>(options): Omit<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">;
 ```
 
-Defined in: [preact-query/src/mutationOptions.ts:73](https://github.com/TanStack/query/blob/main/packages/preact-query/src/mutationOptions.ts#L73)
+Defined in: [preact-query/src/mutationOptions.ts:77](https://github.com/TanStack/query/blob/main/packages/preact-query/src/mutationOptions.ts#L77)
 
 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
diff --git a/docs/framework/preact/reference/functions/useInfiniteQuery.md b/docs/framework/preact/reference/functions/useInfiniteQuery.md
index 26d1472e9a9..e21c46d2f89 100644
--- a/docs/framework/preact/reference/functions/useInfiniteQuery.md
+++ b/docs/framework/preact/reference/functions/useInfiniteQuery.md
@@ -84,7 +84,7 @@ function Projects() {
 function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): UseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useInfiniteQuery.ts:104](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L104)
+Defined in: [preact-query/src/useInfiniteQuery.ts:78](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L78)
 
 The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
 `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
@@ -132,40 +132,13 @@ The same properties as `useQuery`, with the addition of `data.pages`, `data.page
 `fetchNextPage`, `fetchPreviousPage`, `hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and
 `isFetchingPreviousPage`.
 
-### Example
-
-```tsx
-import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
-
-const projectsOptions = infiniteQueryOptions({
-  queryKey: ['projects'],
-  queryFn: ({ pageParam }) => fetchProjects(pageParam),
-  initialPageParam: 0,
-  getNextPageParam: (lastPage) => lastPage.nextId,
-})
-
-function Projects() {
-  const { data, fetchNextPage, hasNextPage, isFetchingNextPage } =
-    useInfiniteQuery(projectsOptions)
-
-  return (
-    <button
-      onClick={() => fetchNextPage()}
-      disabled={!hasNextPage || isFetchingNextPage}
-    >
-      Load More
-    </button>
-  )
-}
-```
-
 ## Call Signature
 
 ```ts
 function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): UseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useInfiniteQuery.ts:161](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L161)
+Defined in: [preact-query/src/useInfiniteQuery.ts:135](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L135)
 
 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/useMutation.md b/docs/framework/preact/reference/functions/useMutation.md
index 2a33451105c..5b562f16380 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:79](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useMutation.ts#L79)
+Defined in: [preact-query/src/useMutation.ts:82](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useMutation.ts#L82)
 
 ## Type Parameters
 
@@ -79,15 +79,18 @@ function AddTodo() {
     mutationFn: addTodo,
     onMutate: async (newTodo) => {
       await queryClient.cancelQueries({ queryKey: ['todos'] })
-      const previousTodos = queryClient.getQueryData(['todos'])
+      const previousTodos = queryClient.getQueryData<Array<string>>(['todos'])
 
-      queryClient.setQueryData(['todos'], (old) => [...old, newTodo])
+      queryClient.setQueryData<Array<string>>(['todos'], (old) => [
+        ...(old ?? []),
+        newTodo,
+      ])
 
       // Passed to `onError` as `context` if the mutation fails.
       return { previousTodos }
     },
     onError: (_err, _newTodo, context) => {
-      queryClient.setQueryData(['todos'], context.previousTodos)
+      queryClient.setQueryData(['todos'], context?.previousTodos)
     },
     onSettled: () => {
       queryClient.invalidateQueries({ queryKey: ['todos'] })
diff --git a/docs/framework/preact/reference/functions/usePrefetchInfiniteQuery.md b/docs/framework/preact/reference/functions/usePrefetchInfiniteQuery.md
index 12d8e50a30e..d8835ecc75e 100644
--- a/docs/framework/preact/reference/functions/usePrefetchInfiniteQuery.md
+++ b/docs/framework/preact/reference/functions/usePrefetchInfiniteQuery.md
@@ -7,7 +7,7 @@ title: usePrefetchInfiniteQuery
 function usePrefetchInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): void;
 ```
 
-Defined in: [preact-query/src/usePrefetchInfiniteQuery.tsx:43](https://github.com/TanStack/query/blob/main/packages/preact-query/src/usePrefetchInfiniteQuery.tsx#L43)
+Defined in: [preact-query/src/usePrefetchInfiniteQuery.tsx:45](https://github.com/TanStack/query/blob/main/packages/preact-query/src/usePrefetchInfiniteQuery.tsx#L45)
 
 `usePrefetchInfiniteQuery` does not return anything, it should be used just to fire a prefetch during render,
 before a suspense boundary that wraps a component that uses `useSuspenseInfiniteQuery`. You can pass
@@ -62,16 +62,18 @@ available.
 
 ```tsx
 import { Suspense } from 'preact/compat'
-import { usePrefetchInfiniteQuery } from '@tanstack/preact-query'
+import { infiniteQueryOptions, usePrefetchInfiniteQuery } from '@tanstack/preact-query'
+
+const projectsOptions = infiniteQueryOptions({
+  queryKey: ['projects'],
+  queryFn: ({ pageParam }) => fetchProjects(pageParam),
+  initialPageParam: 0,
+  getNextPageParam: (lastPage) => lastPage.nextId,
+})
 
 function App() {
   // Fire the prefetch during render, before the suspense boundary below.
-  usePrefetchInfiniteQuery({
-    queryKey: ['projects'],
-    queryFn: ({ pageParam }) => fetchProjects(pageParam),
-    initialPageParam: 0,
-    getNextPageParam: (lastPage) => lastPage.nextId,
-  })
+  usePrefetchInfiniteQuery(projectsOptions)
 
   return (
     <Suspense fallback={<h1>Loading projects...</h1>}>
diff --git a/docs/framework/preact/reference/functions/useQuery.md b/docs/framework/preact/reference/functions/useQuery.md
index 0d2b74e764d..dd882a88694 100644
--- a/docs/framework/preact/reference/functions/useQuery.md
+++ b/docs/framework/preact/reference/functions/useQuery.md
@@ -75,7 +75,7 @@ function Posts() {
 function useQuery<TQueryFnData, TError, TData, TQueryKey>(options, queryClient?): UseQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useQuery.ts:83](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L83)
+Defined in: [preact-query/src/useQuery.ts:57](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L57)
 
 ### Type Parameters
 
@@ -116,40 +116,13 @@ The current query result. `status` is `pending` if there is no cached data and n
 has finished yet, `error` if the query attempt resulted in an error, or `success` if the query has data to
 display. `isPending`/`isSuccess`/`isError` are derived booleans for convenience.
 
-### Example
-
-```tsx
-import { queryOptions, useQuery } from '@tanstack/preact-query'
-
-const postsOptions = queryOptions({
-  queryKey: ['posts'],
-  queryFn: fetchPosts,
-})
-
-function Posts() {
-  const { status, data, error, isFetching } = useQuery(postsOptions)
-
-  if (status === 'pending') return 'Loading...'
-  if (status === 'error') return <span>Error: {error.message}</span>
-
-  return (
-    <div>
-      {data.map((post) => (
-        <p key={post.id}>{post.title}</p>
-      ))}
-      <div>{isFetching ? 'Background Updating...' : ' '}</div>
-    </div>
-  )
-}
-```
-
 ## Call Signature
 
 ```ts
 function useQuery<TQueryFnData, TError, TData, TQueryKey>(options, queryClient?): UseQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useQuery.ts:163](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L163)
+Defined in: [preact-query/src/useQuery.ts:137](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L137)
 
 ### Type Parameters
 
@@ -244,7 +217,7 @@ function Post({ postId }: { postId: number }) {
     queryFn: () => fetchPost(postId),
     initialData: () =>
       queryClient
-        .getQueryData(['posts'])
+        .getQueryData<Array<Post>>(['posts'])
         ?.find((post) => post.id === postId),
   })
 
diff --git a/docs/framework/preact/reference/functions/useSuspenseQuery.md b/docs/framework/preact/reference/functions/useSuspenseQuery.md
index b03d00231d6..027f6a96f62 100644
--- a/docs/framework/preact/reference/functions/useSuspenseQuery.md
+++ b/docs/framework/preact/reference/functions/useSuspenseQuery.md
@@ -55,18 +55,18 @@ Caveat: cancellation does not work.
 import { Suspense } from 'preact/compat'
 import { useSuspenseQuery } from '@tanstack/preact-query'
 
-function Projects() {
+function Posts() {
   // `data` is guaranteed to be defined here — no `isPending` check needed.
   const { data, isFetching } = useSuspenseQuery({
-    queryKey: ['projects'],
-    queryFn: fetchProjects,
+    queryKey: ['posts'],
+    queryFn: fetchPosts,
   })
 
   return (
     <div>
-      <h1>Projects {isFetching ? <Spinner /> : null}</h1>
-      {data.map((project) => (
-        <p key={project.id}>{project.name}</p>
+      <h1>Posts {isFetching ? <Spinner /> : null}</h1>
+      {data.map((post) => (
+        <p key={post.id}>{post.title}</p>
       ))}
     </div>
   )
@@ -74,8 +74,8 @@ function Projects() {
 
 function App() {
   return (
-    <Suspense fallback={<h1>Loading projects...</h1>}>
-      <Projects />
+    <Suspense fallback={<h1>Loading posts...</h1>}>
+      <Posts />
     </Suspense>
   )
 }
diff --git a/packages/preact-query/src/infiniteQueryOptions.ts b/packages/preact-query/src/infiniteQueryOptions.ts
index d174f461f45..9f4607b61d8 100644
--- a/packages/preact-query/src/infiniteQueryOptions.ts
+++ b/packages/preact-query/src/infiniteQueryOptions.ts
@@ -176,8 +176,13 @@ export function infiniteQueryOptions<
  *   })
  *
  * function Comments({ postId }: { postId: string }) {
- *   const { data } = useInfiniteQuery(commentsOptions(postId))
- *   return <>{data.pages.map((page) => page.comments.map((c) => <p key={c.id}>{c.text}</p>))}</>
+ *   const result = useInfiniteQuery(commentsOptions(postId))
+ *   if (!result.isSuccess) return 'Loading...'
+ *   return (
+ *     <>
+ *       {result.data.pages.map((page) => page.comments.map((c) => <p key={c.id}>{c.text}</p>))}
+ *     </>
+ *   )
  * }
  *
  * // Elsewhere, e.g. to warm the cache before rendering `<Comments>`:
@@ -240,8 +245,13 @@ export function infiniteQueryOptions<
  *   })
  *
  * function Comments({ postId }: { postId: string }) {
- *   const { data } = useInfiniteQuery(commentsOptions(postId))
- *   return <>{data.pages.map((page) => page.comments.map((c) => <p key={c.id}>{c.text}</p>))}</>
+ *   const result = useInfiniteQuery(commentsOptions(postId))
+ *   if (!result.isSuccess) return 'Loading...'
+ *   return (
+ *     <>
+ *       {result.data.pages.map((page) => page.comments.map((c) => <p key={c.id}>{c.text}</p>))}
+ *     </>
+ *   )
  * }
  *
  * // Elsewhere, e.g. to warm the cache before rendering `<Comments>`:
diff --git a/packages/preact-query/src/mutationOptions.ts b/packages/preact-query/src/mutationOptions.ts
index 9392eb27211..c61a0067e58 100644
--- a/packages/preact-query/src/mutationOptions.ts
+++ b/packages/preact-query/src/mutationOptions.ts
@@ -32,9 +32,13 @@ import type { UseMutationOptions } from './types'
  *   mutationFn: createPost,
  * })
  *
- * const isCreatingPost = useMutationState({
- *   filters: { mutationKey: createPostOptions.mutationKey, status: 'pending' },
- * }).length > 0
+ * function SavingIndicator() {
+ *   const isCreatingPost = useMutationState({
+ *     filters: { mutationKey: createPostOptions.mutationKey, status: 'pending' },
+ *   }).length > 0
+ *
+ *   return isCreatingPost ? <span>Saving…</span> : null
+ * }
  * ```
  */
 export function mutationOptions<
diff --git a/packages/preact-query/src/useInfiniteQuery.ts b/packages/preact-query/src/useInfiniteQuery.ts
index 974c23eb9f4..bfb8873d39e 100644
--- a/packages/preact-query/src/useInfiniteQuery.ts
+++ b/packages/preact-query/src/useInfiniteQuery.ts
@@ -74,32 +74,6 @@ export function useInfiniteQuery<
  * @returns The same properties as `useQuery`, with the addition of `data.pages`, `data.pageParams`,
  * `fetchNextPage`, `fetchPreviousPage`, `hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and
  * `isFetchingPreviousPage`.
- *
- * @example
- * ```tsx
- * import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
- *
- * const projectsOptions = infiniteQueryOptions({
- *   queryKey: ['projects'],
- *   queryFn: ({ pageParam }) => fetchProjects(pageParam),
- *   initialPageParam: 0,
- *   getNextPageParam: (lastPage) => lastPage.nextId,
- * })
- *
- * function Projects() {
- *   const { data, fetchNextPage, hasNextPage, isFetchingNextPage } =
- *     useInfiniteQuery(projectsOptions)
- *
- *   return (
- *     <button
- *       onClick={() => fetchNextPage()}
- *       disabled={!hasNextPage || isFetchingNextPage}
- *     >
- *       Load More
- *     </button>
- *   )
- * }
- * ```
  */
 export function useInfiniteQuery<
   TQueryFnData,
diff --git a/packages/preact-query/src/useMutation.ts b/packages/preact-query/src/useMutation.ts
index 535e06b2563..8cd8af38042 100644
--- a/packages/preact-query/src/useMutation.ts
+++ b/packages/preact-query/src/useMutation.ts
@@ -55,15 +55,18 @@ import { useSyncExternalStore } from './utils'
  *     mutationFn: addTodo,
  *     onMutate: async (newTodo) => {
  *       await queryClient.cancelQueries({ queryKey: ['todos'] })
- *       const previousTodos = queryClient.getQueryData(['todos'])
+ *       const previousTodos = queryClient.getQueryData<Array<string>>(['todos'])
  *
- *       queryClient.setQueryData(['todos'], (old) => [...old, newTodo])
+ *       queryClient.setQueryData<Array<string>>(['todos'], (old) => [
+ *         ...(old ?? []),
+ *         newTodo,
+ *       ])
  *
  *       // Passed to `onError` as `context` if the mutation fails.
  *       return { previousTodos }
  *     },
  *     onError: (_err, _newTodo, context) => {
- *       queryClient.setQueryData(['todos'], context.previousTodos)
+ *       queryClient.setQueryData(['todos'], context?.previousTodos)
  *     },
  *     onSettled: () => {
  *       queryClient.invalidateQueries({ queryKey: ['todos'] })
diff --git a/packages/preact-query/src/usePrefetchInfiniteQuery.tsx b/packages/preact-query/src/usePrefetchInfiniteQuery.tsx
index b4bc5e6ad69..f0f286e7d39 100644
--- a/packages/preact-query/src/usePrefetchInfiniteQuery.tsx
+++ b/packages/preact-query/src/usePrefetchInfiniteQuery.tsx
@@ -21,16 +21,18 @@ import type { UsePrefetchInfiniteQueryOptions } from './types'
  * @example
  * ```tsx
  * import { Suspense } from 'preact/compat'
- * import { usePrefetchInfiniteQuery } from '@tanstack/preact-query'
+ * import { infiniteQueryOptions, usePrefetchInfiniteQuery } from '@tanstack/preact-query'
+ *
+ * const projectsOptions = infiniteQueryOptions({
+ *   queryKey: ['projects'],
+ *   queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *   initialPageParam: 0,
+ *   getNextPageParam: (lastPage) => lastPage.nextId,
+ * })
  *
  * function App() {
  *   // Fire the prefetch during render, before the suspense boundary below.
- *   usePrefetchInfiniteQuery({
- *     queryKey: ['projects'],
- *     queryFn: ({ pageParam }) => fetchProjects(pageParam),
- *     initialPageParam: 0,
- *     getNextPageParam: (lastPage) => lastPage.nextId,
- *   })
+ *   usePrefetchInfiniteQuery(projectsOptions)
  *
  *   return (
  *     <Suspense fallback={<h1>Loading projects...</h1>}>
diff --git a/packages/preact-query/src/useQuery.ts b/packages/preact-query/src/useQuery.ts
index f8b0a420201..6c0baba6c71 100644
--- a/packages/preact-query/src/useQuery.ts
+++ b/packages/preact-query/src/useQuery.ts
@@ -53,32 +53,6 @@ export function useQuery<
  * @returns The current query result. `status` is `pending` if there is no cached data and no query attempt
  * has finished yet, `error` if the query attempt resulted in an error, or `success` if the query has data to
  * display. `isPending`/`isSuccess`/`isError` are derived booleans for convenience.
- *
- * @example
- * ```tsx
- * import { queryOptions, useQuery } from '@tanstack/preact-query'
- *
- * const postsOptions = queryOptions({
- *   queryKey: ['posts'],
- *   queryFn: fetchPosts,
- * })
- *
- * function Posts() {
- *   const { status, data, error, isFetching } = useQuery(postsOptions)
- *
- *   if (status === 'pending') return 'Loading...'
- *   if (status === 'error') return <span>Error: {error.message}</span>
- *
- *   return (
- *     <div>
- *       {data.map((post) => (
- *         <p key={post.id}>{post.title}</p>
- *       ))}
- *       <div>{isFetching ? 'Background Updating...' : ' '}</div>
- *     </div>
- *   )
- * }
- * ```
  */
 export function useQuery<
   TQueryFnData = unknown,
@@ -152,7 +126,7 @@ export function useQuery<
  *     queryFn: () => fetchPost(postId),
  *     initialData: () =>
  *       queryClient
- *         .getQueryData(['posts'])
+ *         .getQueryData<Array<Post>>(['posts'])
  *         ?.find((post) => post.id === postId),
  *   })
  *
diff --git a/packages/preact-query/src/useSuspenseQuery.ts b/packages/preact-query/src/useSuspenseQuery.ts
index 1c393f9affb..22798536c54 100644
--- a/packages/preact-query/src/useSuspenseQuery.ts
+++ b/packages/preact-query/src/useSuspenseQuery.ts
@@ -19,18 +19,18 @@ import { useBaseQuery } from './useBaseQuery'
  * import { Suspense } from 'preact/compat'
  * import { useSuspenseQuery } from '@tanstack/preact-query'
  *
- * function Projects() {
+ * function Posts() {
  *   // `data` is guaranteed to be defined here — no `isPending` check needed.
  *   const { data, isFetching } = useSuspenseQuery({
- *     queryKey: ['projects'],
- *     queryFn: fetchProjects,
+ *     queryKey: ['posts'],
+ *     queryFn: fetchPosts,
  *   })
  *
  *   return (
  *     <div>
- *       <h1>Projects {isFetching ? <Spinner /> : null}</h1>
- *       {data.map((project) => (
- *         <p key={project.id}>{project.name}</p>
+ *       <h1>Posts {isFetching ? <Spinner /> : null}</h1>
+ *       {data.map((post) => (
+ *         <p key={post.id}>{post.title}</p>
  *       ))}
  *     </div>
  *   )
@@ -38,8 +38,8 @@ import { useBaseQuery } from './useBaseQuery'
  *
  * function App() {
  *   return (
- *     <Suspense fallback={<h1>Loading projects...</h1>}>
- *       <Projects />
+ *     <Suspense fallback={<h1>Loading posts...</h1>}>
+ *       <Posts />
  *     </Suspense>
  *   )
  * }

From 75c6efe5ab1a1f9c484c26a1cdc8a7466b71c1e2 Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Tue, 25 Aug 2026 01:56:42 +0900
Subject: [PATCH 17/28] docs(preact-query): describe every documented parameter
 and restore reverted overload example

---
 .../functions/infiniteQueryOptions.md         | 12 +++--
 .../reference/functions/mutationOptions.md    | 10 +++-
 .../reference/functions/queryOptions.md       | 12 +++--
 .../reference/functions/useInfiniteQuery.md   | 47 ++++++++++++++++---
 .../reference/functions/useIsFetching.md      |  2 +-
 .../reference/functions/useIsMutating.md      |  2 +-
 .../preact/reference/functions/useMutation.md |  4 +-
 .../reference/functions/useMutationState.md   |  5 +-
 .../functions/usePrefetchInfiniteQuery.md     |  7 ++-
 .../reference/functions/usePrefetchQuery.md   |  7 ++-
 .../preact/reference/functions/useQueries.md  |  8 ++++
 .../preact/reference/functions/useQuery.md    | 39 +++++++++++++--
 .../functions/useSuspenseInfiniteQuery.md     |  7 ++-
 .../reference/functions/useSuspenseQueries.md | 18 ++++++-
 .../reference/functions/useSuspenseQuery.md   |  7 ++-
 .../preact-query/src/infiniteQueryOptions.ts  |  5 ++
 packages/preact-query/src/mutationOptions.ts  |  6 +++
 packages/preact-query/src/queryOptions.ts     |  3 ++
 packages/preact-query/src/useInfiniteQuery.ts | 37 +++++++++++++--
 packages/preact-query/src/useIsFetching.ts    |  2 +-
 packages/preact-query/src/useMutation.ts      |  1 +
 packages/preact-query/src/useMutationState.ts |  4 +-
 .../src/usePrefetchInfiniteQuery.tsx          |  3 ++
 .../preact-query/src/usePrefetchQuery.tsx     |  3 ++
 packages/preact-query/src/useQueries.ts       | 11 +++++
 packages/preact-query/src/useQuery.ts         | 29 ++++++++++++
 .../src/useSuspenseInfiniteQuery.ts           |  3 ++
 .../preact-query/src/useSuspenseQueries.ts    | 16 +++++++
 packages/preact-query/src/useSuspenseQuery.ts |  3 ++
 29 files changed, 279 insertions(+), 34 deletions(-)

diff --git a/docs/framework/preact/reference/functions/infiniteQueryOptions.md b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
index 5b189071c22..3cc47a1369b 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:123](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L123)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:124](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L124)
 
 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`.
@@ -46,6 +46,8 @@ never `undefined`.
 
 [`DefinedInitialDataInfiniteOptions`](../type-aliases/DefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\>
 
+The [DefinedInitialDataInfiniteOptions](../type-aliases/DefinedInitialDataInfiniteOptions.md) 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.
@@ -76,7 +78,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:192](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L192)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:195](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L195)
 
 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`.
@@ -110,6 +112,8 @@ These options can be shared across hooks and imperative APIs such as `queryClien
 
 [`UnusedSkipTokenInfiniteOptions`](../type-aliases/UnusedSkipTokenInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\>
 
+The [UnusedSkipTokenInfiniteOptions](../type-aliases/UnusedSkipTokenInfiniteOptions.md) to use — everything you can pass to `useInfiniteQuery`.
+
 ### Returns
 
 The same options object, typed so that `queryKey` carries the inferred data type.
@@ -159,7 +163,7 @@ queryClient.prefetchInfiniteQuery(commentsOptions(postId))
 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:261](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L261)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:266](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L266)
 
 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`.
@@ -193,6 +197,8 @@ These options can be shared across hooks and imperative APIs such as `queryClien
 
 [`UndefinedInitialDataInfiniteOptions`](../type-aliases/UndefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\>
 
+The [UndefinedInitialDataInfiniteOptions](../type-aliases/UndefinedInitialDataInfiniteOptions.md) to use — everything you can pass to `useInfiniteQuery`.
+
 ### Returns
 
 The same options object, typed so that `queryKey` carries the inferred data type.
diff --git a/docs/framework/preact/reference/functions/mutationOptions.md b/docs/framework/preact/reference/functions/mutationOptions.md
index e4385a5eea8..b9992f68a78 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:44](https://github.com/TanStack/query/blob/main/packages/preact-query/src/mutationOptions.ts#L44)
+Defined in: [preact-query/src/mutationOptions.ts:47](https://github.com/TanStack/query/blob/main/packages/preact-query/src/mutationOptions.ts#L47)
 
 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
@@ -39,6 +39,9 @@ You can generally pass everything to `mutationOptions` that you can also pass to
 
 `WithRequired`\<[`UseMutationOptions`](../interfaces/UseMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\>
 
+The mutation options to use, identical to what you'd pass to `useMutation`, with a
+required `mutationKey`.
+
 ### Returns
 
 `WithRequired`\<[`UseMutationOptions`](../interfaces/UseMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\>
@@ -83,7 +86,7 @@ function SavingIndicator() {
 function mutationOptions<TData, TError, TVariables, TOnMutateResult>(options): Omit<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">;
 ```
 
-Defined in: [preact-query/src/mutationOptions.ts:77](https://github.com/TanStack/query/blob/main/packages/preact-query/src/mutationOptions.ts#L77)
+Defined in: [preact-query/src/mutationOptions.ts:83](https://github.com/TanStack/query/blob/main/packages/preact-query/src/mutationOptions.ts#L83)
 
 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
@@ -113,6 +116,9 @@ You can generally pass everything to `mutationOptions` that you can also pass to
 
 `Omit`\<[`UseMutationOptions`](../interfaces/UseMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\>
 
+The mutation options to use, identical to what you'd pass to `useMutation`, without a
+`mutationKey`.
+
 ### Returns
 
 `Omit`\<[`UseMutationOptions`](../interfaces/UseMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\>
diff --git a/docs/framework/preact/reference/functions/queryOptions.md b/docs/framework/preact/reference/functions/queryOptions.md
index 9fc6b0c7749..6f81946d5dd 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:101](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L101)
+Defined in: [preact-query/src/queryOptions.ts:102](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L102)
 
 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
@@ -42,6 +42,8 @@ never `undefined`.
 
 [`DefinedInitialDataOptions`](../type-aliases/DefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
 
+The [DefinedInitialDataOptions](../type-aliases/DefinedInitialDataOptions.md) 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.
@@ -70,7 +72,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:164](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L164)
+Defined in: [preact-query/src/queryOptions.ts:166](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L166)
 
 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
@@ -100,6 +102,8 @@ is the query key to generate options for.
 
 [`UnusedSkipTokenOptions`](../type-aliases/UnusedSkipTokenOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
 
+The [UnusedSkipTokenOptions](../type-aliases/UnusedSkipTokenOptions.md) to use — everything you can pass to `useQuery`.
+
 ### Returns
 
 The same options object, typed so that `queryKey` carries the inferred data type.
@@ -155,7 +159,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:227](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L227)
+Defined in: [preact-query/src/queryOptions.ts:230](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L230)
 
 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
@@ -185,6 +189,8 @@ is the query key to generate options for.
 
 [`UndefinedInitialDataOptions`](../type-aliases/UndefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
 
+The [UndefinedInitialDataOptions](../type-aliases/UndefinedInitialDataOptions.md) to use — everything you can pass to `useQuery`.
+
 ### Returns
 
 The same options object, typed so that `queryKey` carries the inferred data type.
diff --git a/docs/framework/preact/reference/functions/useInfiniteQuery.md b/docs/framework/preact/reference/functions/useInfiniteQuery.md
index e21c46d2f89..293c9b116f7 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:51](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L51)
+Defined in: [preact-query/src/useInfiniteQuery.ts:52](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L52)
 
 The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
 `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
@@ -44,6 +44,8 @@ This overload is selected when `initialData` is set, so the resulting `data` is
 
 [`DefinedInitialDataInfiniteOptions`](../type-aliases/DefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\>
 
+The [DefinedInitialDataInfiniteOptions](../type-aliases/DefinedInitialDataInfiniteOptions.md) to use — everything you can pass to `useInfiniteQuery`, with `initialData` set.
+
 #### queryClient?
 
 `QueryClient`
@@ -84,7 +86,7 @@ function Projects() {
 function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): UseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useInfiniteQuery.ts:78](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L78)
+Defined in: [preact-query/src/useInfiniteQuery.ts:106](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L106)
 
 The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
 `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
@@ -117,6 +119,8 @@ The options for `useInfiniteQuery` are identical to `useQuery`, with the additio
 
 [`UndefinedInitialDataInfiniteOptions`](../type-aliases/UndefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\>
 
+The [UndefinedInitialDataInfiniteOptions](../type-aliases/UndefinedInitialDataInfiniteOptions.md) to use — everything you can pass to `useInfiniteQuery`.
+
 #### queryClient?
 
 `QueryClient`
@@ -132,17 +136,48 @@ The same properties as `useQuery`, with the addition of `data.pages`, `data.page
 `fetchNextPage`, `fetchPreviousPage`, `hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and
 `isFetchingPreviousPage`.
 
+### Example
+
+```tsx
+import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
+
+const projectsOptions = infiniteQueryOptions({
+  queryKey: ['projects'],
+  queryFn: ({ pageParam }) => fetchProjects(pageParam),
+  initialPageParam: 0,
+  getNextPageParam: (lastPage) => lastPage.nextId,
+})
+
+function Projects() {
+  const { data, fetchNextPage, hasNextPage, isFetchingNextPage } =
+    useInfiniteQuery(projectsOptions)
+
+  return (
+    <button
+      onClick={() => fetchNextPage()}
+      disabled={!hasNextPage || isFetchingNextPage}
+    >
+      Load More
+    </button>
+  )
+}
+```
+
 ## Call Signature
 
 ```ts
 function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): UseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useInfiniteQuery.ts:135](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L135)
+Defined in: [preact-query/src/useInfiniteQuery.ts:164](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L164)
 
 The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
 `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
 
+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`.
+
 ### Type Parameters
 
 #### TQueryFnData
@@ -171,6 +206,8 @@ The options for `useInfiniteQuery` are identical to `useQuery`, with the additio
 
 [`UseInfiniteQueryOptions`](../interfaces/UseInfiniteQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\>
 
+The [UseInfiniteQueryOptions](../interfaces/UseInfiniteQueryOptions.md) to use — everything you can pass to `useInfiniteQuery`.
+
 #### queryClient?
 
 `QueryClient`
@@ -186,10 +223,6 @@ The same properties as `useQuery`, with the addition of `data.pages`, `data.page
 `fetchNextPage`, `fetchPreviousPage`, `hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and
 `isFetchingPreviousPage`.
 
-Keep in mind that imperative fetch calls, such as `fetchNextPage`, may interfere with the default refetch
-behaviour, resulting in outdated data. Make sure to call these functions only in response to user actions,
-or add conditions like `hasNextPage && !isFetching`.
-
 ### Example
 
 ```tsx
diff --git a/docs/framework/preact/reference/functions/useIsFetching.md b/docs/framework/preact/reference/functions/useIsFetching.md
index e697a482236..d31f330b99b 100644
--- a/docs/framework/preact/reference/functions/useIsFetching.md
+++ b/docs/framework/preact/reference/functions/useIsFetching.md
@@ -18,7 +18,7 @@ fetching in the background (useful for app-wide loading indicators).
 
 `QueryFilters`\<readonly `unknown`[]\>
 
-QueryFilters
+The QueryFilters to narrow down the matched queries.
 
 ### queryClient?
 
diff --git a/docs/framework/preact/reference/functions/useIsMutating.md b/docs/framework/preact/reference/functions/useIsMutating.md
index ca3a9b76b71..fc3b0ad613d 100644
--- a/docs/framework/preact/reference/functions/useIsMutating.md
+++ b/docs/framework/preact/reference/functions/useIsMutating.md
@@ -18,7 +18,7 @@ Defined in: [preact-query/src/useMutationState.ts:33](https://github.com/TanStac
 
 `MutationFilters`\<`unknown`, `Error`, `unknown`, `unknown`\>
 
-MutationFilters
+The MutationFilters to narrow down the matched mutations.
 
 ### queryClient?
 
diff --git a/docs/framework/preact/reference/functions/useMutation.md b/docs/framework/preact/reference/functions/useMutation.md
index 5b562f16380..3484af95d80 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:82](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useMutation.ts#L82)
+Defined in: [preact-query/src/useMutation.ts:83](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useMutation.ts#L83)
 
 ## Type Parameters
 
@@ -33,6 +33,8 @@ Defined in: [preact-query/src/useMutation.ts:82](https://github.com/TanStack/que
 
 [`UseMutationOptions`](../interfaces/UseMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>
 
+The [UseMutationOptions](../interfaces/UseMutationOptions.md) to use — everything you can pass to `useMutation`.
+
 ### queryClient?
 
 `QueryClient`
diff --git a/docs/framework/preact/reference/functions/useMutationState.md b/docs/framework/preact/reference/functions/useMutationState.md
index 626810d33f3..0a92400c3db 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:139](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useMutationState.ts#L139)
 
 `useMutationState` is a hook that gives you access to all mutations in the `MutationCache`. You can pass
 `filters` to it to narrow down your mutations, and `select` to transform the mutation state.
@@ -31,6 +31,9 @@ the mutation state.
 
 `MutationStateOptions`\<`TResult`, `TMutation`\> = `{}`
 
+The `filters` to narrow down matched mutations, and an optional `select` to transform the
+mutation state.
+
 ### queryClient?
 
 `QueryClient`
diff --git a/docs/framework/preact/reference/functions/usePrefetchInfiniteQuery.md b/docs/framework/preact/reference/functions/usePrefetchInfiniteQuery.md
index d8835ecc75e..d11a14cae59 100644
--- a/docs/framework/preact/reference/functions/usePrefetchInfiniteQuery.md
+++ b/docs/framework/preact/reference/functions/usePrefetchInfiniteQuery.md
@@ -7,7 +7,7 @@ title: usePrefetchInfiniteQuery
 function usePrefetchInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): void;
 ```
 
-Defined in: [preact-query/src/usePrefetchInfiniteQuery.tsx:45](https://github.com/TanStack/query/blob/main/packages/preact-query/src/usePrefetchInfiniteQuery.tsx#L45)
+Defined in: [preact-query/src/usePrefetchInfiniteQuery.tsx:48](https://github.com/TanStack/query/blob/main/packages/preact-query/src/usePrefetchInfiniteQuery.tsx#L48)
 
 `usePrefetchInfiniteQuery` does not return anything, it should be used just to fire a prefetch during render,
 before a suspense boundary that wraps a component that uses `useSuspenseInfiniteQuery`. You can pass
@@ -48,10 +48,15 @@ available.
 
 [`UsePrefetchInfiniteQueryOptions`](../type-aliases/UsePrefetchInfiniteQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\>
 
+The [UsePrefetchInfiniteQueryOptions](../type-aliases/UsePrefetchInfiniteQueryOptions.md) to use — everything you can pass to `queryClient.fetchInfiniteQuery`.
+
 ### queryClient?
 
 `QueryClient`
 
+Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
+be used.
+
 ## Returns
 
 `void`
diff --git a/docs/framework/preact/reference/functions/usePrefetchQuery.md b/docs/framework/preact/reference/functions/usePrefetchQuery.md
index 9f16c64bd7c..3c434dbf13a 100644
--- a/docs/framework/preact/reference/functions/usePrefetchQuery.md
+++ b/docs/framework/preact/reference/functions/usePrefetchQuery.md
@@ -7,7 +7,7 @@ title: usePrefetchQuery
 function usePrefetchQuery<TQueryFnData, TError, TData, TQueryData, TQueryKey>(options, queryClient?): void;
 ```
 
-Defined in: [preact-query/src/usePrefetchQuery.tsx:35](https://github.com/TanStack/query/blob/main/packages/preact-query/src/usePrefetchQuery.tsx#L35)
+Defined in: [preact-query/src/usePrefetchQuery.tsx:38](https://github.com/TanStack/query/blob/main/packages/preact-query/src/usePrefetchQuery.tsx#L38)
 
 `usePrefetchQuery` does not return anything, it should be used just to fire a prefetch during render, before
 a suspense boundary that wraps a component that uses `useSuspenseQuery`. You can pass everything to
@@ -42,10 +42,15 @@ a suspense boundary that wraps a component that uses `useSuspenseQuery`. You can
 
 [`UsePrefetchQueryOptions`](../type-aliases/UsePrefetchQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryData`, `TQueryKey`\>
 
+The [UsePrefetchQueryOptions](../type-aliases/UsePrefetchQueryOptions.md) to use — everything you can pass to `queryClient.fetchQuery`.
+
 ### queryClient?
 
 `QueryClient`
 
+Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
+be used.
+
 ## Returns
 
 `void`
diff --git a/docs/framework/preact/reference/functions/useQueries.md b/docs/framework/preact/reference/functions/useQueries.md
index 49f375e8444..8b64636a918 100644
--- a/docs/framework/preact/reference/functions/useQueries.md
+++ b/docs/framework/preact/reference/functions/useQueries.md
@@ -39,15 +39,23 @@ be structurally shared to be as referentially stable as possible.
 
 (`result`) => `TCombinedResult`
 
+Use this to combine the results of the queries into a single value. The result will be structurally
+shared to be as referentially stable as possible.
+
 #### queries
 
   \| readonly \[`T` *extends* \[\] ? \[\] : `T` *extends* \[`Head`\] ? \[`GetUseQueryOptionsForUseQueries`\<`Head`\>\] : `T` *extends* \[`Head`, `...Tails[]`\] ? \[`...Tails[]`\] *extends* \[\] ? \[\] : \[`...Tails[]`\] *extends* \[`Head`\] ? \[`GetUseQueryOptionsForUseQueries`\<`Head`\>, `GetUseQueryOptionsForUseQueries`\<`Head`\>\] : \[`...Tails[]`\] *extends* \[`Head`, `...Tails[]`\] ? \[`...(...)[]`\] *extends* \[\] ? \[\] : ... *extends* ... ? ... : ... : readonly ...[] *extends* \[`...(...)[]`\] ? \[`...(...)[]`\] : ... *extends* ... ? ... : ... : readonly `unknown`[] *extends* `T` ? `T` : `T` *extends* `UseQueryOptionsForUseQueries`\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>[] ? `UseQueryOptionsForUseQueries`\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>[] : `UseQueryOptionsForUseQueries`\<`unknown`, `Error`, `unknown`, readonly ...[]\>[]\]
   \| readonly \[\{ \[K in string \| number \| symbol\]: GetUseQueryOptionsForUseQueries\<T\[K\<K\>\]\> \}\]
 
+An array with query option objects identical to `useQuery` (excluding the `queryClient` option, since
+the `QueryClient` can be passed in on the top level).
+
 #### subscribed?
 
 `boolean`
 
+Set this to `false` to unsubscribe this observer from updates to the query cache. Defaults to `true`.
+
 ### queryClient?
 
 `QueryClient`
diff --git a/docs/framework/preact/reference/functions/useQuery.md b/docs/framework/preact/reference/functions/useQuery.md
index dd882a88694..989665a7592 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:40](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L40)
+Defined in: [preact-query/src/useQuery.ts:41](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L41)
 
 This overload is selected when `initialData` is set, so the resulting `data` is never `undefined`.
 
@@ -37,6 +37,8 @@ This overload is selected when `initialData` is set, so the resulting `data` is
 
 [`DefinedInitialDataOptions`](../type-aliases/DefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
 
+The [DefinedInitialDataOptions](../type-aliases/DefinedInitialDataOptions.md) to use — everything you can pass to `useQuery`, with `initialData` set.
+
 #### queryClient?
 
 `QueryClient`
@@ -75,7 +77,7 @@ function Posts() {
 function useQuery<TQueryFnData, TError, TData, TQueryKey>(options, queryClient?): UseQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useQuery.ts:57](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L57)
+Defined in: [preact-query/src/useQuery.ts:85](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L85)
 
 ### Type Parameters
 
@@ -101,6 +103,8 @@ Defined in: [preact-query/src/useQuery.ts:57](https://github.com/TanStack/query/
 
 [`UndefinedInitialDataOptions`](../type-aliases/UndefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
 
+The [UndefinedInitialDataOptions](../type-aliases/UndefinedInitialDataOptions.md) to use — everything you can pass to `useQuery`.
+
 #### queryClient?
 
 `QueryClient`
@@ -116,13 +120,40 @@ The current query result. `status` is `pending` if there is no cached data and n
 has finished yet, `error` if the query attempt resulted in an error, or `success` if the query has data to
 display. `isPending`/`isSuccess`/`isError` are derived booleans for convenience.
 
+### Example
+
+```tsx
+import { queryOptions, useQuery } from '@tanstack/preact-query'
+
+const postsOptions = queryOptions({
+  queryKey: ['posts'],
+  queryFn: fetchPosts,
+})
+
+function Posts() {
+  const { status, data, error, isFetching } = useQuery(postsOptions)
+
+  if (status === 'pending') return 'Loading...'
+  if (status === 'error') return <span>Error: {error.message}</span>
+
+  return (
+    <div>
+      {data.map((post) => (
+        <p key={post.id}>{post.title}</p>
+      ))}
+      <div>{isFetching ? 'Background Updating...' : ' '}</div>
+    </div>
+  )
+}
+```
+
 ## Call Signature
 
 ```ts
 function useQuery<TQueryFnData, TError, TData, TQueryKey>(options, queryClient?): UseQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useQuery.ts:137](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L137)
+Defined in: [preact-query/src/useQuery.ts:166](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L166)
 
 ### Type Parameters
 
@@ -148,6 +179,8 @@ Defined in: [preact-query/src/useQuery.ts:137](https://github.com/TanStack/query
 
 [`UseQueryOptions`](../interfaces/UseQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
 
+The [UseQueryOptions](../interfaces/UseQueryOptions.md) to use — everything you can pass to `useQuery`.
+
 #### queryClient?
 
 `QueryClient`
diff --git a/docs/framework/preact/reference/functions/useSuspenseInfiniteQuery.md b/docs/framework/preact/reference/functions/useSuspenseInfiniteQuery.md
index 551dd4035ee..543ab2a184e 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:63](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseInfiniteQuery.ts#L63)
+Defined in: [preact-query/src/useSuspenseInfiniteQuery.ts:66](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseInfiniteQuery.ts#L66)
 
 The options for `useSuspenseInfiniteQuery` are the same as for `useInfiniteQuery`, except for `throwOnError`,
 `enabled`, and `placeholderData`.
@@ -40,10 +40,15 @@ The options for `useSuspenseInfiniteQuery` are the same as for `useInfiniteQuery
 
 [`UseSuspenseInfiniteQueryOptions`](../interfaces/UseSuspenseInfiniteQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\>
 
+The [UseSuspenseInfiniteQueryOptions](../interfaces/UseSuspenseInfiniteQueryOptions.md) to use — the same options as `useInfiniteQuery`, minus the ones listed above.
+
 ### queryClient?
 
 `QueryClient`
 
+Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
+be used.
+
 ## Returns
 
 [`UseSuspenseInfiniteQueryResult`](../type-aliases/UseSuspenseInfiniteQueryResult.md)\<`TData`, `TError`\>
diff --git a/docs/framework/preact/reference/functions/useSuspenseQueries.md b/docs/framework/preact/reference/functions/useSuspenseQueries.md
index 8281abc2294..50b61d6d38c 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:211](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseQueries.ts#L211)
+Defined in: [preact-query/src/useSuspenseQueries.ts:212](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseQueries.ts#L212)
 
 The options for `useSuspenseQueries` are the same as for `useQueries`, except that each `query` can't have
 `throwOnError`, `enabled`, or `placeholderData`.
@@ -28,15 +28,22 @@ The options for `useSuspenseQueries` are the same as for `useQueries`, except th
 
 #### options
 
+The `queries` array to run in Suspense, and an optional `combine` function.
+
 ##### combine?
 
 (`result`) => `TCombinedResult`
 
+Use this to combine the results of the queries into a single value. The result will be structurally
+shared to be as referentially stable as possible.
+
 ##### queries
 
   \| readonly \[`T` *extends* \[\] ? \[\] : `T` *extends* \[`Head`\] ? \[`GetUseSuspenseQueryOptions`\<`Head`\>\] : `T` *extends* \[`Head`, `...Tails[]`\] ? \[`...Tails[]`\] *extends* \[\] ? \[\] : \[`...Tails[]`\] *extends* \[`Head`\] ? \[`GetUseSuspenseQueryOptions`\<`Head`\>, `GetUseSuspenseQueryOptions`\<`Head`\>\] : \[`...Tails[]`\] *extends* \[`Head`, `...Tails[]`\] ? \[`...(...)[]`\] *extends* \[\] ? \[\] : ... *extends* ... ? ... : ... : ...[] *extends* \[`...(...)[]`\] ? \[`...(...)[]`\] : ... *extends* ... ? ... : ... : `unknown`[] *extends* `T` ? `T` : `T` *extends* [`UseSuspenseQueryOptions`](../interfaces/UseSuspenseQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>[] ? [`UseSuspenseQueryOptions`](../interfaces/UseSuspenseQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>[] : [`UseSuspenseQueryOptions`](../interfaces/UseSuspenseQueryOptions.md)\<`unknown`, `Error`, `unknown`, readonly ...[]\>[]\]
   \| readonly \[\{ \[K in string \| number \| symbol\]: GetUseSuspenseQueryOptions\<T\[K\<K\>\]\> \}\]
 
+An array with query option objects identical to `useSuspenseQuery`.
+
 #### queryClient?
 
 `QueryClient`
@@ -95,7 +102,7 @@ function App() {
 function useSuspenseQueries<T, TCombinedResult>(options, queryClient?): TCombinedResult;
 ```
 
-Defined in: [preact-query/src/useSuspenseQueries.ts:270](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseQueries.ts#L270)
+Defined in: [preact-query/src/useSuspenseQueries.ts:279](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseQueries.ts#L279)
 
 The options for `useSuspenseQueries` are the same as for `useQueries`, except that each `query` can't have
 `throwOnError`, `enabled`, or `placeholderData`.
@@ -114,14 +121,21 @@ The options for `useSuspenseQueries` are the same as for `useQueries`, except th
 
 #### options
 
+The `queries` array to run in Suspense, and an optional `combine` function.
+
 ##### combine?
 
 (`result`) => `TCombinedResult`
 
+Use this to combine the results of the queries into a single value. The result will be structurally
+shared to be as referentially stable as possible.
+
 ##### queries
 
 readonly \[`T` *extends* \[\] ? \[\] : `T` *extends* \[`Head`\] ? \[`GetUseSuspenseQueryOptions`\<`Head`\>\] : `T` *extends* \[`Head`, `...Tails[]`\] ? \[`...Tails[]`\] *extends* \[\] ? \[\] : \[`...Tails[]`\] *extends* \[`Head`\] ? \[`GetUseSuspenseQueryOptions`\<`Head`\>, `GetUseSuspenseQueryOptions`\<`Head`\>\] : \[`...Tails[]`\] *extends* \[`Head`, `...Tails[]`\] ? \[`...Tails[]`\] *extends* \[\] ? \[\] : \[`...(...)[]`\] *extends* \[...\] ? \[..., ..., ...\] : ... *extends* ... ? ... : ... : `unknown`[] *extends* \[`...Tails[]`\] ? \[`...Tails[]`\] : \[`...(...)[]`\] *extends* ...[] ? ...[] : ...[] : `unknown`[] *extends* `T` ? `T` : `T` *extends* [`UseSuspenseQueryOptions`](../interfaces/UseSuspenseQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>[] ? [`UseSuspenseQueryOptions`](../interfaces/UseSuspenseQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>[] : [`UseSuspenseQueryOptions`](../interfaces/UseSuspenseQueryOptions.md)\<`unknown`, `Error`, `unknown`, readonly `unknown`[]\>[]\]
 
+An array with query option objects identical to `useSuspenseQuery`.
+
 #### queryClient?
 
 `QueryClient`
diff --git a/docs/framework/preact/reference/functions/useSuspenseQuery.md b/docs/framework/preact/reference/functions/useSuspenseQuery.md
index 027f6a96f62..31dbeabba27 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:48](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseQuery.ts#L48)
+Defined in: [preact-query/src/useSuspenseQuery.ts:51](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useSuspenseQuery.ts#L51)
 
 The options for `useSuspenseQuery` are the same as for `useQuery`, except for `throwOnError`, `enabled`, and
 `placeholderData`.
@@ -36,10 +36,15 @@ The options for `useSuspenseQuery` are the same as for `useQuery`, except for `t
 
 [`UseSuspenseQueryOptions`](../interfaces/UseSuspenseQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
 
+The [UseSuspenseQueryOptions](../interfaces/UseSuspenseQueryOptions.md) to use — the same options as `useQuery`, minus the ones listed above.
+
 ### queryClient?
 
 `QueryClient`
 
+Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
+be used.
+
 ## Returns
 
 [`UseSuspenseQueryResult`](../type-aliases/UseSuspenseQueryResult.md)\<`TData`, `TError`\>
diff --git a/packages/preact-query/src/infiniteQueryOptions.ts b/packages/preact-query/src/infiniteQueryOptions.ts
index 9f4607b61d8..ac4d93f3f2d 100644
--- a/packages/preact-query/src/infiniteQueryOptions.ts
+++ b/packages/preact-query/src/infiniteQueryOptions.ts
@@ -99,6 +99,7 @@ export type DefinedInitialDataInfiniteOptions<
  * This overload is selected when `initialData` is set, so `queryFn` is optional and the resulting `data` is
  * never `undefined`.
  *
+ * @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.
  *
  * @example
@@ -188,6 +189,8 @@ export function infiniteQueryOptions<
  * // Elsewhere, e.g. to warm the cache before rendering `<Comments>`:
  * queryClient.prefetchInfiniteQuery(commentsOptions(postId))
  * ```
+ *
+ * @param options - The {@link UnusedSkipTokenInfiniteOptions} to use — everything you can pass to `useInfiniteQuery`.
  */
 export function infiniteQueryOptions<
   TQueryFnData,
@@ -257,6 +260,8 @@ export function infiniteQueryOptions<
  * // Elsewhere, e.g. to warm the cache before rendering `<Comments>`:
  * queryClient.prefetchInfiniteQuery(commentsOptions(postId))
  * ```
+ *
+ * @param options - The {@link UndefinedInitialDataInfiniteOptions} to use — everything you can pass to `useInfiniteQuery`.
  */
 export function infiniteQueryOptions<
   TQueryFnData,
diff --git a/packages/preact-query/src/mutationOptions.ts b/packages/preact-query/src/mutationOptions.ts
index c61a0067e58..4df1ae05844 100644
--- a/packages/preact-query/src/mutationOptions.ts
+++ b/packages/preact-query/src/mutationOptions.ts
@@ -7,6 +7,9 @@ import type { UseMutationOptions } from './types'
  * `mutationKey` is required on this overload so the mutation can be looked up later, e.g. with
  * `useMutationState`.
  *
+ * @param options - The mutation options to use, identical to what you'd pass to `useMutation`, with a
+ * required `mutationKey`.
+ *
  * @example
  * ```tsx
  * import { mutationOptions, useMutation } from '@tanstack/preact-query'
@@ -60,6 +63,9 @@ export function mutationOptions<
  * `mutationKey` is required on this overload — use this when you don't need to look the mutation up later
  * (e.g. with `useMutationState`).
  *
+ * @param options - The mutation options to use, identical to what you'd pass to `useMutation`, without a
+ * `mutationKey`.
+ *
  * @example
  * ```tsx
  * import { mutationOptions, useMutation } from '@tanstack/preact-query'
diff --git a/packages/preact-query/src/queryOptions.ts b/packages/preact-query/src/queryOptions.ts
index 891a52f0218..3d71f0ac39d 100644
--- a/packages/preact-query/src/queryOptions.ts
+++ b/packages/preact-query/src/queryOptions.ts
@@ -79,6 +79,7 @@ export type DefinedInitialDataOptions<
  * This overload is selected when `initialData` is set, so `queryFn` is optional and the resulting `data` is
  * never `undefined`.
  *
+ * @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.
  *
  * @example
@@ -113,6 +114,7 @@ export function queryOptions<
  * be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and
  * is the query key to generate options for.
  *
+ * @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
@@ -176,6 +178,7 @@ export function queryOptions<
  * be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and
  * is the query key to generate options for.
  *
+ * @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
diff --git a/packages/preact-query/src/useInfiniteQuery.ts b/packages/preact-query/src/useInfiniteQuery.ts
index bfb8873d39e..be86f96bf5b 100644
--- a/packages/preact-query/src/useInfiniteQuery.ts
+++ b/packages/preact-query/src/useInfiniteQuery.ts
@@ -24,6 +24,7 @@ import { useBaseQuery } from './useBaseQuery'
  *
  * This overload is selected when `initialData` is set, so the resulting `data` is never `undefined`.
  *
+ * @param options - The {@link DefinedInitialDataInfiniteOptions} to use — everything you can pass to `useInfiniteQuery`, with `initialData` set.
  * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
  * be used.
  * @returns The same properties as `useQuery`, with the addition of `data.pages`, `data.pageParams`,
@@ -69,11 +70,38 @@ export function useInfiniteQuery<
  * The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
  * `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
  *
+ * @param options - The {@link UndefinedInitialDataInfiniteOptions} to use — everything you can pass to `useInfiniteQuery`.
  * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
  * be used.
  * @returns The same properties as `useQuery`, with the addition of `data.pages`, `data.pageParams`,
  * `fetchNextPage`, `fetchPreviousPage`, `hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and
  * `isFetchingPreviousPage`.
+ *
+ * @example
+ * ```tsx
+ * import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
+ *
+ * const projectsOptions = infiniteQueryOptions({
+ *   queryKey: ['projects'],
+ *   queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *   initialPageParam: 0,
+ *   getNextPageParam: (lastPage) => lastPage.nextId,
+ * })
+ *
+ * function Projects() {
+ *   const { data, fetchNextPage, hasNextPage, isFetchingNextPage } =
+ *     useInfiniteQuery(projectsOptions)
+ *
+ *   return (
+ *     <button
+ *       onClick={() => fetchNextPage()}
+ *       disabled={!hasNextPage || isFetchingNextPage}
+ *     >
+ *       Load More
+ *     </button>
+ *   )
+ * }
+ * ```
  */
 export function useInfiniteQuery<
   TQueryFnData,
@@ -96,16 +124,17 @@ export function useInfiniteQuery<
  * The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
  * `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
  *
+ * 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`.
+ *
+ * @param options - The {@link UseInfiniteQueryOptions} to use — everything you can pass to `useInfiniteQuery`.
  * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
  * be used.
  * @returns The same properties as `useQuery`, with the addition of `data.pages`, `data.pageParams`,
  * `fetchNextPage`, `fetchPreviousPage`, `hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and
  * `isFetchingPreviousPage`.
  *
- * Keep in mind that imperative fetch calls, such as `fetchNextPage`, may interfere with the default refetch
- * behaviour, resulting in outdated data. Make sure to call these functions only in response to user actions,
- * or add conditions like `hasNextPage && !isFetching`.
- *
  * @example
  * ```tsx
  * import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
diff --git a/packages/preact-query/src/useIsFetching.ts b/packages/preact-query/src/useIsFetching.ts
index e75f6ac2596..877cc068aa4 100644
--- a/packages/preact-query/src/useIsFetching.ts
+++ b/packages/preact-query/src/useIsFetching.ts
@@ -9,7 +9,7 @@ import { useSyncExternalStore } from './utils'
  * `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).
  *
- * @param filters - {@link QueryFilters}
+ * @param filters - The {@link QueryFilters} to narrow down the matched queries.
  * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
  * be used.
  * @returns Will be the `number` of the queries that your application is currently loading or fetching in the
diff --git a/packages/preact-query/src/useMutation.ts b/packages/preact-query/src/useMutation.ts
index 8cd8af38042..84d73167e9c 100644
--- a/packages/preact-query/src/useMutation.ts
+++ b/packages/preact-query/src/useMutation.ts
@@ -18,6 +18,7 @@ import { useSyncExternalStore } from './utils'
 // HOOK
 
 /**
+ * @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.
  * @returns `mutate`/`mutateAsync` also accept per-call `onSuccess`/`onError`/`onSettled` callbacks as a second
diff --git a/packages/preact-query/src/useMutationState.ts b/packages/preact-query/src/useMutationState.ts
index 6919bfb832d..a10bf1c33a7 100644
--- a/packages/preact-query/src/useMutationState.ts
+++ b/packages/preact-query/src/useMutationState.ts
@@ -15,7 +15,7 @@ import { useSyncExternalStore } from './utils'
  * `useIsMutating` is an optional hook that returns the `number` of mutations that your application is fetching
  * (useful for app-wide loading indicators).
  *
- * @param filters - {@link MutationFilters}
+ * @param filters - The {@link MutationFilters} to narrow down the matched mutations.
  * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
  * be used.
  * @returns Will be the `number` of the mutations that your application is currently fetching.
@@ -86,6 +86,8 @@ function getResult<
  * `options.filters` narrows down the matched mutations ({@link MutationFilters}), and `options.select` transforms
  * the mutation state.
  *
+ * @param options - The `filters` to narrow down matched mutations, and an optional `select` to transform the
+ * mutation state.
  * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
  * be used.
  * @returns Will be an Array of whatever `select` returns for each matching mutation.
diff --git a/packages/preact-query/src/usePrefetchInfiniteQuery.tsx b/packages/preact-query/src/usePrefetchInfiniteQuery.tsx
index f0f286e7d39..f504e8faaa1 100644
--- a/packages/preact-query/src/usePrefetchInfiniteQuery.tsx
+++ b/packages/preact-query/src/usePrefetchInfiniteQuery.tsx
@@ -16,6 +16,9 @@ import type { UsePrefetchInfiniteQueryOptions } from './types'
  * optional parameter to your query function. Return `undefined` or `null` to indicate there is no next page
  * available.
  *
+ * @param options - The {@link UsePrefetchInfiniteQueryOptions} to use — everything you can pass to `queryClient.fetchInfiniteQuery`.
+ * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
+ * be used.
  * @returns `void` — nothing is returned.
  *
  * @example
diff --git a/packages/preact-query/src/usePrefetchQuery.tsx b/packages/preact-query/src/usePrefetchQuery.tsx
index 893707e676e..f079c378960 100644
--- a/packages/preact-query/src/usePrefetchQuery.tsx
+++ b/packages/preact-query/src/usePrefetchQuery.tsx
@@ -10,6 +10,9 @@ import type { UsePrefetchQueryOptions } from './types'
  * `usePrefetchQuery` that you can pass to `queryClient.fetchQuery`, though `queryKey` is always required, and
  * `queryFn` is required unless a default query function has been defined.
  *
+ * @param options - The {@link UsePrefetchQueryOptions} to use — everything you can pass to `queryClient.fetchQuery`.
+ * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
+ * be used.
  * @returns `void` — nothing is returned.
  *
  * @example
diff --git a/packages/preact-query/src/useQueries.ts b/packages/preact-query/src/useQueries.ts
index 4709b971a95..0cdd0e76a19 100644
--- a/packages/preact-query/src/useQueries.ts
+++ b/packages/preact-query/src/useQueries.ts
@@ -261,10 +261,21 @@ export function useQueries<
     queries,
     ...options
   }: {
+    /**
+     * An array with query option objects identical to `useQuery` (excluding the `queryClient` option, since
+     * the `QueryClient` can be passed in on the top level).
+     */
     queries:
       | readonly [...QueriesOptions<T>]
       | readonly [...{ [K in keyof T]: GetUseQueryOptionsForUseQueries<T[K]> }]
+    /**
+     * Use this to combine the results of the queries into a single value. The result will be structurally
+     * shared to be as referentially stable as possible.
+     */
     combine?: (result: QueriesResults<T>) => TCombinedResult
+    /**
+     * Set this to `false` to unsubscribe this observer from updates to the query cache. Defaults to `true`.
+     */
     subscribed?: boolean
   },
   queryClient?: QueryClient,
diff --git a/packages/preact-query/src/useQuery.ts b/packages/preact-query/src/useQuery.ts
index 6c0baba6c71..3b9a8da0322 100644
--- a/packages/preact-query/src/useQuery.ts
+++ b/packages/preact-query/src/useQuery.ts
@@ -15,6 +15,7 @@ import { useBaseQuery } from './useBaseQuery'
 /**
  * This overload is selected when `initialData` is set, so the resulting `data` is never `undefined`.
  *
+ * @param options - The {@link DefinedInitialDataOptions} to use — everything you can pass to `useQuery`, with `initialData` set.
  * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
  * be used.
  * @returns The current query result. `status` is `pending` if there is no cached data and no query attempt
@@ -48,11 +49,38 @@ export function useQuery<
 ): DefinedUseQueryResult<TData, TError>
 
 /**
+ * @param options - The {@link UndefinedInitialDataOptions} to use — everything you can pass to `useQuery`.
  * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
  * be used.
  * @returns The current query result. `status` is `pending` if there is no cached data and no query attempt
  * has finished yet, `error` if the query attempt resulted in an error, or `success` if the query has data to
  * display. `isPending`/`isSuccess`/`isError` are derived booleans for convenience.
+ *
+ * @example
+ * ```tsx
+ * import { queryOptions, useQuery } from '@tanstack/preact-query'
+ *
+ * const postsOptions = queryOptions({
+ *   queryKey: ['posts'],
+ *   queryFn: fetchPosts,
+ * })
+ *
+ * function Posts() {
+ *   const { status, data, error, isFetching } = useQuery(postsOptions)
+ *
+ *   if (status === 'pending') return 'Loading...'
+ *   if (status === 'error') return <span>Error: {error.message}</span>
+ *
+ *   return (
+ *     <div>
+ *       {data.map((post) => (
+ *         <p key={post.id}>{post.title}</p>
+ *       ))}
+ *       <div>{isFetching ? 'Background Updating...' : ' '}</div>
+ *     </div>
+ *   )
+ * }
+ * ```
  */
 export function useQuery<
   TQueryFnData = unknown,
@@ -65,6 +93,7 @@ export function useQuery<
 ): UseQueryResult<TData, TError>
 
 /**
+ * @param options - The {@link UseQueryOptions} to use — everything you can pass to `useQuery`.
  * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
  * be used.
  * @returns The current query result. `status` is `pending` if there is no cached data and no query attempt
diff --git a/packages/preact-query/src/useSuspenseInfiniteQuery.ts b/packages/preact-query/src/useSuspenseInfiniteQuery.ts
index f7e683741f3..61d6301820e 100644
--- a/packages/preact-query/src/useSuspenseInfiniteQuery.ts
+++ b/packages/preact-query/src/useSuspenseInfiniteQuery.ts
@@ -19,6 +19,9 @@ import { useBaseQuery } from './useBaseQuery'
  * The options for `useSuspenseInfiniteQuery` are the same as for `useInfiniteQuery`, except for `throwOnError`,
  * `enabled`, and `placeholderData`.
  *
+ * @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.
  * @returns The same object as `useInfiniteQuery`, except that `data` is guaranteed to be defined,
  * `isPlaceholderData` is missing, and `status` is either `success` or `error` (with the derived flags set
  * accordingly).
diff --git a/packages/preact-query/src/useSuspenseQueries.ts b/packages/preact-query/src/useSuspenseQueries.ts
index c29688a7c63..64b98fc855d 100644
--- a/packages/preact-query/src/useSuspenseQueries.ts
+++ b/packages/preact-query/src/useSuspenseQueries.ts
@@ -166,6 +166,7 @@ export type SuspenseQueriesResults<
  * The options for `useSuspenseQueries` are the same as for `useQueries`, except that each `query` can't have
  * `throwOnError`, `enabled`, or `placeholderData`.
  *
+ * @param options - The `queries` array to run in Suspense, and an optional `combine` function.
  * @param queryClient - Use this to provide a custom QueryClient. Otherwise, the one from the nearest context
  * will be used.
  * @returns The same structure as `useQueries`, except that for each `query`, `data` is guaranteed to be
@@ -213,9 +214,16 @@ export function useSuspenseQueries<
   TCombinedResult = SuspenseQueriesResults<T>,
 >(
   options: {
+    /**
+     * An array with query option objects identical to `useSuspenseQuery`.
+     */
     queries:
       | readonly [...SuspenseQueriesOptions<T>]
       | readonly [...{ [K in keyof T]: GetUseSuspenseQueryOptions<T[K]> }]
+    /**
+     * Use this to combine the results of the queries into a single value. The result will be structurally
+     * shared to be as referentially stable as possible.
+     */
     combine?: (result: SuspenseQueriesResults<T>) => TCombinedResult
   },
   queryClient?: QueryClient,
@@ -225,6 +233,7 @@ export function useSuspenseQueries<
  * The options for `useSuspenseQueries` are the same as for `useQueries`, except that each `query` can't have
  * `throwOnError`, `enabled`, or `placeholderData`.
  *
+ * @param options - The `queries` array to run in Suspense, and an optional `combine` function.
  * @param queryClient - Use this to provide a custom QueryClient. Otherwise, the one from the nearest context
  * will be used.
  * @returns The same structure as `useQueries`, except that for each `query`, `data` is guaranteed to be
@@ -272,7 +281,14 @@ export function useSuspenseQueries<
   TCombinedResult = SuspenseQueriesResults<T>,
 >(
   options: {
+    /**
+     * An array with query option objects identical to `useSuspenseQuery`.
+     */
     queries: readonly [...SuspenseQueriesOptions<T>]
+    /**
+     * Use this to combine the results of the queries into a single value. The result will be structurally
+     * shared to be as referentially stable as possible.
+     */
     combine?: (result: SuspenseQueriesResults<T>) => TCombinedResult
   },
   queryClient?: QueryClient,
diff --git a/packages/preact-query/src/useSuspenseQuery.ts b/packages/preact-query/src/useSuspenseQuery.ts
index 22798536c54..71576c758db 100644
--- a/packages/preact-query/src/useSuspenseQuery.ts
+++ b/packages/preact-query/src/useSuspenseQuery.ts
@@ -9,6 +9,9 @@ import { useBaseQuery } from './useBaseQuery'
  * The options for `useSuspenseQuery` are the same as for `useQuery`, except for `throwOnError`, `enabled`, and
  * `placeholderData`.
  *
+ * @param options - The {@link UseSuspenseQueryOptions} to use — the same options as `useQuery`, minus the ones listed above.
+ * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
+ * be used.
  * @returns The same object as `useQuery`, except that `data` is guaranteed to be defined, `isPlaceholderData`
  * is missing, and `status` is either `success` or `error` (with the derived flags set accordingly).
  *

From 47c02aaf6cc0ae7cd476cd1f66c07a43c889e7d4 Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Tue, 25 Aug 2026 02:01:37 +0900
Subject: [PATCH 18/28] docs(preact-query): describe children props and
 low-level context exports

---
 .../preact/reference/functions/HydrationBoundary.md       | 2 +-
 .../preact/reference/functions/QueryClientProvider.md     | 2 +-
 .../preact/reference/functions/useQueryClient.md          | 2 +-
 .../preact/reference/interfaces/HydrationBoundaryProps.md | 6 ++++--
 .../reference/type-aliases/QueryClientProviderProps.md    | 8 +++++---
 .../preact/reference/variables/IsRestoringProvider.md     | 5 ++++-
 .../preact/reference/variables/QueryClientContext.md      | 4 +++-
 packages/preact-query/src/HydrationBoundary.tsx           | 3 +++
 packages/preact-query/src/IsRestoringProvider.ts          | 5 +++++
 packages/preact-query/src/QueryClientProvider.tsx         | 6 ++++++
 10 files changed, 33 insertions(+), 10 deletions(-)

diff --git a/docs/framework/preact/reference/functions/HydrationBoundary.md b/docs/framework/preact/reference/functions/HydrationBoundary.md
index 460c2b55748..77977535602 100644
--- a/docs/framework/preact/reference/functions/HydrationBoundary.md
+++ b/docs/framework/preact/reference/functions/HydrationBoundary.md
@@ -7,7 +7,7 @@ title: HydrationBoundary
 function HydrationBoundary(__namedParameters): Element;
 ```
 
-Defined in: [preact-query/src/HydrationBoundary.tsx:72](https://github.com/TanStack/query/blob/main/packages/preact-query/src/HydrationBoundary.tsx#L72)
+Defined in: [preact-query/src/HydrationBoundary.tsx:75](https://github.com/TanStack/query/blob/main/packages/preact-query/src/HydrationBoundary.tsx#L75)
 
 `HydrationBoundary` adds a previously dehydrated state into the `queryClient` that would be returned by
 `useQueryClient()`. If the client already contains data, the new queries will be intelligently merged based on
diff --git a/docs/framework/preact/reference/functions/QueryClientProvider.md b/docs/framework/preact/reference/functions/QueryClientProvider.md
index d7c5423ce0f..cf336475452 100644
--- a/docs/framework/preact/reference/functions/QueryClientProvider.md
+++ b/docs/framework/preact/reference/functions/QueryClientProvider.md
@@ -7,7 +7,7 @@ title: QueryClientProvider
 function QueryClientProvider(__namedParameters): VNode;
 ```
 
-Defined in: [preact-query/src/QueryClientProvider.tsx:55](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryClientProvider.tsx#L55)
+Defined in: [preact-query/src/QueryClientProvider.tsx:61](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryClientProvider.tsx#L61)
 
 Use the `QueryClientProvider` component to connect and provide a `QueryClient` to your application.
 
diff --git a/docs/framework/preact/reference/functions/useQueryClient.md b/docs/framework/preact/reference/functions/useQueryClient.md
index d750430a6f3..65c02ea6531 100644
--- a/docs/framework/preact/reference/functions/useQueryClient.md
+++ b/docs/framework/preact/reference/functions/useQueryClient.md
@@ -7,7 +7,7 @@ title: useQueryClient
 function useQueryClient(queryClient?): QueryClient;
 ```
 
-Defined in: [preact-query/src/QueryClientProvider.tsx:17](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryClientProvider.tsx#L17)
+Defined in: [preact-query/src/QueryClientProvider.tsx:20](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryClientProvider.tsx#L20)
 
 The `useQueryClient` hook returns the current `QueryClient` instance.
 
diff --git a/docs/framework/preact/reference/interfaces/HydrationBoundaryProps.md b/docs/framework/preact/reference/interfaces/HydrationBoundaryProps.md
index e7bc72ec8d3..418680c1c09 100644
--- a/docs/framework/preact/reference/interfaces/HydrationBoundaryProps.md
+++ b/docs/framework/preact/reference/interfaces/HydrationBoundaryProps.md
@@ -13,7 +13,9 @@ Defined in: [preact-query/src/HydrationBoundary.tsx:14](https://github.com/TanSt
 optional children: ComponentChildren;
 ```
 
-Defined in: [preact-query/src/HydrationBoundary.tsx:28](https://github.com/TanStack/query/blob/main/packages/preact-query/src/HydrationBoundary.tsx#L28)
+Defined in: [preact-query/src/HydrationBoundary.tsx:31](https://github.com/TanStack/query/blob/main/packages/preact-query/src/HydrationBoundary.tsx#L31)
+
+The components that render once the dehydrated state has been hydrated into the cache.
 
 ***
 
@@ -44,7 +46,7 @@ optional defaultOptions: OmitKeyof<{
 optional queryClient: QueryClient;
 ```
 
-Defined in: [preact-query/src/HydrationBoundary.tsx:32](https://github.com/TanStack/query/blob/main/packages/preact-query/src/HydrationBoundary.tsx#L32)
+Defined in: [preact-query/src/HydrationBoundary.tsx:35](https://github.com/TanStack/query/blob/main/packages/preact-query/src/HydrationBoundary.tsx#L35)
 
 Use this to use a custom QueryClient. Otherwise, the one from the nearest context will be used.
 
diff --git a/docs/framework/preact/reference/type-aliases/QueryClientProviderProps.md b/docs/framework/preact/reference/type-aliases/QueryClientProviderProps.md
index 07eb00de464..9600b35e30f 100644
--- a/docs/framework/preact/reference/type-aliases/QueryClientProviderProps.md
+++ b/docs/framework/preact/reference/type-aliases/QueryClientProviderProps.md
@@ -7,7 +7,7 @@ title: QueryClientProviderProps
 type QueryClientProviderProps = object;
 ```
 
-Defined in: [preact-query/src/QueryClientProvider.tsx:31](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryClientProvider.tsx#L31)
+Defined in: [preact-query/src/QueryClientProvider.tsx:34](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryClientProvider.tsx#L34)
 
 ## Properties
 
@@ -17,7 +17,9 @@ Defined in: [preact-query/src/QueryClientProvider.tsx:31](https://github.com/Tan
 optional children: ComponentChildren;
 ```
 
-Defined in: [preact-query/src/QueryClientProvider.tsx:38](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryClientProvider.tsx#L38)
+Defined in: [preact-query/src/QueryClientProvider.tsx:44](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryClientProvider.tsx#L44)
+
+The components that get access to the provided QueryClient.
 
 ***
 
@@ -27,7 +29,7 @@ Defined in: [preact-query/src/QueryClientProvider.tsx:38](https://github.com/Tan
 client: QueryClient;
 ```
 
-Defined in: [preact-query/src/QueryClientProvider.tsx:37](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryClientProvider.tsx#L37)
+Defined in: [preact-query/src/QueryClientProvider.tsx:40](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryClientProvider.tsx#L40)
 
 **Required**
 
diff --git a/docs/framework/preact/reference/variables/IsRestoringProvider.md b/docs/framework/preact/reference/variables/IsRestoringProvider.md
index 895ae6eb25c..42069e45fc2 100644
--- a/docs/framework/preact/reference/variables/IsRestoringProvider.md
+++ b/docs/framework/preact/reference/variables/IsRestoringProvider.md
@@ -7,4 +7,7 @@ title: IsRestoringProvider
 const IsRestoringProvider: Provider<boolean> = IsRestoringContext.Provider;
 ```
 
-Defined in: [preact-query/src/IsRestoringProvider.ts:14](https://github.com/TanStack/query/blob/main/packages/preact-query/src/IsRestoringProvider.ts#L14)
+Defined in: [preact-query/src/IsRestoringProvider.ts:19](https://github.com/TanStack/query/blob/main/packages/preact-query/src/IsRestoringProvider.ts#L19)
+
+The Provider that `PersistQueryClientProvider` uses to signal whether a persisted client is currently
+being restored, read by `useIsRestoring`.
diff --git a/docs/framework/preact/reference/variables/QueryClientContext.md b/docs/framework/preact/reference/variables/QueryClientContext.md
index ea5b0b07085..fa7a465d171 100644
--- a/docs/framework/preact/reference/variables/QueryClientContext.md
+++ b/docs/framework/preact/reference/variables/QueryClientContext.md
@@ -7,4 +7,6 @@ title: QueryClientContext
 const QueryClientContext: Context<QueryClient | undefined>;
 ```
 
-Defined in: [preact-query/src/QueryClientProvider.tsx:6](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryClientProvider.tsx#L6)
+Defined in: [preact-query/src/QueryClientProvider.tsx:9](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryClientProvider.tsx#L9)
+
+The context that `useQueryClient` reads from. `QueryClientProvider` is the normal way to set it.
diff --git a/packages/preact-query/src/HydrationBoundary.tsx b/packages/preact-query/src/HydrationBoundary.tsx
index e5b5dcfaed7..53e7effcc92 100644
--- a/packages/preact-query/src/HydrationBoundary.tsx
+++ b/packages/preact-query/src/HydrationBoundary.tsx
@@ -25,6 +25,9 @@ export interface HydrationBoundaryProps {
       'mutations'
     >
   }
+  /**
+   * The components that render once the dehydrated state has been hydrated into the cache.
+   */
   children?: ComponentChildren
   /**
    * Use this to use a custom QueryClient. Otherwise, the one from the nearest context will be used.
diff --git a/packages/preact-query/src/IsRestoringProvider.ts b/packages/preact-query/src/IsRestoringProvider.ts
index 84d55326a1d..e2c240eba3d 100644
--- a/packages/preact-query/src/IsRestoringProvider.ts
+++ b/packages/preact-query/src/IsRestoringProvider.ts
@@ -11,4 +11,9 @@ const IsRestoringContext = createContext(false)
  * @returns `true` while a persisted client is being restored, `false` otherwise.
  */
 export const useIsRestoring = () => useContext(IsRestoringContext)
+
+/**
+ * The Provider that `PersistQueryClientProvider` uses to signal whether a persisted client is currently
+ * being restored, read by `useIsRestoring`.
+ */
 export const IsRestoringProvider = IsRestoringContext.Provider
diff --git a/packages/preact-query/src/QueryClientProvider.tsx b/packages/preact-query/src/QueryClientProvider.tsx
index eb1ad3d3fe6..147c04da82b 100644
--- a/packages/preact-query/src/QueryClientProvider.tsx
+++ b/packages/preact-query/src/QueryClientProvider.tsx
@@ -3,6 +3,9 @@ import { createContext } from 'preact'
 import type { ComponentChildren, VNode } from 'preact'
 import { useContext, useEffect } from 'preact/hooks'
 
+/**
+ * The context that `useQueryClient` reads from. `QueryClientProvider` is the normal way to set it.
+ */
 export const QueryClientContext = createContext<QueryClient | undefined>(
   undefined,
 )
@@ -35,6 +38,9 @@ export type QueryClientProviderProps = {
    * The QueryClient instance to provide.
    */
   client: QueryClient
+  /**
+   * The components that get access to the provided QueryClient.
+   */
   children?: ComponentChildren
 }
 

From bfc047513f74a4acaafb5d261bc6a9a186a02c15 Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Tue, 25 Aug 2026 02:05:59 +0900
Subject: [PATCH 19/28] fix(preact-query): remove inaccurate 'queryFn is
 optional' claim from infiniteQueryOptions overload

---
 .../preact/reference/functions/infiniteQueryOptions.md   | 9 ++++-----
 packages/preact-query/src/infiniteQueryOptions.ts        | 3 +--
 2 files changed, 5 insertions(+), 7 deletions(-)

diff --git a/docs/framework/preact/reference/functions/infiniteQueryOptions.md b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
index 3cc47a1369b..7d9b84b6caf 100644
--- a/docs/framework/preact/reference/functions/infiniteQueryOptions.md
+++ b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
@@ -9,14 +9,13 @@ 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:124](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L124)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:123](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L123)
 
 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`.
 `options.queryKey` is required and is the query key to generate options for.
 
-This overload is selected when `initialData` is set, so `queryFn` is optional and the resulting `data` is
-never `undefined`.
+This overload is selected when `initialData` is set, so the resulting `data` is never `undefined`.
 
 ### Type Parameters
 
@@ -78,7 +77,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:195](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L195)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:194](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L194)
 
 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`.
@@ -163,7 +162,7 @@ queryClient.prefetchInfiniteQuery(commentsOptions(postId))
 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:266](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L266)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:265](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L265)
 
 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/packages/preact-query/src/infiniteQueryOptions.ts b/packages/preact-query/src/infiniteQueryOptions.ts
index ac4d93f3f2d..e987c8969ec 100644
--- a/packages/preact-query/src/infiniteQueryOptions.ts
+++ b/packages/preact-query/src/infiniteQueryOptions.ts
@@ -96,8 +96,7 @@ export type DefinedInitialDataInfiniteOptions<
  * These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
  * `options.queryKey` is required and is the query key to generate options for.
  *
- * This overload is selected when `initialData` is set, so `queryFn` is optional and the resulting `data` is
- * never `undefined`.
+ * This overload is selected when `initialData` is set, so the resulting `data` is never `undefined`.
  *
  * @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.

From 13cf7ba6cfad8f40b3a1e94a059fd4a84d5bdbd4 Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Tue, 25 Aug 2026 02:10:12 +0900
Subject: [PATCH 20/28] docs(preact-query): add missing @returns to
 mutationOptions overloads and provider components

---
 .../preact/reference/functions/HydrationBoundary.md       | 4 +++-
 .../preact/reference/functions/QueryClientProvider.md     | 4 +++-
 .../preact/reference/functions/QueryErrorResetBoundary.md | 5 ++++-
 .../preact/reference/functions/mutationOptions.md         | 8 ++++++--
 packages/preact-query/src/HydrationBoundary.tsx           | 2 ++
 packages/preact-query/src/QueryClientProvider.tsx         | 2 ++
 packages/preact-query/src/QueryErrorResetBoundary.tsx     | 3 +++
 packages/preact-query/src/mutationOptions.ts              | 2 ++
 8 files changed, 25 insertions(+), 5 deletions(-)

diff --git a/docs/framework/preact/reference/functions/HydrationBoundary.md b/docs/framework/preact/reference/functions/HydrationBoundary.md
index 77977535602..64d64e83b97 100644
--- a/docs/framework/preact/reference/functions/HydrationBoundary.md
+++ b/docs/framework/preact/reference/functions/HydrationBoundary.md
@@ -7,7 +7,7 @@ title: HydrationBoundary
 function HydrationBoundary(__namedParameters): Element;
 ```
 
-Defined in: [preact-query/src/HydrationBoundary.tsx:75](https://github.com/TanStack/query/blob/main/packages/preact-query/src/HydrationBoundary.tsx#L75)
+Defined in: [preact-query/src/HydrationBoundary.tsx:77](https://github.com/TanStack/query/blob/main/packages/preact-query/src/HydrationBoundary.tsx#L77)
 
 `HydrationBoundary` adds a previously dehydrated state into the `queryClient` that would be returned by
 `useQueryClient()`. If the client already contains data, the new queries will be intelligently merged based on
@@ -25,6 +25,8 @@ Note: Only `queries` can be dehydrated with an `HydrationBoundary`.
 
 `Element`
 
+The provided `children`, rendered once `state` has been hydrated into the cache.
+
 ## Examples
 
 ```tsx
diff --git a/docs/framework/preact/reference/functions/QueryClientProvider.md b/docs/framework/preact/reference/functions/QueryClientProvider.md
index cf336475452..6283568f84b 100644
--- a/docs/framework/preact/reference/functions/QueryClientProvider.md
+++ b/docs/framework/preact/reference/functions/QueryClientProvider.md
@@ -7,7 +7,7 @@ title: QueryClientProvider
 function QueryClientProvider(__namedParameters): VNode;
 ```
 
-Defined in: [preact-query/src/QueryClientProvider.tsx:61](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryClientProvider.tsx#L61)
+Defined in: [preact-query/src/QueryClientProvider.tsx:63](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryClientProvider.tsx#L63)
 
 Use the `QueryClientProvider` component to connect and provide a `QueryClient` to your application.
 
@@ -21,6 +21,8 @@ Use the `QueryClientProvider` component to connect and provide a `QueryClient` t
 
 `VNode`
 
+The provided `children`, wrapped so they can read the `QueryClient` via `useQueryClient`.
+
 ## Example
 
 ```tsx
diff --git a/docs/framework/preact/reference/functions/QueryErrorResetBoundary.md b/docs/framework/preact/reference/functions/QueryErrorResetBoundary.md
index 3e6c8945dfd..01461327c21 100644
--- a/docs/framework/preact/reference/functions/QueryErrorResetBoundary.md
+++ b/docs/framework/preact/reference/functions/QueryErrorResetBoundary.md
@@ -7,7 +7,7 @@ title: QueryErrorResetBoundary
 function QueryErrorResetBoundary(__namedParameters): Element;
 ```
 
-Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:127](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L127)
+Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:130](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L130)
 
 When using **suspense** or **throwOnError** in your queries, you need a way to let queries know that you want to
 try again when re-rendering after some error occurred. With the `QueryErrorResetBoundary` component you can
@@ -23,6 +23,9 @@ reset any query errors within the boundaries of the component.
 
 `Element`
 
+The `children`, rendered as-is, or called with the boundary's QueryErrorResetBoundaryValue
+if `children` is a function.
+
 ## Example
 
 ```tsx
diff --git a/docs/framework/preact/reference/functions/mutationOptions.md b/docs/framework/preact/reference/functions/mutationOptions.md
index b9992f68a78..66212f8e107 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:47](https://github.com/TanStack/query/blob/main/packages/preact-query/src/mutationOptions.ts#L47)
+Defined in: [preact-query/src/mutationOptions.ts:48](https://github.com/TanStack/query/blob/main/packages/preact-query/src/mutationOptions.ts#L48)
 
 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
@@ -46,6 +46,8 @@ required `mutationKey`.
 
 `WithRequired`\<[`UseMutationOptions`](../interfaces/UseMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\>
 
+The same options object, unchanged.
+
 ### Examples
 
 ```tsx
@@ -86,7 +88,7 @@ function SavingIndicator() {
 function mutationOptions<TData, TError, TVariables, TOnMutateResult>(options): Omit<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">;
 ```
 
-Defined in: [preact-query/src/mutationOptions.ts:83](https://github.com/TanStack/query/blob/main/packages/preact-query/src/mutationOptions.ts#L83)
+Defined in: [preact-query/src/mutationOptions.ts:85](https://github.com/TanStack/query/blob/main/packages/preact-query/src/mutationOptions.ts#L85)
 
 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
@@ -123,6 +125,8 @@ The mutation options to use, identical to what you'd pass to `useMutation`, with
 
 `Omit`\<[`UseMutationOptions`](../interfaces/UseMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\>
 
+The same options object, unchanged.
+
 ### Example
 
 ```tsx
diff --git a/packages/preact-query/src/HydrationBoundary.tsx b/packages/preact-query/src/HydrationBoundary.tsx
index 53e7effcc92..10be3ece80d 100644
--- a/packages/preact-query/src/HydrationBoundary.tsx
+++ b/packages/preact-query/src/HydrationBoundary.tsx
@@ -42,6 +42,8 @@ export interface HydrationBoundaryProps {
  *
  * Note: Only `queries` can be dehydrated with an `HydrationBoundary`.
  *
+ * @returns The provided `children`, rendered once `state` has been hydrated into the cache.
+ *
  * @example
  * ```tsx
  * import { HydrationBoundary } from '@tanstack/preact-query'
diff --git a/packages/preact-query/src/QueryClientProvider.tsx b/packages/preact-query/src/QueryClientProvider.tsx
index 147c04da82b..9c607d1286d 100644
--- a/packages/preact-query/src/QueryClientProvider.tsx
+++ b/packages/preact-query/src/QueryClientProvider.tsx
@@ -47,6 +47,8 @@ export type QueryClientProviderProps = {
 /**
  * Use the `QueryClientProvider` component to connect and provide a `QueryClient` to your application.
  *
+ * @returns The provided `children`, wrapped so they can read the `QueryClient` via `useQueryClient`.
+ *
  * @example
  * ```tsx
  * import { QueryClient, QueryClientProvider } from '@tanstack/preact-query'
diff --git a/packages/preact-query/src/QueryErrorResetBoundary.tsx b/packages/preact-query/src/QueryErrorResetBoundary.tsx
index c41a943e531..6d42064ca24 100644
--- a/packages/preact-query/src/QueryErrorResetBoundary.tsx
+++ b/packages/preact-query/src/QueryErrorResetBoundary.tsx
@@ -87,6 +87,9 @@ export interface QueryErrorResetBoundaryProps {
  * try again when re-rendering after some error occurred. With the `QueryErrorResetBoundary` component you can
  * reset any query errors within the boundaries of the component.
  *
+ * @returns The `children`, rendered as-is, or called with the boundary's {@link QueryErrorResetBoundaryValue}
+ * if `children` is a function.
+ *
  * @example
  * ```tsx
  * import { useErrorBoundary } from 'preact/hooks'
diff --git a/packages/preact-query/src/mutationOptions.ts b/packages/preact-query/src/mutationOptions.ts
index 4df1ae05844..ffabea5a75b 100644
--- a/packages/preact-query/src/mutationOptions.ts
+++ b/packages/preact-query/src/mutationOptions.ts
@@ -9,6 +9,7 @@ import type { UseMutationOptions } from './types'
  *
  * @param options - The mutation options to use, identical to what you'd pass to `useMutation`, with a
  * required `mutationKey`.
+ * @returns The same options object, unchanged.
  *
  * @example
  * ```tsx
@@ -65,6 +66,7 @@ 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.
  *
  * @example
  * ```tsx

From fa95739705f0f9ed00eb8cd9f67fb3a2eaa68c0c Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Tue, 25 Aug 2026 02:13:09 +0900
Subject: [PATCH 21/28] docs(preact-query): describe QueryErrorResetBoundary
 children and its render-function parameter

---
 .../preact/reference/functions/QueryErrorResetBoundary.md  | 2 +-
 .../reference/interfaces/QueryErrorResetBoundaryProps.md   | 7 +++++--
 .../type-aliases/QueryErrorResetBoundaryFunction.md        | 4 +++-
 packages/preact-query/src/QueryErrorResetBoundary.tsx      | 7 +++++++
 4 files changed, 16 insertions(+), 4 deletions(-)

diff --git a/docs/framework/preact/reference/functions/QueryErrorResetBoundary.md b/docs/framework/preact/reference/functions/QueryErrorResetBoundary.md
index 01461327c21..901cec345ab 100644
--- a/docs/framework/preact/reference/functions/QueryErrorResetBoundary.md
+++ b/docs/framework/preact/reference/functions/QueryErrorResetBoundary.md
@@ -7,7 +7,7 @@ title: QueryErrorResetBoundary
 function QueryErrorResetBoundary(__namedParameters): Element;
 ```
 
-Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:130](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L130)
+Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:137](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L137)
 
 When using **suspense** or **throwOnError** in your queries, you need a way to let queries know that you want to
 try again when re-rendering after some error occurred. With the `QueryErrorResetBoundary` component you can
diff --git a/docs/framework/preact/reference/interfaces/QueryErrorResetBoundaryProps.md b/docs/framework/preact/reference/interfaces/QueryErrorResetBoundaryProps.md
index 4dc3ea7129b..cfedfd05310 100644
--- a/docs/framework/preact/reference/interfaces/QueryErrorResetBoundaryProps.md
+++ b/docs/framework/preact/reference/interfaces/QueryErrorResetBoundaryProps.md
@@ -3,7 +3,7 @@ id: QueryErrorResetBoundaryProps
 title: QueryErrorResetBoundaryProps
 ---
 
-Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:81](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L81)
+Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:84](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L84)
 
 ## Properties
 
@@ -15,4 +15,7 @@ children:
   | QueryErrorResetBoundaryFunction;
 ```
 
-Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:82](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L82)
+Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:89](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L89)
+
+Either a plain node, or a function that receives the boundary's QueryErrorResetBoundaryValue and
+returns a node.
diff --git a/docs/framework/preact/reference/type-aliases/QueryErrorResetBoundaryFunction.md b/docs/framework/preact/reference/type-aliases/QueryErrorResetBoundaryFunction.md
index 048dac086e2..2c48c6ddb7b 100644
--- a/docs/framework/preact/reference/type-aliases/QueryErrorResetBoundaryFunction.md
+++ b/docs/framework/preact/reference/type-aliases/QueryErrorResetBoundaryFunction.md
@@ -7,7 +7,7 @@ title: QueryErrorResetBoundaryFunction
 type QueryErrorResetBoundaryFunction = (value) => ComponentChildren;
 ```
 
-Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:77](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L77)
+Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:80](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L80)
 
 ## Parameters
 
@@ -15,6 +15,8 @@ Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:77](https://github.com
 
 `QueryErrorResetBoundaryValue`
 
+The boundary's QueryErrorResetBoundaryValue.
+
 ## Returns
 
 `ComponentChildren`
diff --git a/packages/preact-query/src/QueryErrorResetBoundary.tsx b/packages/preact-query/src/QueryErrorResetBoundary.tsx
index 6d42064ca24..692fc777bdf 100644
--- a/packages/preact-query/src/QueryErrorResetBoundary.tsx
+++ b/packages/preact-query/src/QueryErrorResetBoundary.tsx
@@ -74,11 +74,18 @@ export const useQueryErrorResetBoundary = () =>
 
 // COMPONENT
 
+/**
+ * @param value - The boundary's {@link QueryErrorResetBoundaryValue}.
+ */
 export type QueryErrorResetBoundaryFunction = (
   value: QueryErrorResetBoundaryValue,
 ) => ComponentChildren
 
 export interface QueryErrorResetBoundaryProps {
+  /**
+   * Either a plain node, or a function that receives the boundary's {@link QueryErrorResetBoundaryValue} and
+   * returns a node.
+   */
   children: QueryErrorResetBoundaryFunction | ComponentChildren
 }
 

From e30eb05f21edd993f4aa6de38ad4e14f26601658 Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Tue, 25 Aug 2026 02:29:02 +0900
Subject: [PATCH 22/28] docs(preact-query): fix prose-accuracy issues found by
 multi-agent audit

Corrects useQuery's first overload @returns to match its actual return
type, moves the useSuspenseQuery/useSuspenseInfiniteQuery cancellation
caveat out of the @returns block, softens overstated skipToken/queryFn
claims, merges a duplicated useMutationState description, and adds
missing JSDoc to QueryErrorResetBoundary's function-type aliases and
UseMutateFunction/UseMutateAsyncFunction.
---
 .../functions/QueryErrorResetBoundary.md          |  2 +-
 .../preact/reference/functions/useMutation.md     |  5 ++++-
 .../reference/functions/useMutationState.md       |  8 +++-----
 .../preact/reference/functions/useQuery.md        |  6 +++---
 .../functions/useQueryErrorResetBoundary.md       |  2 +-
 .../functions/useSuspenseInfiniteQuery.md         |  4 ++--
 .../reference/functions/useSuspenseQuery.md       |  4 ++--
 .../interfaces/QueryErrorResetBoundaryProps.md    |  4 ++--
 .../interfaces/UseInfiniteQueryOptions.md         |  4 ++--
 .../reference/interfaces/UseMutationOptions.md    |  2 +-
 .../reference/interfaces/UseQueryOptions.md       |  2 +-
 .../interfaces/UseSuspenseInfiniteQueryOptions.md |  6 +++---
 .../interfaces/UseSuspenseQueryOptions.md         |  4 ++--
 .../type-aliases/AnyUseInfiniteQueryOptions.md    |  2 +-
 .../type-aliases/AnyUseMutationOptions.md         |  2 +-
 .../reference/type-aliases/AnyUseQueryOptions.md  |  2 +-
 .../AnyUseSuspenseInfiniteQueryOptions.md         |  2 +-
 .../type-aliases/AnyUseSuspenseQueryOptions.md    |  2 +-
 .../type-aliases/DefinedUseInfiniteQueryResult.md |  2 +-
 .../type-aliases/DefinedUseQueryResult.md         |  2 +-
 .../type-aliases/QueryErrorClearResetFunction.md  |  4 +++-
 .../type-aliases/QueryErrorIsResetFunction.md     |  4 +++-
 .../QueryErrorResetBoundaryFunction.md            |  6 +++++-
 .../type-aliases/QueryErrorResetFunction.md       |  4 +++-
 .../UnusedSkipTokenInfiniteOptions.md             |  4 ++--
 .../type-aliases/UnusedSkipTokenOptions.md        |  4 ++--
 .../type-aliases/UseBaseMutationResult.md         |  2 +-
 .../reference/type-aliases/UseBaseQueryResult.md  |  2 +-
 .../type-aliases/UseInfiniteQueryResult.md        |  2 +-
 .../type-aliases/UseMutateAsyncFunction.md        |  5 ++++-
 .../reference/type-aliases/UseMutateFunction.md   |  6 +++++-
 .../reference/type-aliases/UseMutationResult.md   |  2 +-
 .../UsePrefetchInfiniteQueryOptions.md            |  5 +++--
 .../type-aliases/UsePrefetchQueryOptions.md       |  3 ++-
 .../reference/type-aliases/UseQueryResult.md      |  2 +-
 .../UseSuspenseInfiniteQueryResult.md             |  2 +-
 .../type-aliases/UseSuspenseQueryResult.md        |  2 +-
 .../preact-query/src/QueryErrorResetBoundary.tsx  | 15 +++++++++++++++
 packages/preact-query/src/infiniteQueryOptions.ts |  4 ++--
 packages/preact-query/src/queryOptions.ts         |  4 ++--
 packages/preact-query/src/types.ts                | 15 +++++++++++++--
 packages/preact-query/src/useMutation.ts          |  3 +++
 packages/preact-query/src/useMutationState.ts     |  6 ++----
 packages/preact-query/src/useQuery.ts             |  6 +++---
 .../preact-query/src/useSuspenseInfiniteQuery.ts  |  4 ++--
 packages/preact-query/src/useSuspenseQuery.ts     |  4 ++--
 46 files changed, 117 insertions(+), 70 deletions(-)

diff --git a/docs/framework/preact/reference/functions/QueryErrorResetBoundary.md b/docs/framework/preact/reference/functions/QueryErrorResetBoundary.md
index 901cec345ab..80287b478b9 100644
--- a/docs/framework/preact/reference/functions/QueryErrorResetBoundary.md
+++ b/docs/framework/preact/reference/functions/QueryErrorResetBoundary.md
@@ -7,7 +7,7 @@ title: QueryErrorResetBoundary
 function QueryErrorResetBoundary(__namedParameters): Element;
 ```
 
-Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:137](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L137)
+Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:152](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L152)
 
 When using **suspense** or **throwOnError** in your queries, you need a way to let queries know that you want to
 try again when re-rendering after some error occurred. With the `QueryErrorResetBoundary` component you can
diff --git a/docs/framework/preact/reference/functions/useMutation.md b/docs/framework/preact/reference/functions/useMutation.md
index 3484af95d80..a04d9c93287 100644
--- a/docs/framework/preact/reference/functions/useMutation.md
+++ b/docs/framework/preact/reference/functions/useMutation.md
@@ -7,7 +7,10 @@ title: useMutation
 function useMutation<TData, TError, TVariables, TOnMutateResult>(options, queryClient?): UseMutationResult<TData, TError, TVariables, TOnMutateResult>;
 ```
 
-Defined in: [preact-query/src/useMutation.ts:83](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useMutation.ts#L83)
+Defined in: [preact-query/src/useMutation.ts:86](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useMutation.ts#L86)
+
+Unlike queries, mutations are typically used to create/update/delete data or perform server side-effects.
+`useMutation` is the hook for that.
 
 ## Type Parameters
 
diff --git a/docs/framework/preact/reference/functions/useMutationState.md b/docs/framework/preact/reference/functions/useMutationState.md
index 0a92400c3db..85f58a1ab75 100644
--- a/docs/framework/preact/reference/functions/useMutationState.md
+++ b/docs/framework/preact/reference/functions/useMutationState.md
@@ -7,13 +7,11 @@ title: useMutationState
 function useMutationState<TResult, TMutation>(options, queryClient?): TResult[];
 ```
 
-Defined in: [preact-query/src/useMutationState.ts:139](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useMutationState.ts#L139)
+Defined in: [preact-query/src/useMutationState.ts:137](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useMutationState.ts#L137)
 
 `useMutationState` is a hook that gives you access to all mutations in the `MutationCache`. You can pass
-`filters` to it to narrow down your mutations, and `select` to transform the mutation state.
-
-`options.filters` narrows down the matched mutations (MutationFilters), and `options.select` transforms
-the mutation state.
+`filters` (MutationFilters) to narrow down your mutations, and `select` to transform the mutation
+state.
 
 ## Type Parameters
 
diff --git a/docs/framework/preact/reference/functions/useQuery.md b/docs/framework/preact/reference/functions/useQuery.md
index 989665a7592..c2127e0b5f3 100644
--- a/docs/framework/preact/reference/functions/useQuery.md
+++ b/docs/framework/preact/reference/functions/useQuery.md
@@ -50,9 +50,9 @@ be used.
 
 [`DefinedUseQueryResult`](../type-aliases/DefinedUseQueryResult.md)\<`TData`, `TError`\>
 
-The current query result. `status` is `pending` if there is no cached data and no query attempt
-has finished yet, `error` if the query attempt resulted in an error, or `success` if the query has data to
-display. `isPending`/`isSuccess`/`isError` are derived booleans for convenience.
+The current query result, typed so that `status` is `success` — or `error` if a fetch attempt
+fails while keeping the existing data (`status` never resolves to `pending` in this overload's type,
+since `initialData` guarantees data upfront). `isSuccess`/`isError` are derived booleans for convenience.
 
 ### Example
 
diff --git a/docs/framework/preact/reference/functions/useQueryErrorResetBoundary.md b/docs/framework/preact/reference/functions/useQueryErrorResetBoundary.md
index eefa6c0eb6a..b2d33cf6799 100644
--- a/docs/framework/preact/reference/functions/useQueryErrorResetBoundary.md
+++ b/docs/framework/preact/reference/functions/useQueryErrorResetBoundary.md
@@ -7,7 +7,7 @@ title: useQueryErrorResetBoundary
 function useQueryErrorResetBoundary(): QueryErrorResetBoundaryValue;
 ```
 
-Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:72](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L72)
+Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:84](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L84)
 
 This hook will reset any query errors within the closest `QueryErrorResetBoundary`. If there is no boundary
 defined it will reset them globally.
diff --git a/docs/framework/preact/reference/functions/useSuspenseInfiniteQuery.md b/docs/framework/preact/reference/functions/useSuspenseInfiniteQuery.md
index 543ab2a184e..06ffb78381a 100644
--- a/docs/framework/preact/reference/functions/useSuspenseInfiniteQuery.md
+++ b/docs/framework/preact/reference/functions/useSuspenseInfiniteQuery.md
@@ -12,6 +12,8 @@ Defined in: [preact-query/src/useSuspenseInfiniteQuery.ts:66](https://github.com
 The options for `useSuspenseInfiniteQuery` are the same as for `useInfiniteQuery`, except for `throwOnError`,
 `enabled`, and `placeholderData`.
 
+Caveat: cancellation does not work.
+
 ## Type Parameters
 
 ### TQueryFnData
@@ -57,8 +59,6 @@ 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).
 
-Caveat: cancellation does not work.
-
 ## Example
 
 ```tsx
diff --git a/docs/framework/preact/reference/functions/useSuspenseQuery.md b/docs/framework/preact/reference/functions/useSuspenseQuery.md
index 31dbeabba27..ee5d805bff8 100644
--- a/docs/framework/preact/reference/functions/useSuspenseQuery.md
+++ b/docs/framework/preact/reference/functions/useSuspenseQuery.md
@@ -12,6 +12,8 @@ Defined in: [preact-query/src/useSuspenseQuery.ts:51](https://github.com/TanStac
 The options for `useSuspenseQuery` are the same as for `useQuery`, except for `throwOnError`, `enabled`, and
 `placeholderData`.
 
+Caveat: cancellation does not work.
+
 ## Type Parameters
 
 ### TQueryFnData
@@ -52,8 +54,6 @@ be used.
 The same object as `useQuery`, except that `data` is guaranteed to be defined, `isPlaceholderData`
 is missing, and `status` is either `success` or `error` (with the derived flags set accordingly).
 
-Caveat: cancellation does not work.
-
 ## Example
 
 ```tsx
diff --git a/docs/framework/preact/reference/interfaces/QueryErrorResetBoundaryProps.md b/docs/framework/preact/reference/interfaces/QueryErrorResetBoundaryProps.md
index cfedfd05310..ab613307d9f 100644
--- a/docs/framework/preact/reference/interfaces/QueryErrorResetBoundaryProps.md
+++ b/docs/framework/preact/reference/interfaces/QueryErrorResetBoundaryProps.md
@@ -3,7 +3,7 @@ id: QueryErrorResetBoundaryProps
 title: QueryErrorResetBoundaryProps
 ---
 
-Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:84](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L84)
+Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:99](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L99)
 
 ## Properties
 
@@ -15,7 +15,7 @@ children:
   | QueryErrorResetBoundaryFunction;
 ```
 
-Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:89](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L89)
+Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:104](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L104)
 
 Either a plain node, or a function that receives the boundary's QueryErrorResetBoundaryValue and
 returns a node.
diff --git a/docs/framework/preact/reference/interfaces/UseInfiniteQueryOptions.md b/docs/framework/preact/reference/interfaces/UseInfiniteQueryOptions.md
index ff860eb0aa3..570416ab1b7 100644
--- a/docs/framework/preact/reference/interfaces/UseInfiniteQueryOptions.md
+++ b/docs/framework/preact/reference/interfaces/UseInfiniteQueryOptions.md
@@ -3,7 +3,7 @@ id: UseInfiniteQueryOptions
 title: UseInfiniteQueryOptions
 ---
 
-Defined in: [preact-query/src/types.ts:149](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L149)
+Defined in: [preact-query/src/types.ts:151](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L151)
 
 ## Extends
 
@@ -39,7 +39,7 @@ Defined in: [preact-query/src/types.ts:149](https://github.com/TanStack/query/bl
 optional subscribed: boolean;
 ```
 
-Defined in: [preact-query/src/types.ts:169](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L169)
+Defined in: [preact-query/src/types.ts:171](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L171)
 
 Set this to `false` to unsubscribe this observer from updates to the query cache.
 Defaults to `true`.
diff --git a/docs/framework/preact/reference/interfaces/UseMutationOptions.md b/docs/framework/preact/reference/interfaces/UseMutationOptions.md
index 67dc05c6ded..13b6dc08a30 100644
--- a/docs/framework/preact/reference/interfaces/UseMutationOptions.md
+++ b/docs/framework/preact/reference/interfaces/UseMutationOptions.md
@@ -3,7 +3,7 @@ id: UseMutationOptions
 title: UseMutationOptions
 ---
 
-Defined in: [preact-query/src/types.ts:242](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L242)
+Defined in: [preact-query/src/types.ts:244](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L244)
 
 ## Extends
 
diff --git a/docs/framework/preact/reference/interfaces/UseQueryOptions.md b/docs/framework/preact/reference/interfaces/UseQueryOptions.md
index 927b0c40b88..1038e6c9691 100644
--- a/docs/framework/preact/reference/interfaces/UseQueryOptions.md
+++ b/docs/framework/preact/reference/interfaces/UseQueryOptions.md
@@ -3,7 +3,7 @@ id: UseQueryOptions
 title: UseQueryOptions
 ---
 
-Defined in: [preact-query/src/types.ts:107](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L107)
+Defined in: [preact-query/src/types.ts:109](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L109)
 
 ## Extends
 
diff --git a/docs/framework/preact/reference/interfaces/UseSuspenseInfiniteQueryOptions.md b/docs/framework/preact/reference/interfaces/UseSuspenseInfiniteQueryOptions.md
index 78bde153d30..b420d6baeed 100644
--- a/docs/framework/preact/reference/interfaces/UseSuspenseInfiniteQueryOptions.md
+++ b/docs/framework/preact/reference/interfaces/UseSuspenseInfiniteQueryOptions.md
@@ -3,7 +3,7 @@ id: UseSuspenseInfiniteQueryOptions
 title: UseSuspenseInfiniteQueryOptions
 ---
 
-Defined in: [preact-query/src/types.ts:174](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L174)
+Defined in: [preact-query/src/types.ts:176](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L176)
 
 ## Extends
 
@@ -39,7 +39,7 @@ Defined in: [preact-query/src/types.ts:174](https://github.com/TanStack/query/bl
 optional queryFn: QueryFunction<TQueryFnData, TQueryKey, TPageParam>;
 ```
 
-Defined in: [preact-query/src/types.ts:188](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L188)
+Defined in: [preact-query/src/types.ts:190](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L190)
 
 `skipToken` is not allowed here — Suspense hooks cannot render a "disabled" state, so a query function
 must always be provided.
@@ -52,7 +52,7 @@ must always be provided.
 optional subscribed: boolean;
 ```
 
-Defined in: [preact-query/src/types.ts:169](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L169)
+Defined in: [preact-query/src/types.ts:171](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L171)
 
 Set this to `false` to unsubscribe this observer from updates to the query cache.
 Defaults to `true`.
diff --git a/docs/framework/preact/reference/interfaces/UseSuspenseQueryOptions.md b/docs/framework/preact/reference/interfaces/UseSuspenseQueryOptions.md
index b3b39b20770..1f2ed068bf8 100644
--- a/docs/framework/preact/reference/interfaces/UseSuspenseQueryOptions.md
+++ b/docs/framework/preact/reference/interfaces/UseSuspenseQueryOptions.md
@@ -3,7 +3,7 @@ id: UseSuspenseQueryOptions
 title: UseSuspenseQueryOptions
 ---
 
-Defined in: [preact-query/src/types.ts:123](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L123)
+Defined in: [preact-query/src/types.ts:125](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L125)
 
 ## Extends
 
@@ -35,7 +35,7 @@ Defined in: [preact-query/src/types.ts:123](https://github.com/TanStack/query/bl
 optional queryFn: QueryFunction<TQueryFnData, TQueryKey, never>;
 ```
 
-Defined in: [preact-query/src/types.ts:136](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L136)
+Defined in: [preact-query/src/types.ts:138](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L138)
 
 `skipToken` is not allowed here — Suspense hooks cannot render a "disabled" state, so a query function
 must always be provided.
diff --git a/docs/framework/preact/reference/type-aliases/AnyUseInfiniteQueryOptions.md b/docs/framework/preact/reference/type-aliases/AnyUseInfiniteQueryOptions.md
index c2eb5ecc4a6..ca8ccce2e3d 100644
--- a/docs/framework/preact/reference/type-aliases/AnyUseInfiniteQueryOptions.md
+++ b/docs/framework/preact/reference/type-aliases/AnyUseInfiniteQueryOptions.md
@@ -7,4 +7,4 @@ title: AnyUseInfiniteQueryOptions
 type AnyUseInfiniteQueryOptions = UseInfiniteQueryOptions<any, any, any, any, any>;
 ```
 
-Defined in: [preact-query/src/types.ts:142](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L142)
+Defined in: [preact-query/src/types.ts:144](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L144)
diff --git a/docs/framework/preact/reference/type-aliases/AnyUseMutationOptions.md b/docs/framework/preact/reference/type-aliases/AnyUseMutationOptions.md
index 6d4327820ee..2dc2d26366f 100644
--- a/docs/framework/preact/reference/type-aliases/AnyUseMutationOptions.md
+++ b/docs/framework/preact/reference/type-aliases/AnyUseMutationOptions.md
@@ -7,4 +7,4 @@ title: AnyUseMutationOptions
 type AnyUseMutationOptions = UseMutationOptions<any, any, any, any>;
 ```
 
-Defined in: [preact-query/src/types.ts:241](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L241)
+Defined in: [preact-query/src/types.ts:243](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L243)
diff --git a/docs/framework/preact/reference/type-aliases/AnyUseQueryOptions.md b/docs/framework/preact/reference/type-aliases/AnyUseQueryOptions.md
index bd66a02d947..737779e6513 100644
--- a/docs/framework/preact/reference/type-aliases/AnyUseQueryOptions.md
+++ b/docs/framework/preact/reference/type-aliases/AnyUseQueryOptions.md
@@ -7,4 +7,4 @@ title: AnyUseQueryOptions
 type AnyUseQueryOptions = UseQueryOptions<any, any, any, any>;
 ```
 
-Defined in: [preact-query/src/types.ts:106](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L106)
+Defined in: [preact-query/src/types.ts:108](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L108)
diff --git a/docs/framework/preact/reference/type-aliases/AnyUseSuspenseInfiniteQueryOptions.md b/docs/framework/preact/reference/type-aliases/AnyUseSuspenseInfiniteQueryOptions.md
index fd8ceb5bb7e..045bd4c2634 100644
--- a/docs/framework/preact/reference/type-aliases/AnyUseSuspenseInfiniteQueryOptions.md
+++ b/docs/framework/preact/reference/type-aliases/AnyUseSuspenseInfiniteQueryOptions.md
@@ -7,4 +7,4 @@ title: AnyUseSuspenseInfiniteQueryOptions
 type AnyUseSuspenseInfiniteQueryOptions = UseSuspenseInfiniteQueryOptions<any, any, any, any, any>;
 ```
 
-Defined in: [preact-query/src/types.ts:172](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L172)
+Defined in: [preact-query/src/types.ts:174](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L174)
diff --git a/docs/framework/preact/reference/type-aliases/AnyUseSuspenseQueryOptions.md b/docs/framework/preact/reference/type-aliases/AnyUseSuspenseQueryOptions.md
index 708b7db3080..f7b5a6620e9 100644
--- a/docs/framework/preact/reference/type-aliases/AnyUseSuspenseQueryOptions.md
+++ b/docs/framework/preact/reference/type-aliases/AnyUseSuspenseQueryOptions.md
@@ -7,4 +7,4 @@ title: AnyUseSuspenseQueryOptions
 type AnyUseSuspenseQueryOptions = UseSuspenseQueryOptions<any, any, any, any>;
 ```
 
-Defined in: [preact-query/src/types.ts:117](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L117)
+Defined in: [preact-query/src/types.ts:119](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L119)
diff --git a/docs/framework/preact/reference/type-aliases/DefinedUseInfiniteQueryResult.md b/docs/framework/preact/reference/type-aliases/DefinedUseInfiniteQueryResult.md
index f0afce9d8dc..a9d6fd4099f 100644
--- a/docs/framework/preact/reference/type-aliases/DefinedUseInfiniteQueryResult.md
+++ b/docs/framework/preact/reference/type-aliases/DefinedUseInfiniteQueryResult.md
@@ -7,7 +7,7 @@ title: DefinedUseInfiniteQueryResult
 type DefinedUseInfiniteQueryResult<TData, TError> = DefinedInfiniteQueryObserverResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/types.ts:228](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L228)
+Defined in: [preact-query/src/types.ts:230](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L230)
 
 ## Type Parameters
 
diff --git a/docs/framework/preact/reference/type-aliases/DefinedUseQueryResult.md b/docs/framework/preact/reference/type-aliases/DefinedUseQueryResult.md
index b8739df6a31..c6803ec0595 100644
--- a/docs/framework/preact/reference/type-aliases/DefinedUseQueryResult.md
+++ b/docs/framework/preact/reference/type-aliases/DefinedUseQueryResult.md
@@ -7,7 +7,7 @@ title: DefinedUseQueryResult
 type DefinedUseQueryResult<TData, TError> = DefinedQueryObserverResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/types.ts:218](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L218)
+Defined in: [preact-query/src/types.ts:220](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L220)
 
 ## Type Parameters
 
diff --git a/docs/framework/preact/reference/type-aliases/QueryErrorClearResetFunction.md b/docs/framework/preact/reference/type-aliases/QueryErrorClearResetFunction.md
index 26cbffd963d..d80f43bf5e8 100644
--- a/docs/framework/preact/reference/type-aliases/QueryErrorClearResetFunction.md
+++ b/docs/framework/preact/reference/type-aliases/QueryErrorClearResetFunction.md
@@ -7,7 +7,9 @@ title: QueryErrorClearResetFunction
 type QueryErrorClearResetFunction = () => void;
 ```
 
-Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:8](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L8)
+Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:20](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L20)
+
+Clears the reset state, so queries know not to try again until the boundary is reset again.
 
 ## Returns
 
diff --git a/docs/framework/preact/reference/type-aliases/QueryErrorIsResetFunction.md b/docs/framework/preact/reference/type-aliases/QueryErrorIsResetFunction.md
index 3c08a571ff4..c1cd3ca73e9 100644
--- a/docs/framework/preact/reference/type-aliases/QueryErrorIsResetFunction.md
+++ b/docs/framework/preact/reference/type-aliases/QueryErrorIsResetFunction.md
@@ -7,7 +7,9 @@ title: QueryErrorIsResetFunction
 type QueryErrorIsResetFunction = () => boolean;
 ```
 
-Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:7](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L7)
+Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:15](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L15)
+
+Returns whether the boundary has been reset and not yet cleared.
 
 ## Returns
 
diff --git a/docs/framework/preact/reference/type-aliases/QueryErrorResetBoundaryFunction.md b/docs/framework/preact/reference/type-aliases/QueryErrorResetBoundaryFunction.md
index 2c48c6ddb7b..f826081fb3f 100644
--- a/docs/framework/preact/reference/type-aliases/QueryErrorResetBoundaryFunction.md
+++ b/docs/framework/preact/reference/type-aliases/QueryErrorResetBoundaryFunction.md
@@ -7,7 +7,9 @@ title: QueryErrorResetBoundaryFunction
 type QueryErrorResetBoundaryFunction = (value) => ComponentChildren;
 ```
 
-Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:80](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L80)
+Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:95](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L95)
+
+A render-prop function usable as `children` on `QueryErrorResetBoundary`.
 
 ## Parameters
 
@@ -20,3 +22,5 @@ The boundary's QueryErrorResetBoundaryValue.
 ## Returns
 
 `ComponentChildren`
+
+The children to render.
diff --git a/docs/framework/preact/reference/type-aliases/QueryErrorResetFunction.md b/docs/framework/preact/reference/type-aliases/QueryErrorResetFunction.md
index 09ad00e7f93..963e0bba8ae 100644
--- a/docs/framework/preact/reference/type-aliases/QueryErrorResetFunction.md
+++ b/docs/framework/preact/reference/type-aliases/QueryErrorResetFunction.md
@@ -7,7 +7,9 @@ title: QueryErrorResetFunction
 type QueryErrorResetFunction = () => void;
 ```
 
-Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:6](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L6)
+Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:10](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L10)
+
+Resets any query errors within the boundary, so queries know they can try again.
 
 ## Returns
 
diff --git a/docs/framework/preact/reference/type-aliases/UnusedSkipTokenInfiniteOptions.md b/docs/framework/preact/reference/type-aliases/UnusedSkipTokenInfiniteOptions.md
index 0fb50efbad3..78c039445f2 100644
--- a/docs/framework/preact/reference/type-aliases/UnusedSkipTokenInfiniteOptions.md
+++ b/docs/framework/preact/reference/type-aliases/UnusedSkipTokenInfiniteOptions.md
@@ -17,8 +17,8 @@ Defined in: [preact-query/src/infiniteQueryOptions.ts:42](https://github.com/Tan
 optional queryFn: Exclude<UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>["queryFn"], SkipToken | undefined>;
 ```
 
-`skipToken` is not allowed here — this overload is selected when no `initialData` is set, so the query
-always needs a function to actually run.
+`skipToken` is not allowed as a value here — this overload is selected when no `initialData` is set. If
+you don't intend to run the query yet, omit `queryFn` or use a default query function instead.
 
 ## Type Parameters
 
diff --git a/docs/framework/preact/reference/type-aliases/UnusedSkipTokenOptions.md b/docs/framework/preact/reference/type-aliases/UnusedSkipTokenOptions.md
index 55bb73dd6f6..7f82dad99c2 100644
--- a/docs/framework/preact/reference/type-aliases/UnusedSkipTokenOptions.md
+++ b/docs/framework/preact/reference/type-aliases/UnusedSkipTokenOptions.md
@@ -17,8 +17,8 @@ Defined in: [preact-query/src/queryOptions.ts:33](https://github.com/TanStack/qu
 optional queryFn: Exclude<UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>["queryFn"], SkipToken | undefined>;
 ```
 
-`skipToken` is not allowed here — this overload is selected when no `initialData` is set, so the query
-always needs a function to actually run.
+`skipToken` is not allowed as a value here — this overload is selected when no `initialData` is set. If
+you don't intend to run the query yet, omit `queryFn` or use a default query function instead.
 
 ## Type Parameters
 
diff --git a/docs/framework/preact/reference/type-aliases/UseBaseMutationResult.md b/docs/framework/preact/reference/type-aliases/UseBaseMutationResult.md
index b7c3a4ba4d9..47bfb391d16 100644
--- a/docs/framework/preact/reference/type-aliases/UseBaseMutationResult.md
+++ b/docs/framework/preact/reference/type-aliases/UseBaseMutationResult.md
@@ -9,7 +9,7 @@ type UseBaseMutationResult<TData, TError, TVariables, TOnMutateResult> = Overrid
 }> & object;
 ```
 
-Defined in: [preact-query/src/types.ts:270](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L270)
+Defined in: [preact-query/src/types.ts:281](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L281)
 
 ## Type Declaration
 
diff --git a/docs/framework/preact/reference/type-aliases/UseBaseQueryResult.md b/docs/framework/preact/reference/type-aliases/UseBaseQueryResult.md
index b13cf83a324..70bf3f5252f 100644
--- a/docs/framework/preact/reference/type-aliases/UseBaseQueryResult.md
+++ b/docs/framework/preact/reference/type-aliases/UseBaseQueryResult.md
@@ -7,7 +7,7 @@ title: UseBaseQueryResult
 type UseBaseQueryResult<TData, TError> = QueryObserverResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/types.ts:200](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L200)
+Defined in: [preact-query/src/types.ts:202](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L202)
 
 ## Type Parameters
 
diff --git a/docs/framework/preact/reference/type-aliases/UseInfiniteQueryResult.md b/docs/framework/preact/reference/type-aliases/UseInfiniteQueryResult.md
index 8b8e7203c04..9b0b9eec232 100644
--- a/docs/framework/preact/reference/type-aliases/UseInfiniteQueryResult.md
+++ b/docs/framework/preact/reference/type-aliases/UseInfiniteQueryResult.md
@@ -7,7 +7,7 @@ title: UseInfiniteQueryResult
 type UseInfiniteQueryResult<TData, TError> = InfiniteQueryObserverResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/types.ts:223](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L223)
+Defined in: [preact-query/src/types.ts:225](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L225)
 
 ## Type Parameters
 
diff --git a/docs/framework/preact/reference/type-aliases/UseMutateAsyncFunction.md b/docs/framework/preact/reference/type-aliases/UseMutateAsyncFunction.md
index 3d41f5d6c33..8a833c776a5 100644
--- a/docs/framework/preact/reference/type-aliases/UseMutateAsyncFunction.md
+++ b/docs/framework/preact/reference/type-aliases/UseMutateAsyncFunction.md
@@ -7,7 +7,10 @@ title: UseMutateAsyncFunction
 type UseMutateAsyncFunction<TData, TError, TVariables, TOnMutateResult> = MutateFunction<TData, TError, TVariables, TOnMutateResult>;
 ```
 
-Defined in: [preact-query/src/types.ts:263](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L263)
+Defined in: [preact-query/src/types.ts:274](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L274)
+
+The type of `mutateAsync`, as returned by `useMutation`. Similar to [UseMutateFunction](UseMutateFunction.md), but returns a
+promise which can be awaited.
 
 ## Type Parameters
 
diff --git a/docs/framework/preact/reference/type-aliases/UseMutateFunction.md b/docs/framework/preact/reference/type-aliases/UseMutateFunction.md
index 6dc8e6734eb..5f692a42394 100644
--- a/docs/framework/preact/reference/type-aliases/UseMutateFunction.md
+++ b/docs/framework/preact/reference/type-aliases/UseMutateFunction.md
@@ -7,7 +7,11 @@ title: UseMutateFunction
 type UseMutateFunction<TData, TError, TVariables, TOnMutateResult> = (...args) => void;
 ```
 
-Defined in: [preact-query/src/types.ts:252](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L252)
+Defined in: [preact-query/src/types.ts:259](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L259)
+
+The type of `mutate`, as returned by `useMutation`. Forwards the variables (and an optional per-call
+`onSuccess`/`onError`/`onSettled`) to the underlying `mutate` call. Fire-and-forget — errors are surfaced
+through the mutation result, not thrown.
 
 ## Type Parameters
 
diff --git a/docs/framework/preact/reference/type-aliases/UseMutationResult.md b/docs/framework/preact/reference/type-aliases/UseMutationResult.md
index b6002b9a8d7..2611e9a1ef3 100644
--- a/docs/framework/preact/reference/type-aliases/UseMutationResult.md
+++ b/docs/framework/preact/reference/type-aliases/UseMutationResult.md
@@ -7,7 +7,7 @@ title: UseMutationResult
 type UseMutationResult<TData, TError, TVariables, TOnMutateResult> = UseBaseMutationResult<TData, TError, TVariables, TOnMutateResult>;
 ```
 
-Defined in: [preact-query/src/types.ts:290](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L290)
+Defined in: [preact-query/src/types.ts:301](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L301)
 
 ## Type Parameters
 
diff --git a/docs/framework/preact/reference/type-aliases/UsePrefetchInfiniteQueryOptions.md b/docs/framework/preact/reference/type-aliases/UsePrefetchInfiniteQueryOptions.md
index 8680dc32223..a1bae7e8ce4 100644
--- a/docs/framework/preact/reference/type-aliases/UsePrefetchInfiniteQueryOptions.md
+++ b/docs/framework/preact/reference/type-aliases/UsePrefetchInfiniteQueryOptions.md
@@ -7,7 +7,7 @@ title: UsePrefetchInfiniteQueryOptions
 type UsePrefetchInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> = DistributiveOmit<InfiniteQueryExecuteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, "queryFn"> & object;
 ```
 
-Defined in: [preact-query/src/types.ts:75](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L75)
+Defined in: [preact-query/src/types.ts:76](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L76)
 
 ## Type Declaration
 
@@ -17,7 +17,8 @@ Defined in: [preact-query/src/types.ts:75](https://github.com/TanStack/query/blo
 optional queryFn: Exclude<InfiniteQueryExecuteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>["queryFn"], SkipToken>;
 ```
 
-`skipToken` is not allowed here — a prefetch always needs a query function to actually run.
+`skipToken` is not allowed as a value here — a prefetch always needs a query function to actually run,
+unless a default query function has been defined.
 
 ## Type Parameters
 
diff --git a/docs/framework/preact/reference/type-aliases/UsePrefetchQueryOptions.md b/docs/framework/preact/reference/type-aliases/UsePrefetchQueryOptions.md
index f147535ebd3..174c48f9c40 100644
--- a/docs/framework/preact/reference/type-aliases/UsePrefetchQueryOptions.md
+++ b/docs/framework/preact/reference/type-aliases/UsePrefetchQueryOptions.md
@@ -17,7 +17,8 @@ Defined in: [preact-query/src/types.ts:50](https://github.com/TanStack/query/blo
 optional queryFn: Exclude<QueryExecuteOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey>["queryFn"], SkipToken>;
 ```
 
-`skipToken` is not allowed here — a prefetch always needs a query function to actually run.
+`skipToken` is not allowed as a value here — a prefetch always needs a query function to actually run,
+unless a default query function has been defined.
 
 ## Type Parameters
 
diff --git a/docs/framework/preact/reference/type-aliases/UseQueryResult.md b/docs/framework/preact/reference/type-aliases/UseQueryResult.md
index b46d463da25..7a52ca3e896 100644
--- a/docs/framework/preact/reference/type-aliases/UseQueryResult.md
+++ b/docs/framework/preact/reference/type-aliases/UseQueryResult.md
@@ -7,7 +7,7 @@ title: UseQueryResult
 type UseQueryResult<TData, TError> = UseBaseQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/types.ts:205](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L205)
+Defined in: [preact-query/src/types.ts:207](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L207)
 
 ## Type Parameters
 
diff --git a/docs/framework/preact/reference/type-aliases/UseSuspenseInfiniteQueryResult.md b/docs/framework/preact/reference/type-aliases/UseSuspenseInfiniteQueryResult.md
index f285e10e9dd..dedb0fe4f91 100644
--- a/docs/framework/preact/reference/type-aliases/UseSuspenseInfiniteQueryResult.md
+++ b/docs/framework/preact/reference/type-aliases/UseSuspenseInfiniteQueryResult.md
@@ -7,7 +7,7 @@ title: UseSuspenseInfiniteQueryResult
 type UseSuspenseInfiniteQueryResult<TData, TError> = OmitKeyof<DefinedInfiniteQueryObserverResult<TData, TError>, "isPlaceholderData">;
 ```
 
-Defined in: [preact-query/src/types.ts:233](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L233)
+Defined in: [preact-query/src/types.ts:235](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L235)
 
 ## Type Parameters
 
diff --git a/docs/framework/preact/reference/type-aliases/UseSuspenseQueryResult.md b/docs/framework/preact/reference/type-aliases/UseSuspenseQueryResult.md
index aa6f5b6bbda..34fed72a54c 100644
--- a/docs/framework/preact/reference/type-aliases/UseSuspenseQueryResult.md
+++ b/docs/framework/preact/reference/type-aliases/UseSuspenseQueryResult.md
@@ -7,7 +7,7 @@ title: UseSuspenseQueryResult
 type UseSuspenseQueryResult<TData, TError> = DistributiveOmit<DefinedQueryObserverResult<TData, TError>, "isPlaceholderData">;
 ```
 
-Defined in: [preact-query/src/types.ts:210](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L210)
+Defined in: [preact-query/src/types.ts:212](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L212)
 
 ## Type Parameters
 
diff --git a/packages/preact-query/src/QueryErrorResetBoundary.tsx b/packages/preact-query/src/QueryErrorResetBoundary.tsx
index 692fc777bdf..3468ffa7563 100644
--- a/packages/preact-query/src/QueryErrorResetBoundary.tsx
+++ b/packages/preact-query/src/QueryErrorResetBoundary.tsx
@@ -3,8 +3,20 @@ import type { ComponentChildren } from 'preact'
 import { useContext, useState } from 'preact/hooks'
 
 // CONTEXT
+
+/**
+ * Resets any query errors within the boundary, so queries know they can try again.
+ */
 export type QueryErrorResetFunction = () => void
+
+/**
+ * Returns whether the boundary has been reset and not yet cleared.
+ */
 export type QueryErrorIsResetFunction = () => boolean
+
+/**
+ * Clears the reset state, so queries know not to try again until the boundary is reset again.
+ */
 export type QueryErrorClearResetFunction = () => void
 
 export interface QueryErrorResetBoundaryValue {
@@ -75,7 +87,10 @@ export const useQueryErrorResetBoundary = () =>
 // COMPONENT
 
 /**
+ * A render-prop function usable as `children` on `QueryErrorResetBoundary`.
+ *
  * @param value - The boundary's {@link QueryErrorResetBoundaryValue}.
+ * @returns The children to render.
  */
 export type QueryErrorResetBoundaryFunction = (
   value: QueryErrorResetBoundaryValue,
diff --git a/packages/preact-query/src/infiniteQueryOptions.ts b/packages/preact-query/src/infiniteQueryOptions.ts
index e987c8969ec..de91a207e7e 100644
--- a/packages/preact-query/src/infiniteQueryOptions.ts
+++ b/packages/preact-query/src/infiniteQueryOptions.ts
@@ -50,8 +50,8 @@ export type UnusedSkipTokenInfiniteOptions<
   'queryFn'
 > & {
   /**
-   * `skipToken` is not allowed here — this overload is selected when no `initialData` is set, so the query
-   * always needs a function to actually run.
+   * `skipToken` is not allowed as a value here — this overload is selected when no `initialData` is set. If
+   * you don't intend to run the query yet, omit `queryFn` or use a default query function instead.
    */
   queryFn?: Exclude<
     UseInfiniteQueryOptions<
diff --git a/packages/preact-query/src/queryOptions.ts b/packages/preact-query/src/queryOptions.ts
index 3d71f0ac39d..c677e43846a 100644
--- a/packages/preact-query/src/queryOptions.ts
+++ b/packages/preact-query/src/queryOptions.ts
@@ -40,8 +40,8 @@ export type UnusedSkipTokenOptions<
   'queryFn'
 > & {
   /**
-   * `skipToken` is not allowed here — this overload is selected when no `initialData` is set, so the query
-   * always needs a function to actually run.
+   * `skipToken` is not allowed as a value here — this overload is selected when no `initialData` is set. If
+   * you don't intend to run the query yet, omit `queryFn` or use a default query function instead.
    */
   queryFn?: Exclude<
     UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>['queryFn'],
diff --git a/packages/preact-query/src/types.ts b/packages/preact-query/src/types.ts
index 1c85505211b..428b493fa4a 100644
--- a/packages/preact-query/src/types.ts
+++ b/packages/preact-query/src/types.ts
@@ -58,7 +58,8 @@ export type UsePrefetchQueryOptions<
   'queryFn'
 > & {
   /**
-   * `skipToken` is not allowed here — a prefetch always needs a query function to actually run.
+   * `skipToken` is not allowed as a value here — a prefetch always needs a query function to actually run,
+   * unless a default query function has been defined.
    */
   queryFn?: Exclude<
     QueryExecuteOptions<
@@ -89,7 +90,8 @@ export type UsePrefetchInfiniteQueryOptions<
   'queryFn'
 > & {
   /**
-   * `skipToken` is not allowed here — a prefetch always needs a query function to actually run.
+   * `skipToken` is not allowed as a value here — a prefetch always needs a query function to actually run,
+   * unless a default query function has been defined.
    */
   queryFn?: Exclude<
     InfiniteQueryExecuteOptions<
@@ -249,6 +251,11 @@ export interface UseMutationOptions<
   '_defaulted'
 > {}
 
+/**
+ * The type of `mutate`, as returned by `useMutation`. Forwards the variables (and an optional per-call
+ * `onSuccess`/`onError`/`onSettled`) to the underlying `mutate` call. Fire-and-forget — errors are surfaced
+ * through the mutation result, not thrown.
+ */
 export type UseMutateFunction<
   TData = unknown,
   TError = DefaultError,
@@ -260,6 +267,10 @@ export type UseMutateFunction<
   >
 ) => void
 
+/**
+ * The type of `mutateAsync`, as returned by `useMutation`. Similar to {@link UseMutateFunction}, but returns a
+ * promise which can be awaited.
+ */
 export type UseMutateAsyncFunction<
   TData = unknown,
   TError = DefaultError,
diff --git a/packages/preact-query/src/useMutation.ts b/packages/preact-query/src/useMutation.ts
index 84d73167e9c..23523885dcc 100644
--- a/packages/preact-query/src/useMutation.ts
+++ b/packages/preact-query/src/useMutation.ts
@@ -18,6 +18,9 @@ import { useSyncExternalStore } from './utils'
 // HOOK
 
 /**
+ * Unlike queries, mutations are typically used to create/update/delete data or perform server side-effects.
+ * `useMutation` is the hook for that.
+ *
  * @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.
diff --git a/packages/preact-query/src/useMutationState.ts b/packages/preact-query/src/useMutationState.ts
index a10bf1c33a7..342c49c385d 100644
--- a/packages/preact-query/src/useMutationState.ts
+++ b/packages/preact-query/src/useMutationState.ts
@@ -81,10 +81,8 @@ function getResult<
 
 /**
  * `useMutationState` is a hook that gives you access to all mutations in the `MutationCache`. You can pass
- * `filters` to it to narrow down your mutations, and `select` to transform the mutation state.
- *
- * `options.filters` narrows down the matched mutations ({@link MutationFilters}), and `options.select` transforms
- * the mutation state.
+ * `filters` ({@link MutationFilters}) to narrow down your mutations, and `select` to transform the mutation
+ * state.
  *
  * @param options - The `filters` to narrow down matched mutations, and an optional `select` to transform the
  * mutation state.
diff --git a/packages/preact-query/src/useQuery.ts b/packages/preact-query/src/useQuery.ts
index 3b9a8da0322..60af51724e5 100644
--- a/packages/preact-query/src/useQuery.ts
+++ b/packages/preact-query/src/useQuery.ts
@@ -18,9 +18,9 @@ import { useBaseQuery } from './useBaseQuery'
  * @param options - The {@link DefinedInitialDataOptions} to use — everything you can pass to `useQuery`, with `initialData` set.
  * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
  * be used.
- * @returns The current query result. `status` is `pending` if there is no cached data and no query attempt
- * has finished yet, `error` if the query attempt resulted in an error, or `success` if the query has data to
- * display. `isPending`/`isSuccess`/`isError` are derived booleans for convenience.
+ * @returns The current query result, typed so that `status` is `success` — or `error` if a fetch attempt
+ * fails while keeping the existing data (`status` never resolves to `pending` in this overload's type,
+ * since `initialData` guarantees data upfront). `isSuccess`/`isError` are derived booleans for convenience.
  *
  * @example
  * ```tsx
diff --git a/packages/preact-query/src/useSuspenseInfiniteQuery.ts b/packages/preact-query/src/useSuspenseInfiniteQuery.ts
index 61d6301820e..d09dc325510 100644
--- a/packages/preact-query/src/useSuspenseInfiniteQuery.ts
+++ b/packages/preact-query/src/useSuspenseInfiniteQuery.ts
@@ -19,6 +19,8 @@ import { useBaseQuery } from './useBaseQuery'
  * The options for `useSuspenseInfiniteQuery` are the same as for `useInfiniteQuery`, except for `throwOnError`,
  * `enabled`, and `placeholderData`.
  *
+ * Caveat: cancellation does not work.
+ *
  * @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.
@@ -26,8 +28,6 @@ import { useBaseQuery } from './useBaseQuery'
  * `isPlaceholderData` is missing, and `status` is either `success` or `error` (with the derived flags set
  * accordingly).
  *
- * Caveat: cancellation does not work.
- *
  * @example
  * ```tsx
  * import { Suspense } from 'preact/compat'
diff --git a/packages/preact-query/src/useSuspenseQuery.ts b/packages/preact-query/src/useSuspenseQuery.ts
index 71576c758db..5e92d8aa351 100644
--- a/packages/preact-query/src/useSuspenseQuery.ts
+++ b/packages/preact-query/src/useSuspenseQuery.ts
@@ -9,14 +9,14 @@ import { useBaseQuery } from './useBaseQuery'
  * The options for `useSuspenseQuery` are the same as for `useQuery`, except for `throwOnError`, `enabled`, and
  * `placeholderData`.
  *
+ * Caveat: cancellation does not work.
+ *
  * @param options - The {@link UseSuspenseQueryOptions} to use — the same options as `useQuery`, minus the ones listed above.
  * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
  * be used.
  * @returns The same object as `useQuery`, except that `data` is guaranteed to be defined, `isPlaceholderData`
  * is missing, and `status` is either `success` or `error` (with the derived flags set accordingly).
  *
- * Caveat: cancellation does not work.
- *
  * @example
  * ```tsx
  * import { Suspense } from 'preact/compat'

From 41143d56b8731c49d8b6f1c564bc11e691b57351 Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Tue, 25 Aug 2026 02:30:49 +0900
Subject: [PATCH 23/28] docs(preact-query): soften remaining overstated queryFn
 requirement in Suspense options

---
 .../reference/interfaces/UseSuspenseInfiniteQueryOptions.md   | 2 +-
 .../preact/reference/interfaces/UseSuspenseQueryOptions.md    | 2 +-
 packages/preact-query/src/types.ts                            | 4 ++--
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/framework/preact/reference/interfaces/UseSuspenseInfiniteQueryOptions.md b/docs/framework/preact/reference/interfaces/UseSuspenseInfiniteQueryOptions.md
index b420d6baeed..34633bf1527 100644
--- a/docs/framework/preact/reference/interfaces/UseSuspenseInfiniteQueryOptions.md
+++ b/docs/framework/preact/reference/interfaces/UseSuspenseInfiniteQueryOptions.md
@@ -42,7 +42,7 @@ optional queryFn: QueryFunction<TQueryFnData, TQueryKey, TPageParam>;
 Defined in: [preact-query/src/types.ts:190](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L190)
 
 `skipToken` is not allowed here — Suspense hooks cannot render a "disabled" state, so a query function
-must always be provided.
+must always be provided, unless a default query function has been defined.
 
 ***
 
diff --git a/docs/framework/preact/reference/interfaces/UseSuspenseQueryOptions.md b/docs/framework/preact/reference/interfaces/UseSuspenseQueryOptions.md
index 1f2ed068bf8..55b0854f7f0 100644
--- a/docs/framework/preact/reference/interfaces/UseSuspenseQueryOptions.md
+++ b/docs/framework/preact/reference/interfaces/UseSuspenseQueryOptions.md
@@ -38,7 +38,7 @@ optional queryFn: QueryFunction<TQueryFnData, TQueryKey, never>;
 Defined in: [preact-query/src/types.ts:138](https://github.com/TanStack/query/blob/main/packages/preact-query/src/types.ts#L138)
 
 `skipToken` is not allowed here — Suspense hooks cannot render a "disabled" state, so a query function
-must always be provided.
+must always be provided, unless a default query function has been defined.
 
 ***
 
diff --git a/packages/preact-query/src/types.ts b/packages/preact-query/src/types.ts
index 428b493fa4a..c23cbf38f90 100644
--- a/packages/preact-query/src/types.ts
+++ b/packages/preact-query/src/types.ts
@@ -133,7 +133,7 @@ export interface UseSuspenseQueryOptions<
 > {
   /**
    * `skipToken` is not allowed here — Suspense hooks cannot render a "disabled" state, so a query function
-   * must always be provided.
+   * must always be provided, unless a default query function has been defined.
    */
   queryFn?: Exclude<
     UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>['queryFn'],
@@ -185,7 +185,7 @@ export interface UseSuspenseInfiniteQueryOptions<
 > {
   /**
    * `skipToken` is not allowed here — Suspense hooks cannot render a "disabled" state, so a query function
-   * must always be provided.
+   * must always be provided, unless a default query function has been defined.
    */
   queryFn?: Exclude<
     UseInfiniteQueryOptions<

From accd316025eda4a953236e86212953ffb2ec00f5 Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Tue, 25 Aug 2026 02:59:16 +0900
Subject: [PATCH 24/28] docs(preact-query): fix inaccurate prose in hydration,
 queryFn, and useQueries docs

---
 .../preact/reference/functions/HydrationBoundary.md   |  5 +++--
 .../reference/functions/QueryErrorResetBoundary.md    |  3 ++-
 .../reference/functions/infiniteQueryOptions.md       |  2 +-
 .../preact/reference/functions/queryOptions.md        |  9 ++++-----
 .../reference/functions/usePrefetchInfiniteQuery.md   |  7 +++----
 .../preact/reference/functions/useQueries.md          | 11 +++++++----
 docs/framework/preact/reference/functions/useQuery.md |  6 +++---
 .../reference/functions/useQueryErrorResetBoundary.md |  3 ++-
 .../reference/interfaces/HydrationBoundaryProps.md    |  8 +++++---
 .../interfaces/QueryErrorResetBoundaryProps.md        |  4 ++--
 .../type-aliases/DefinedInitialDataOptions.md         |  4 +++-
 .../type-aliases/QueryErrorResetBoundaryFunction.md   |  2 +-
 packages/preact-query/src/HydrationBoundary.tsx       |  7 +++++--
 packages/preact-query/src/QueryErrorResetBoundary.tsx |  2 ++
 packages/preact-query/src/infiniteQueryOptions.ts     |  2 +-
 packages/preact-query/src/queryOptions.ts             |  7 ++++---
 .../preact-query/src/usePrefetchInfiniteQuery.tsx     |  5 ++---
 packages/preact-query/src/useQueries.ts               |  9 ++++++---
 packages/preact-query/src/useQuery.ts                 |  6 +++---
 19 files changed, 59 insertions(+), 43 deletions(-)

diff --git a/docs/framework/preact/reference/functions/HydrationBoundary.md b/docs/framework/preact/reference/functions/HydrationBoundary.md
index 64d64e83b97..9d89cf9c80d 100644
--- a/docs/framework/preact/reference/functions/HydrationBoundary.md
+++ b/docs/framework/preact/reference/functions/HydrationBoundary.md
@@ -7,7 +7,7 @@ title: HydrationBoundary
 function HydrationBoundary(__namedParameters): Element;
 ```
 
-Defined in: [preact-query/src/HydrationBoundary.tsx:77](https://github.com/TanStack/query/blob/main/packages/preact-query/src/HydrationBoundary.tsx#L77)
+Defined in: [preact-query/src/HydrationBoundary.tsx:80](https://github.com/TanStack/query/blob/main/packages/preact-query/src/HydrationBoundary.tsx#L80)
 
 `HydrationBoundary` adds a previously dehydrated state into the `queryClient` that would be returned by
 `useQueryClient()`. If the client already contains data, the new queries will be intelligently merged based on
@@ -25,7 +25,8 @@ Note: Only `queries` can be dehydrated with an `HydrationBoundary`.
 
 `Element`
 
-The provided `children`, rendered once `state` has been hydrated into the cache.
+The provided `children`, rendered unconditionally. New queries in `state` are hydrated into the
+cache during render; queries already in the cache are hydrated in an effect after commit.
 
 ## Examples
 
diff --git a/docs/framework/preact/reference/functions/QueryErrorResetBoundary.md b/docs/framework/preact/reference/functions/QueryErrorResetBoundary.md
index 80287b478b9..77a8e448092 100644
--- a/docs/framework/preact/reference/functions/QueryErrorResetBoundary.md
+++ b/docs/framework/preact/reference/functions/QueryErrorResetBoundary.md
@@ -7,7 +7,7 @@ title: QueryErrorResetBoundary
 function QueryErrorResetBoundary(__namedParameters): Element;
 ```
 
-Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:152](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L152)
+Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:154](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L154)
 
 When using **suspense** or **throwOnError** in your queries, you need a way to let queries know that you want to
 try again when re-rendering after some error occurred. With the `QueryErrorResetBoundary` component you can
@@ -30,6 +30,7 @@ if `children` is a function.
 
 ```tsx
 import { useErrorBoundary } from 'preact/hooks'
+import type { ComponentChildren } from 'preact'
 import { QueryErrorResetBoundary } from '@tanstack/preact-query'
 
 function ErrorBoundary({
diff --git a/docs/framework/preact/reference/functions/infiniteQueryOptions.md b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
index 7d9b84b6caf..65f64fc0875 100644
--- a/docs/framework/preact/reference/functions/infiniteQueryOptions.md
+++ b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
@@ -15,7 +15,7 @@ You can generally pass everything to `infiniteQueryOptions` that you can also pa
 These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
 `options.queryKey` is required and is the query key to generate options for.
 
-This overload is selected when `initialData` is set, so the resulting `data` is never `undefined`.
+This overload is selected when `initialData` is set.
 
 ### Type Parameters
 
diff --git a/docs/framework/preact/reference/functions/queryOptions.md b/docs/framework/preact/reference/functions/queryOptions.md
index 6f81946d5dd..99d29ec22ba 100644
--- a/docs/framework/preact/reference/functions/queryOptions.md
+++ b/docs/framework/preact/reference/functions/queryOptions.md
@@ -9,14 +9,13 @@ 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:102](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L102)
+Defined in: [preact-query/src/queryOptions.ts:103](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L103)
 
 You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can
 be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and
 is the query key to generate options for.
 
-This overload is selected when `initialData` is set, so `queryFn` is optional and the resulting `data` is
-never `undefined`.
+This overload is selected when `initialData` is set, so the resulting `data` is never `undefined`.
 
 ### Type Parameters
 
@@ -72,7 +71,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:166](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L166)
+Defined in: [preact-query/src/queryOptions.ts:167](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L167)
 
 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
@@ -159,7 +158,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:230](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L230)
+Defined in: [preact-query/src/queryOptions.ts:231](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L231)
 
 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/usePrefetchInfiniteQuery.md b/docs/framework/preact/reference/functions/usePrefetchInfiniteQuery.md
index d11a14cae59..f5ee14bcb9c 100644
--- a/docs/framework/preact/reference/functions/usePrefetchInfiniteQuery.md
+++ b/docs/framework/preact/reference/functions/usePrefetchInfiniteQuery.md
@@ -7,7 +7,7 @@ title: usePrefetchInfiniteQuery
 function usePrefetchInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): void;
 ```
 
-Defined in: [preact-query/src/usePrefetchInfiniteQuery.tsx:48](https://github.com/TanStack/query/blob/main/packages/preact-query/src/usePrefetchInfiniteQuery.tsx#L48)
+Defined in: [preact-query/src/usePrefetchInfiniteQuery.tsx:47](https://github.com/TanStack/query/blob/main/packages/preact-query/src/usePrefetchInfiniteQuery.tsx#L47)
 
 `usePrefetchInfiniteQuery` does not return anything, it should be used just to fire a prefetch during render,
 before a suspense boundary that wraps a component that uses `useSuspenseInfiniteQuery`. You can pass
@@ -16,9 +16,8 @@ everything to `usePrefetchInfiniteQuery` that you can pass to `queryClient.fetch
 a default query function has been defined.
 
 `getNextPageParam` receives both the last page of the infinite list of data and the full array of all pages,
-as well as pageParam information, and should return a single variable that will be passed as the last
-optional parameter to your query function. Return `undefined` or `null` to indicate there is no next page
-available.
+as well as pageParam information, and should return a single variable that will be passed to your query
+function as `context.pageParam`. Return `undefined` or `null` to indicate there is no next page available.
 
 ## Type Parameters
 
diff --git a/docs/framework/preact/reference/functions/useQueries.md b/docs/framework/preact/reference/functions/useQueries.md
index 8b64636a918..3078250b822 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:256](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQueries.ts#L256)
+Defined in: [preact-query/src/useQueries.ts:257](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQueries.ts#L257)
 
 The `useQueries` hook can be used to fetch a variable number of queries.
 
@@ -47,8 +47,10 @@ shared to be as referentially stable as possible.
   \| readonly \[`T` *extends* \[\] ? \[\] : `T` *extends* \[`Head`\] ? \[`GetUseQueryOptionsForUseQueries`\<`Head`\>\] : `T` *extends* \[`Head`, `...Tails[]`\] ? \[`...Tails[]`\] *extends* \[\] ? \[\] : \[`...Tails[]`\] *extends* \[`Head`\] ? \[`GetUseQueryOptionsForUseQueries`\<`Head`\>, `GetUseQueryOptionsForUseQueries`\<`Head`\>\] : \[`...Tails[]`\] *extends* \[`Head`, `...Tails[]`\] ? \[`...(...)[]`\] *extends* \[\] ? \[\] : ... *extends* ... ? ... : ... : readonly ...[] *extends* \[`...(...)[]`\] ? \[`...(...)[]`\] : ... *extends* ... ? ... : ... : readonly `unknown`[] *extends* `T` ? `T` : `T` *extends* `UseQueryOptionsForUseQueries`\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>[] ? `UseQueryOptionsForUseQueries`\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>[] : `UseQueryOptionsForUseQueries`\<`unknown`, `Error`, `unknown`, readonly ...[]\>[]\]
   \| readonly \[\{ \[K in string \| number \| symbol\]: GetUseQueryOptionsForUseQueries\<T\[K\<K\>\]\> \}\]
 
-An array with query option objects identical to `useQuery` (excluding the `queryClient` option, since
-the `QueryClient` can be passed in on the top level).
+An array with query option objects, mostly identical to `useQuery` — except that `queryClient` and
+`subscribed` aren't accepted per-query (`subscribed` is a top-level option here instead), and
+`placeholderData` accepts a QueriesPlaceholderDataFunction rather than `useQuery`'s
+single-argument placeholder function.
 
 #### subscribed?
 
@@ -67,7 +69,8 @@ will be used.
 
 `TCombinedResult`
 
-An array with all the query results. The order returned is the same as the input order.
+The combined result. Without `combine`, this is an array with all the query results, in the same
+order as the input. When `combine` is provided, this is the value returned by `combine` instead.
 
 ## Examples
 
diff --git a/docs/framework/preact/reference/functions/useQuery.md b/docs/framework/preact/reference/functions/useQuery.md
index c2127e0b5f3..307464f1207 100644
--- a/docs/framework/preact/reference/functions/useQuery.md
+++ b/docs/framework/preact/reference/functions/useQuery.md
@@ -227,11 +227,11 @@ A dependent query, only enabled once `postId` is set:
 ```tsx
 import { useQuery } from '@tanstack/preact-query'
 
-function Post({ postId }: { postId: number }) {
+function Post({ postId }: { postId: number | undefined }) {
   const { data } = useQuery({
     queryKey: ['post', postId],
-    queryFn: () => fetchPost(postId),
-    enabled: !!postId,
+    queryFn: () => fetchPost(postId!),
+    enabled: postId != null,
   })
 
   return <h1>{data?.title}</h1>
diff --git a/docs/framework/preact/reference/functions/useQueryErrorResetBoundary.md b/docs/framework/preact/reference/functions/useQueryErrorResetBoundary.md
index b2d33cf6799..15ec961a2b7 100644
--- a/docs/framework/preact/reference/functions/useQueryErrorResetBoundary.md
+++ b/docs/framework/preact/reference/functions/useQueryErrorResetBoundary.md
@@ -7,7 +7,7 @@ title: useQueryErrorResetBoundary
 function useQueryErrorResetBoundary(): QueryErrorResetBoundaryValue;
 ```
 
-Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:84](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L84)
+Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:85](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L85)
 
 This hook will reset any query errors within the closest `QueryErrorResetBoundary`. If there is no boundary
 defined it will reset them globally.
@@ -22,6 +22,7 @@ The boundary's QueryErrorResetBoundaryValue.
 
 ```tsx
 import { useErrorBoundary } from 'preact/hooks'
+import type { ComponentChildren } from 'preact'
 import { useQueryErrorResetBoundary } from '@tanstack/preact-query'
 
 function App({ children }: { children: ComponentChildren }) {
diff --git a/docs/framework/preact/reference/interfaces/HydrationBoundaryProps.md b/docs/framework/preact/reference/interfaces/HydrationBoundaryProps.md
index 418680c1c09..d6cad38a7ef 100644
--- a/docs/framework/preact/reference/interfaces/HydrationBoundaryProps.md
+++ b/docs/framework/preact/reference/interfaces/HydrationBoundaryProps.md
@@ -13,9 +13,11 @@ Defined in: [preact-query/src/HydrationBoundary.tsx:14](https://github.com/TanSt
 optional children: ComponentChildren;
 ```
 
-Defined in: [preact-query/src/HydrationBoundary.tsx:31](https://github.com/TanStack/query/blob/main/packages/preact-query/src/HydrationBoundary.tsx#L31)
+Defined in: [preact-query/src/HydrationBoundary.tsx:33](https://github.com/TanStack/query/blob/main/packages/preact-query/src/HydrationBoundary.tsx#L33)
 
-The components that render once the dehydrated state has been hydrated into the cache.
+The components to render — always rendered unconditionally, not gated on hydration. New queries are
+hydrated into the cache during render; queries that already exist in the cache are hydrated in an effect
+after commit, so `children` may render briefly before that fresher data lands.
 
 ***
 
@@ -46,7 +48,7 @@ optional defaultOptions: OmitKeyof<{
 optional queryClient: QueryClient;
 ```
 
-Defined in: [preact-query/src/HydrationBoundary.tsx:35](https://github.com/TanStack/query/blob/main/packages/preact-query/src/HydrationBoundary.tsx#L35)
+Defined in: [preact-query/src/HydrationBoundary.tsx:37](https://github.com/TanStack/query/blob/main/packages/preact-query/src/HydrationBoundary.tsx#L37)
 
 Use this to use a custom QueryClient. Otherwise, the one from the nearest context will be used.
 
diff --git a/docs/framework/preact/reference/interfaces/QueryErrorResetBoundaryProps.md b/docs/framework/preact/reference/interfaces/QueryErrorResetBoundaryProps.md
index ab613307d9f..e9806c8a578 100644
--- a/docs/framework/preact/reference/interfaces/QueryErrorResetBoundaryProps.md
+++ b/docs/framework/preact/reference/interfaces/QueryErrorResetBoundaryProps.md
@@ -3,7 +3,7 @@ id: QueryErrorResetBoundaryProps
 title: QueryErrorResetBoundaryProps
 ---
 
-Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:99](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L99)
+Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:100](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L100)
 
 ## Properties
 
@@ -15,7 +15,7 @@ children:
   | QueryErrorResetBoundaryFunction;
 ```
 
-Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:104](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L104)
+Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:105](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L105)
 
 Either a plain node, or a function that receives the boundary's QueryErrorResetBoundaryValue and
 returns a node.
diff --git a/docs/framework/preact/reference/type-aliases/DefinedInitialDataOptions.md b/docs/framework/preact/reference/type-aliases/DefinedInitialDataOptions.md
index d73bb22cbc0..111e13a49f4 100644
--- a/docs/framework/preact/reference/type-aliases/DefinedInitialDataOptions.md
+++ b/docs/framework/preact/reference/type-aliases/DefinedInitialDataOptions.md
@@ -31,7 +31,9 @@ cache.
 optional queryFn: QueryFunction<TQueryFnData, TQueryKey>;
 ```
 
-Optional here — since `initialData` is set, the query already has data to display without a query function.
+Optional here, but omitting it is only safe when no fetch will be attempted — for example with
+`enabled: false`, or when a default query function has been defined. Otherwise, an enabled query with no
+`queryFn` still tries to fetch and fails with a "Missing queryFn" error; `initialData` does not prevent this.
 
 ## Type Parameters
 
diff --git a/docs/framework/preact/reference/type-aliases/QueryErrorResetBoundaryFunction.md b/docs/framework/preact/reference/type-aliases/QueryErrorResetBoundaryFunction.md
index f826081fb3f..2ed65c16cb7 100644
--- a/docs/framework/preact/reference/type-aliases/QueryErrorResetBoundaryFunction.md
+++ b/docs/framework/preact/reference/type-aliases/QueryErrorResetBoundaryFunction.md
@@ -7,7 +7,7 @@ title: QueryErrorResetBoundaryFunction
 type QueryErrorResetBoundaryFunction = (value) => ComponentChildren;
 ```
 
-Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:95](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L95)
+Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:96](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L96)
 
 A render-prop function usable as `children` on `QueryErrorResetBoundary`.
 
diff --git a/packages/preact-query/src/HydrationBoundary.tsx b/packages/preact-query/src/HydrationBoundary.tsx
index 10be3ece80d..841c093f9da 100644
--- a/packages/preact-query/src/HydrationBoundary.tsx
+++ b/packages/preact-query/src/HydrationBoundary.tsx
@@ -26,7 +26,9 @@ export interface HydrationBoundaryProps {
     >
   }
   /**
-   * The components that render once the dehydrated state has been hydrated into the cache.
+   * The components to render — always rendered unconditionally, not gated on hydration. New queries are
+   * hydrated into the cache during render; queries that already exist in the cache are hydrated in an effect
+   * after commit, so `children` may render briefly before that fresher data lands.
    */
   children?: ComponentChildren
   /**
@@ -42,7 +44,8 @@ export interface HydrationBoundaryProps {
  *
  * Note: Only `queries` can be dehydrated with an `HydrationBoundary`.
  *
- * @returns The provided `children`, rendered once `state` has been hydrated into the cache.
+ * @returns The provided `children`, rendered unconditionally. New queries in `state` are hydrated into the
+ * cache during render; queries already in the cache are hydrated in an effect after commit.
  *
  * @example
  * ```tsx
diff --git a/packages/preact-query/src/QueryErrorResetBoundary.tsx b/packages/preact-query/src/QueryErrorResetBoundary.tsx
index 3468ffa7563..02ace5ddda0 100644
--- a/packages/preact-query/src/QueryErrorResetBoundary.tsx
+++ b/packages/preact-query/src/QueryErrorResetBoundary.tsx
@@ -62,6 +62,7 @@ const QueryErrorResetBoundaryContext = createContext(createValue())
  * @example
  * ```tsx
  * import { useErrorBoundary } from 'preact/hooks'
+ * import type { ComponentChildren } from 'preact'
  * import { useQueryErrorResetBoundary } from '@tanstack/preact-query'
  *
  * function App({ children }: { children: ComponentChildren }) {
@@ -115,6 +116,7 @@ export interface QueryErrorResetBoundaryProps {
  * @example
  * ```tsx
  * import { useErrorBoundary } from 'preact/hooks'
+ * import type { ComponentChildren } from 'preact'
  * import { QueryErrorResetBoundary } from '@tanstack/preact-query'
  *
  * function ErrorBoundary({
diff --git a/packages/preact-query/src/infiniteQueryOptions.ts b/packages/preact-query/src/infiniteQueryOptions.ts
index de91a207e7e..87a4a75eced 100644
--- a/packages/preact-query/src/infiniteQueryOptions.ts
+++ b/packages/preact-query/src/infiniteQueryOptions.ts
@@ -96,7 +96,7 @@ export type DefinedInitialDataInfiniteOptions<
  * These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
  * `options.queryKey` is required and is the query key to generate options for.
  *
- * This overload is selected when `initialData` is set, so the resulting `data` is never `undefined`.
+ * This overload is selected when `initialData` is set.
  *
  * @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.
diff --git a/packages/preact-query/src/queryOptions.ts b/packages/preact-query/src/queryOptions.ts
index c677e43846a..56e4b1f86e2 100644
--- a/packages/preact-query/src/queryOptions.ts
+++ b/packages/preact-query/src/queryOptions.ts
@@ -66,7 +66,9 @@ export type DefinedInitialDataOptions<
     | NonUndefinedGuard<TQueryFnData>
     | (() => NonUndefinedGuard<TQueryFnData>)
   /**
-   * Optional here — since `initialData` is set, the query already has data to display without a query function.
+   * Optional here, but omitting it is only safe when no fetch will be attempted — for example with
+   * `enabled: false`, or when a default query function has been defined. Otherwise, an enabled query with no
+   * `queryFn` still tries to fetch and fails with a "Missing queryFn" error; `initialData` does not prevent this.
    */
   queryFn?: QueryFunction<TQueryFnData, TQueryKey>
 }
@@ -76,8 +78,7 @@ export type DefinedInitialDataOptions<
  * be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and
  * is the query key to generate options for.
  *
- * This overload is selected when `initialData` is set, so `queryFn` is optional and the resulting `data` is
- * never `undefined`.
+ * This overload is selected when `initialData` is set, so the resulting `data` is never `undefined`.
  *
  * @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.
diff --git a/packages/preact-query/src/usePrefetchInfiniteQuery.tsx b/packages/preact-query/src/usePrefetchInfiniteQuery.tsx
index f504e8faaa1..469572225dc 100644
--- a/packages/preact-query/src/usePrefetchInfiniteQuery.tsx
+++ b/packages/preact-query/src/usePrefetchInfiniteQuery.tsx
@@ -12,9 +12,8 @@ import type { UsePrefetchInfiniteQueryOptions } from './types'
  * a default query function has been defined.
  *
  * `getNextPageParam` receives both the last page of the infinite list of data and the full array of all pages,
- * as well as pageParam information, and should return a single variable that will be passed as the last
- * optional parameter to your query function. Return `undefined` or `null` to indicate there is no next page
- * available.
+ * as well as pageParam information, and should return a single variable that will be passed to your query
+ * function as `context.pageParam`. Return `undefined` or `null` to indicate there is no next page available.
  *
  * @param options - The {@link UsePrefetchInfiniteQueryOptions} to use — everything you can pass to `queryClient.fetchInfiniteQuery`.
  * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
diff --git a/packages/preact-query/src/useQueries.ts b/packages/preact-query/src/useQueries.ts
index 0cdd0e76a19..477bee2b600 100644
--- a/packages/preact-query/src/useQueries.ts
+++ b/packages/preact-query/src/useQueries.ts
@@ -219,7 +219,8 @@ export type QueriesResults<
  *
  * @param queryClient - Use this to provide a custom QueryClient. Otherwise, the one from the nearest context
  * will be used.
- * @returns An array with all the query results. The order returned is the same as the input order.
+ * @returns The combined result. Without `combine`, this is an array with all the query results, in the same
+ * order as the input. When `combine` is provided, this is the value returned by `combine` instead.
  *
  * @example
  * ```tsx
@@ -262,8 +263,10 @@ export function useQueries<
     ...options
   }: {
     /**
-     * An array with query option objects identical to `useQuery` (excluding the `queryClient` option, since
-     * the `QueryClient` can be passed in on the top level).
+     * An array with query option objects, mostly identical to `useQuery` — except that `queryClient` and
+     * `subscribed` aren't accepted per-query (`subscribed` is a top-level option here instead), and
+     * `placeholderData` accepts a {@link QueriesPlaceholderDataFunction} rather than `useQuery`'s
+     * single-argument placeholder function.
      */
     queries:
       | readonly [...QueriesOptions<T>]
diff --git a/packages/preact-query/src/useQuery.ts b/packages/preact-query/src/useQuery.ts
index 60af51724e5..2c59c79f95b 100644
--- a/packages/preact-query/src/useQuery.ts
+++ b/packages/preact-query/src/useQuery.ts
@@ -131,11 +131,11 @@ export function useQuery<
  * ```tsx
  * import { useQuery } from '@tanstack/preact-query'
  *
- * function Post({ postId }: { postId: number }) {
+ * function Post({ postId }: { postId: number | undefined }) {
  *   const { data } = useQuery({
  *     queryKey: ['post', postId],
- *     queryFn: () => fetchPost(postId),
- *     enabled: !!postId,
+ *     queryFn: () => fetchPost(postId!),
+ *     enabled: postId != null,
  *   })
  *
  *   return <h1>{data?.title}</h1>

From 37790c66bf5552bd72c5ad647fd76df82043424c Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Tue, 25 Aug 2026 03:11:11 +0900
Subject: [PATCH 25/28] docs(preact-query): correct hydration freshness gate,
 placeholderData arity, and deprecated 'fetchInfiniteQuery' reference

---
 .../preact/reference/functions/HydrationBoundary.md      | 5 +++--
 .../reference/functions/usePrefetchInfiniteQuery.md      | 4 ++--
 docs/framework/preact/reference/functions/useQueries.md  | 4 ++--
 .../reference/interfaces/HydrationBoundaryProps.md       | 9 +++++----
 packages/preact-query/src/HydrationBoundary.tsx          | 8 +++++---
 packages/preact-query/src/usePrefetchInfiniteQuery.tsx   | 4 ++--
 packages/preact-query/src/useQueries.ts                  | 4 ++--
 7 files changed, 21 insertions(+), 17 deletions(-)

diff --git a/docs/framework/preact/reference/functions/HydrationBoundary.md b/docs/framework/preact/reference/functions/HydrationBoundary.md
index 9d89cf9c80d..ae59d595ab8 100644
--- a/docs/framework/preact/reference/functions/HydrationBoundary.md
+++ b/docs/framework/preact/reference/functions/HydrationBoundary.md
@@ -7,7 +7,7 @@ title: HydrationBoundary
 function HydrationBoundary(__namedParameters): Element;
 ```
 
-Defined in: [preact-query/src/HydrationBoundary.tsx:80](https://github.com/TanStack/query/blob/main/packages/preact-query/src/HydrationBoundary.tsx#L80)
+Defined in: [preact-query/src/HydrationBoundary.tsx:82](https://github.com/TanStack/query/blob/main/packages/preact-query/src/HydrationBoundary.tsx#L82)
 
 `HydrationBoundary` adds a previously dehydrated state into the `queryClient` that would be returned by
 `useQueryClient()`. If the client already contains data, the new queries will be intelligently merged based on
@@ -26,7 +26,8 @@ Note: Only `queries` can be dehydrated with an `HydrationBoundary`.
 `Element`
 
 The provided `children`, rendered unconditionally. New queries in `state` are hydrated into the
-cache during render; queries already in the cache are hydrated in an effect after commit.
+cache during render; for queries already in the cache, only newer dehydrated data is hydrated, in an effect
+after commit.
 
 ## Examples
 
diff --git a/docs/framework/preact/reference/functions/usePrefetchInfiniteQuery.md b/docs/framework/preact/reference/functions/usePrefetchInfiniteQuery.md
index f5ee14bcb9c..465bb7c5f1b 100644
--- a/docs/framework/preact/reference/functions/usePrefetchInfiniteQuery.md
+++ b/docs/framework/preact/reference/functions/usePrefetchInfiniteQuery.md
@@ -11,7 +11,7 @@ Defined in: [preact-query/src/usePrefetchInfiniteQuery.tsx:47](https://github.co
 
 `usePrefetchInfiniteQuery` does not return anything, it should be used just to fire a prefetch during render,
 before a suspense boundary that wraps a component that uses `useSuspenseInfiniteQuery`. You can pass
-everything to `usePrefetchInfiniteQuery` that you can pass to `queryClient.fetchInfiniteQuery`, though
+everything to `usePrefetchInfiniteQuery` that you can pass to `queryClient.infiniteQuery`, though
 `queryKey`, `initialPageParam`, and `getNextPageParam` are always required, and `queryFn` is required unless
 a default query function has been defined.
 
@@ -47,7 +47,7 @@ function as `context.pageParam`. Return `undefined` or `null` to indicate there
 
 [`UsePrefetchInfiniteQueryOptions`](../type-aliases/UsePrefetchInfiniteQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\>
 
-The [UsePrefetchInfiniteQueryOptions](../type-aliases/UsePrefetchInfiniteQueryOptions.md) to use — everything you can pass to `queryClient.fetchInfiniteQuery`.
+The [UsePrefetchInfiniteQueryOptions](../type-aliases/UsePrefetchInfiniteQueryOptions.md) to use — everything you can pass to `queryClient.infiniteQuery`.
 
 ### queryClient?
 
diff --git a/docs/framework/preact/reference/functions/useQueries.md b/docs/framework/preact/reference/functions/useQueries.md
index 3078250b822..aa7a7760872 100644
--- a/docs/framework/preact/reference/functions/useQueries.md
+++ b/docs/framework/preact/reference/functions/useQueries.md
@@ -49,8 +49,8 @@ shared to be as referentially stable as possible.
 
 An array with query option objects, mostly identical to `useQuery` — except that `queryClient` and
 `subscribed` aren't accepted per-query (`subscribed` is a top-level option here instead), and
-`placeholderData` accepts a QueriesPlaceholderDataFunction rather than `useQuery`'s
-single-argument placeholder function.
+`placeholderData` accepts a QueriesPlaceholderDataFunction, which is called with `previousData`
+and `previousQuery` always `undefined`, rather than `useQuery`'s placeholder function.
 
 #### subscribed?
 
diff --git a/docs/framework/preact/reference/interfaces/HydrationBoundaryProps.md b/docs/framework/preact/reference/interfaces/HydrationBoundaryProps.md
index d6cad38a7ef..2760f4a917d 100644
--- a/docs/framework/preact/reference/interfaces/HydrationBoundaryProps.md
+++ b/docs/framework/preact/reference/interfaces/HydrationBoundaryProps.md
@@ -13,11 +13,12 @@ Defined in: [preact-query/src/HydrationBoundary.tsx:14](https://github.com/TanSt
 optional children: ComponentChildren;
 ```
 
-Defined in: [preact-query/src/HydrationBoundary.tsx:33](https://github.com/TanStack/query/blob/main/packages/preact-query/src/HydrationBoundary.tsx#L33)
+Defined in: [preact-query/src/HydrationBoundary.tsx:34](https://github.com/TanStack/query/blob/main/packages/preact-query/src/HydrationBoundary.tsx#L34)
 
 The components to render — always rendered unconditionally, not gated on hydration. New queries are
-hydrated into the cache during render; queries that already exist in the cache are hydrated in an effect
-after commit, so `children` may render briefly before that fresher data lands.
+hydrated into the cache during render; for queries that already exist in the cache, only newer dehydrated
+data is hydrated, and that happens in an effect after commit, so `children` may render briefly before it
+lands.
 
 ***
 
@@ -48,7 +49,7 @@ optional defaultOptions: OmitKeyof<{
 optional queryClient: QueryClient;
 ```
 
-Defined in: [preact-query/src/HydrationBoundary.tsx:37](https://github.com/TanStack/query/blob/main/packages/preact-query/src/HydrationBoundary.tsx#L37)
+Defined in: [preact-query/src/HydrationBoundary.tsx:38](https://github.com/TanStack/query/blob/main/packages/preact-query/src/HydrationBoundary.tsx#L38)
 
 Use this to use a custom QueryClient. Otherwise, the one from the nearest context will be used.
 
diff --git a/packages/preact-query/src/HydrationBoundary.tsx b/packages/preact-query/src/HydrationBoundary.tsx
index 841c093f9da..98b253ed5a5 100644
--- a/packages/preact-query/src/HydrationBoundary.tsx
+++ b/packages/preact-query/src/HydrationBoundary.tsx
@@ -27,8 +27,9 @@ export interface HydrationBoundaryProps {
   }
   /**
    * The components to render — always rendered unconditionally, not gated on hydration. New queries are
-   * hydrated into the cache during render; queries that already exist in the cache are hydrated in an effect
-   * after commit, so `children` may render briefly before that fresher data lands.
+   * hydrated into the cache during render; for queries that already exist in the cache, only newer dehydrated
+   * data is hydrated, and that happens in an effect after commit, so `children` may render briefly before it
+   * lands.
    */
   children?: ComponentChildren
   /**
@@ -45,7 +46,8 @@ export interface HydrationBoundaryProps {
  * Note: Only `queries` can be dehydrated with an `HydrationBoundary`.
  *
  * @returns The provided `children`, rendered unconditionally. New queries in `state` are hydrated into the
- * cache during render; queries already in the cache are hydrated in an effect after commit.
+ * cache during render; for queries already in the cache, only newer dehydrated data is hydrated, in an effect
+ * after commit.
  *
  * @example
  * ```tsx
diff --git a/packages/preact-query/src/usePrefetchInfiniteQuery.tsx b/packages/preact-query/src/usePrefetchInfiniteQuery.tsx
index 469572225dc..33040037f87 100644
--- a/packages/preact-query/src/usePrefetchInfiniteQuery.tsx
+++ b/packages/preact-query/src/usePrefetchInfiniteQuery.tsx
@@ -7,7 +7,7 @@ import type { UsePrefetchInfiniteQueryOptions } from './types'
 /**
  * `usePrefetchInfiniteQuery` does not return anything, it should be used just to fire a prefetch during render,
  * before a suspense boundary that wraps a component that uses `useSuspenseInfiniteQuery`. You can pass
- * everything to `usePrefetchInfiniteQuery` that you can pass to `queryClient.fetchInfiniteQuery`, though
+ * everything to `usePrefetchInfiniteQuery` that you can pass to `queryClient.infiniteQuery`, though
  * `queryKey`, `initialPageParam`, and `getNextPageParam` are always required, and `queryFn` is required unless
  * a default query function has been defined.
  *
@@ -15,7 +15,7 @@ import type { UsePrefetchInfiniteQueryOptions } from './types'
  * as well as pageParam information, and should return a single variable that will be passed to your query
  * function as `context.pageParam`. Return `undefined` or `null` to indicate there is no next page available.
  *
- * @param options - The {@link UsePrefetchInfiniteQueryOptions} to use — everything you can pass to `queryClient.fetchInfiniteQuery`.
+ * @param options - The {@link UsePrefetchInfiniteQueryOptions} to use — everything you can pass to `queryClient.infiniteQuery`.
  * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
  * be used.
  * @returns `void` — nothing is returned.
diff --git a/packages/preact-query/src/useQueries.ts b/packages/preact-query/src/useQueries.ts
index 477bee2b600..b67b73988df 100644
--- a/packages/preact-query/src/useQueries.ts
+++ b/packages/preact-query/src/useQueries.ts
@@ -265,8 +265,8 @@ export function useQueries<
     /**
      * An array with query option objects, mostly identical to `useQuery` — except that `queryClient` and
      * `subscribed` aren't accepted per-query (`subscribed` is a top-level option here instead), and
-     * `placeholderData` accepts a {@link QueriesPlaceholderDataFunction} rather than `useQuery`'s
-     * single-argument placeholder function.
+     * `placeholderData` accepts a {@link QueriesPlaceholderDataFunction}, which is called with `previousData`
+     * and `previousQuery` always `undefined`, rather than `useQuery`'s placeholder function.
      */
     queries:
       | readonly [...QueriesOptions<T>]

From da48c99fc346c8db38eb8fdf544fd2efa1621713 Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Tue, 25 Aug 2026 03:20:57 +0900
Subject: [PATCH 26/28] docs(preact-query): remove leftover 'data is never
 undefined' claim in 'useInfiniteQuery' overload docs

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

diff --git a/docs/framework/preact/reference/functions/infiniteQueryOptions.md b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
index 65f64fc0875..259cc990206 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:123](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L123)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:122](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L122)
 
 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`.
@@ -65,7 +65,6 @@ export const projectsOptions = infiniteQueryOptions({
 })
 
 function Projects() {
-  // `data` is never `undefined`, thanks to `initialData`.
   const { data } = useInfiniteQuery(projectsOptions)
   return <>{data.pages.map((page) => page.projects.map((p) => <p key={p.id}>{p.name}</p>))}</>
 }
@@ -77,7 +76,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:194](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L194)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:193](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L193)
 
 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`.
@@ -162,7 +161,7 @@ queryClient.prefetchInfiniteQuery(commentsOptions(postId))
 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:265](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L265)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:264](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L264)
 
 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/useInfiniteQuery.md b/docs/framework/preact/reference/functions/useInfiniteQuery.md
index 293c9b116f7..ebc08137b7f 100644
--- a/docs/framework/preact/reference/functions/useInfiniteQuery.md
+++ b/docs/framework/preact/reference/functions/useInfiniteQuery.md
@@ -9,12 +9,12 @@ title: useInfiniteQuery
 function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): DefinedUseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useInfiniteQuery.ts:52](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L52)
+Defined in: [preact-query/src/useInfiniteQuery.ts:51](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L51)
 
 The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
 `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
 
-This overload is selected when `initialData` is set, so the resulting `data` is never `undefined`.
+This overload is selected when `initialData` is set.
 
 ### Type Parameters
 
@@ -67,7 +67,6 @@ The same properties as `useQuery`, with the addition of `data.pages`, `data.page
 import { useInfiniteQuery } from '@tanstack/preact-query'
 
 function Projects() {
-  // `data` is never `undefined`, thanks to `initialData`.
   const { data } = useInfiniteQuery({
     queryKey: ['projects'],
     queryFn: ({ pageParam }) => fetchProjects(pageParam),
@@ -86,7 +85,7 @@ function Projects() {
 function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): UseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useInfiniteQuery.ts:106](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L106)
+Defined in: [preact-query/src/useInfiniteQuery.ts:105](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L105)
 
 The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
 `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
@@ -169,7 +168,7 @@ function Projects() {
 function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options, queryClient?): UseInfiniteQueryResult<TData, TError>;
 ```
 
-Defined in: [preact-query/src/useInfiniteQuery.ts:164](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L164)
+Defined in: [preact-query/src/useInfiniteQuery.ts:163](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useInfiniteQuery.ts#L163)
 
 The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
 `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
diff --git a/packages/preact-query/src/infiniteQueryOptions.ts b/packages/preact-query/src/infiniteQueryOptions.ts
index 87a4a75eced..9421eceea11 100644
--- a/packages/preact-query/src/infiniteQueryOptions.ts
+++ b/packages/preact-query/src/infiniteQueryOptions.ts
@@ -114,7 +114,6 @@ export type DefinedInitialDataInfiniteOptions<
  * })
  *
  * function Projects() {
- *   // `data` is never `undefined`, thanks to `initialData`.
  *   const { data } = useInfiniteQuery(projectsOptions)
  *   return <>{data.pages.map((page) => page.projects.map((p) => <p key={p.id}>{p.name}</p>))}</>
  * }
diff --git a/packages/preact-query/src/useInfiniteQuery.ts b/packages/preact-query/src/useInfiniteQuery.ts
index be86f96bf5b..95d2db3c02f 100644
--- a/packages/preact-query/src/useInfiniteQuery.ts
+++ b/packages/preact-query/src/useInfiniteQuery.ts
@@ -22,7 +22,7 @@ import { useBaseQuery } from './useBaseQuery'
  * The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `queryFn`,
  * `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
  *
- * This overload is selected when `initialData` is set, so the resulting `data` is never `undefined`.
+ * This overload is selected when `initialData` is set.
  *
  * @param options - The {@link DefinedInitialDataInfiniteOptions} to use — everything you can pass to `useInfiniteQuery`, with `initialData` set.
  * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
@@ -36,7 +36,6 @@ import { useBaseQuery } from './useBaseQuery'
  * import { useInfiniteQuery } from '@tanstack/preact-query'
  *
  * function Projects() {
- *   // `data` is never `undefined`, thanks to `initialData`.
  *   const { data } = useInfiniteQuery({
  *     queryKey: ['projects'],
  *     queryFn: ({ pageParam }) => fetchProjects(pageParam),

From 80e79b00f4f06537997efd399e976c9a33493afd Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Tue, 25 Aug 2026 03:30:25 +0900
Subject: [PATCH 27/28] docs(preact-query): replace deprecated
 'prefetchQuery'/'prefetchInfiniteQuery' calls in examples with
 'query'/'infiniteQuery'

---
 .../reference/functions/HydrationBoundary.md     | 13 ++++++++-----
 .../reference/functions/infiniteQueryOptions.md  | 10 ++++++----
 .../preact/reference/functions/queryOptions.md   | 16 ++++++++++------
 packages/preact-query/src/HydrationBoundary.tsx  | 11 +++++++----
 .../preact-query/src/infiniteQueryOptions.ts     |  6 ++++--
 packages/preact-query/src/queryOptions.ts        | 12 ++++++++----
 6 files changed, 43 insertions(+), 25 deletions(-)

diff --git a/docs/framework/preact/reference/functions/HydrationBoundary.md b/docs/framework/preact/reference/functions/HydrationBoundary.md
index ae59d595ab8..1a6e6bde460 100644
--- a/docs/framework/preact/reference/functions/HydrationBoundary.md
+++ b/docs/framework/preact/reference/functions/HydrationBoundary.md
@@ -7,7 +7,7 @@ title: HydrationBoundary
 function HydrationBoundary(__namedParameters): Element;
 ```
 
-Defined in: [preact-query/src/HydrationBoundary.tsx:82](https://github.com/TanStack/query/blob/main/packages/preact-query/src/HydrationBoundary.tsx#L82)
+Defined in: [preact-query/src/HydrationBoundary.tsx:85](https://github.com/TanStack/query/blob/main/packages/preact-query/src/HydrationBoundary.tsx#L85)
 
 `HydrationBoundary` adds a previously dehydrated state into the `queryClient` that would be returned by
 `useQueryClient()`. If the client already contains data, the new queries will be intelligently merged based on
@@ -41,15 +41,18 @@ function App() {
 
 Server-side prefetch handed off to the client via `dehydrate`:
 ```tsx
+import { noop } from '@tanstack/query-core'
 import { HydrationBoundary, dehydrate } from '@tanstack/preact-query'
 
 async function ServerComponent() {
   const queryClient = getQueryClient()
 
-  await queryClient.prefetchQuery({
-    queryKey: ['posts'],
-    queryFn: fetchPosts,
-  })
+  await queryClient
+    .query({
+      queryKey: ['posts'],
+      queryFn: fetchPosts,
+    })
+    .catch(noop)
 
   return (
     <HydrationBoundary state={dehydrate(queryClient)}>
diff --git a/docs/framework/preact/reference/functions/infiniteQueryOptions.md b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
index 259cc990206..0a8fbcb07a6 100644
--- a/docs/framework/preact/reference/functions/infiniteQueryOptions.md
+++ b/docs/framework/preact/reference/functions/infiniteQueryOptions.md
@@ -76,7 +76,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:193](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L193)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:194](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L194)
 
 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`.
@@ -131,6 +131,7 @@ export const projectsOptions = infiniteQueryOptions({
 
 A parameterized factory, reused across a hook and an imperative call with the same cache entry:
 ```tsx
+import { noop } from '@tanstack/query-core'
 import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
 
 export const commentsOptions = (postId: string) =>
@@ -152,7 +153,7 @@ function Comments({ postId }: { postId: string }) {
 }
 
 // Elsewhere, e.g. to warm the cache before rendering `<Comments>`:
-queryClient.prefetchInfiniteQuery(commentsOptions(postId))
+queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
 ```
 
 ## Call Signature
@@ -161,7 +162,7 @@ queryClient.prefetchInfiniteQuery(commentsOptions(postId))
 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:264](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L264)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:266](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L266)
 
 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,6 +217,7 @@ export const projectsOptions = infiniteQueryOptions({
 
 A parameterized factory, reused across a hook and an imperative call with the same cache entry:
 ```tsx
+import { noop } from '@tanstack/query-core'
 import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
 
 export const commentsOptions = (postId: string) =>
@@ -237,5 +239,5 @@ function Comments({ postId }: { postId: string }) {
 }
 
 // Elsewhere, e.g. to warm the cache before rendering `<Comments>`:
-queryClient.prefetchInfiniteQuery(commentsOptions(postId))
+queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
 ```
diff --git a/docs/framework/preact/reference/functions/queryOptions.md b/docs/framework/preact/reference/functions/queryOptions.md
index 99d29ec22ba..c8844b2ed1d 100644
--- a/docs/framework/preact/reference/functions/queryOptions.md
+++ b/docs/framework/preact/reference/functions/queryOptions.md
@@ -71,7 +71,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:167](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L167)
+Defined in: [preact-query/src/queryOptions.ts:169](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L169)
 
 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
@@ -120,6 +120,7 @@ export const postsOptions = queryOptions({
 
 A parameterized factory, reused across a hook and an imperative call with the same cache entry:
 ```tsx
+import { noop } from '@tanstack/query-core'
 import { queryOptions, useQuery } from '@tanstack/preact-query'
 
 export const postOptions = (id: string) =>
@@ -134,11 +135,12 @@ function Post({ id }: { id: string }) {
 }
 
 // Elsewhere, e.g. to warm the cache before rendering `<Post>`:
-queryClient.prefetchQuery(postOptions(id))
+queryClient.query(postOptions(id)).catch(noop)
 ```
 
 The same options object works with every API that accepts query options:
 ```tsx
+import { noop } from '@tanstack/query-core'
 import { queryOptions, useQuery, useSuspenseQuery } from '@tanstack/preact-query'
 
 const todosOptions = queryOptions({
@@ -148,7 +150,7 @@ const todosOptions = queryOptions({
 
 useQuery(todosOptions)
 useSuspenseQuery(todosOptions)
-queryClient.prefetchQuery(todosOptions)
+queryClient.query(todosOptions).catch(noop)
 queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefined
 ```
 
@@ -158,7 +160,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:231](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L231)
+Defined in: [preact-query/src/queryOptions.ts:235](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L235)
 
 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
@@ -207,6 +209,7 @@ export const postsOptions = queryOptions({
 
 A parameterized factory, reused across a hook and an imperative call with the same cache entry:
 ```tsx
+import { noop } from '@tanstack/query-core'
 import { queryOptions, useQuery } from '@tanstack/preact-query'
 
 export const postOptions = (id: string) =>
@@ -221,11 +224,12 @@ function Post({ id }: { id: string }) {
 }
 
 // Elsewhere, e.g. to warm the cache before rendering `<Post>`:
-queryClient.prefetchQuery(postOptions(id))
+queryClient.query(postOptions(id)).catch(noop)
 ```
 
 The same options object works with every API that accepts query options:
 ```tsx
+import { noop } from '@tanstack/query-core'
 import { queryOptions, useQuery, useSuspenseQuery } from '@tanstack/preact-query'
 
 const todosOptions = queryOptions({
@@ -235,6 +239,6 @@ const todosOptions = queryOptions({
 
 useQuery(todosOptions)
 useSuspenseQuery(todosOptions)
-queryClient.prefetchQuery(todosOptions)
+queryClient.query(todosOptions).catch(noop)
 queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefined
 ```
diff --git a/packages/preact-query/src/HydrationBoundary.tsx b/packages/preact-query/src/HydrationBoundary.tsx
index 98b253ed5a5..8dc2d4df828 100644
--- a/packages/preact-query/src/HydrationBoundary.tsx
+++ b/packages/preact-query/src/HydrationBoundary.tsx
@@ -61,15 +61,18 @@ export interface HydrationBoundaryProps {
  * @example
  * Server-side prefetch handed off to the client via `dehydrate`:
  * ```tsx
+ * import { noop } from '@tanstack/query-core'
  * import { HydrationBoundary, dehydrate } from '@tanstack/preact-query'
  *
  * async function ServerComponent() {
  *   const queryClient = getQueryClient()
  *
- *   await queryClient.prefetchQuery({
- *     queryKey: ['posts'],
- *     queryFn: fetchPosts,
- *   })
+ *   await queryClient
+ *     .query({
+ *       queryKey: ['posts'],
+ *       queryFn: fetchPosts,
+ *     })
+ *     .catch(noop)
  *
  *   return (
  *     <HydrationBoundary state={dehydrate(queryClient)}>
diff --git a/packages/preact-query/src/infiniteQueryOptions.ts b/packages/preact-query/src/infiniteQueryOptions.ts
index 9421eceea11..081e35e2ed4 100644
--- a/packages/preact-query/src/infiniteQueryOptions.ts
+++ b/packages/preact-query/src/infiniteQueryOptions.ts
@@ -164,6 +164,7 @@ export function infiniteQueryOptions<
  * @example
  * A parameterized factory, reused across a hook and an imperative call with the same cache entry:
  * ```tsx
+ * import { noop } from '@tanstack/query-core'
  * import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
  *
  * export const commentsOptions = (postId: string) =>
@@ -185,7 +186,7 @@ export function infiniteQueryOptions<
  * }
  *
  * // Elsewhere, e.g. to warm the cache before rendering `<Comments>`:
- * queryClient.prefetchInfiniteQuery(commentsOptions(postId))
+ * queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
  * ```
  *
  * @param options - The {@link UnusedSkipTokenInfiniteOptions} to use — everything you can pass to `useInfiniteQuery`.
@@ -235,6 +236,7 @@ export function infiniteQueryOptions<
  * @example
  * A parameterized factory, reused across a hook and an imperative call with the same cache entry:
  * ```tsx
+ * import { noop } from '@tanstack/query-core'
  * import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
  *
  * export const commentsOptions = (postId: string) =>
@@ -256,7 +258,7 @@ export function infiniteQueryOptions<
  * }
  *
  * // Elsewhere, e.g. to warm the cache before rendering `<Comments>`:
- * queryClient.prefetchInfiniteQuery(commentsOptions(postId))
+ * queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
  * ```
  *
  * @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 56e4b1f86e2..32ddec4f1d9 100644
--- a/packages/preact-query/src/queryOptions.ts
+++ b/packages/preact-query/src/queryOptions.ts
@@ -131,6 +131,7 @@ export function queryOptions<
  * @example
  * A parameterized factory, reused across a hook and an imperative call with the same cache entry:
  * ```tsx
+ * import { noop } from '@tanstack/query-core'
  * import { queryOptions, useQuery } from '@tanstack/preact-query'
  *
  * export const postOptions = (id: string) =>
@@ -145,12 +146,13 @@ export function queryOptions<
  * }
  *
  * // Elsewhere, e.g. to warm the cache before rendering `<Post>`:
- * queryClient.prefetchQuery(postOptions(id))
+ * queryClient.query(postOptions(id)).catch(noop)
  * ```
  *
  * @example
  * The same options object works with every API that accepts query options:
  * ```tsx
+ * import { noop } from '@tanstack/query-core'
  * import { queryOptions, useQuery, useSuspenseQuery } from '@tanstack/preact-query'
  *
  * const todosOptions = queryOptions({
@@ -160,7 +162,7 @@ export function queryOptions<
  *
  * useQuery(todosOptions)
  * useSuspenseQuery(todosOptions)
- * queryClient.prefetchQuery(todosOptions)
+ * queryClient.query(todosOptions).catch(noop)
  * queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefined
  * ```
  */
@@ -195,6 +197,7 @@ export function queryOptions<
  * @example
  * A parameterized factory, reused across a hook and an imperative call with the same cache entry:
  * ```tsx
+ * import { noop } from '@tanstack/query-core'
  * import { queryOptions, useQuery } from '@tanstack/preact-query'
  *
  * export const postOptions = (id: string) =>
@@ -209,12 +212,13 @@ export function queryOptions<
  * }
  *
  * // Elsewhere, e.g. to warm the cache before rendering `<Post>`:
- * queryClient.prefetchQuery(postOptions(id))
+ * queryClient.query(postOptions(id)).catch(noop)
  * ```
  *
  * @example
  * The same options object works with every API that accepts query options:
  * ```tsx
+ * import { noop } from '@tanstack/query-core'
  * import { queryOptions, useQuery, useSuspenseQuery } from '@tanstack/preact-query'
  *
  * const todosOptions = queryOptions({
@@ -224,7 +228,7 @@ export function queryOptions<
  *
  * useQuery(todosOptions)
  * useSuspenseQuery(todosOptions)
- * queryClient.prefetchQuery(todosOptions)
+ * queryClient.query(todosOptions).catch(noop)
  * queryClient.getQueryData(todosOptions.queryKey) // typed as Array<Todo> | undefined
  * ```
  */

From 3fd32a1889787a380ab724dfb026d37807f899f1 Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Tue, 25 Aug 2026 03:35:17 +0900
Subject: [PATCH 28/28] docs(preact-query): point 'usePrefetchQuery' JSDoc at
 'queryClient.query' to match its actual option type

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

diff --git a/docs/framework/preact/reference/functions/usePrefetchQuery.md b/docs/framework/preact/reference/functions/usePrefetchQuery.md
index 3c434dbf13a..c935d405992 100644
--- a/docs/framework/preact/reference/functions/usePrefetchQuery.md
+++ b/docs/framework/preact/reference/functions/usePrefetchQuery.md
@@ -11,7 +11,7 @@ Defined in: [preact-query/src/usePrefetchQuery.tsx:38](https://github.com/TanSta
 
 `usePrefetchQuery` does not return anything, it should be used just to fire a prefetch during render, before
 a suspense boundary that wraps a component that uses `useSuspenseQuery`. You can pass everything to
-`usePrefetchQuery` that you can pass to `queryClient.fetchQuery`, though `queryKey` is always required, and
+`usePrefetchQuery` that you can pass to `queryClient.query`, though `queryKey` is always required, and
 `queryFn` is required unless a default query function has been defined.
 
 ## Type Parameters
@@ -42,7 +42,7 @@ a suspense boundary that wraps a component that uses `useSuspenseQuery`. You can
 
 [`UsePrefetchQueryOptions`](../type-aliases/UsePrefetchQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryData`, `TQueryKey`\>
 
-The [UsePrefetchQueryOptions](../type-aliases/UsePrefetchQueryOptions.md) to use — everything you can pass to `queryClient.fetchQuery`.
+The [UsePrefetchQueryOptions](../type-aliases/UsePrefetchQueryOptions.md) to use — everything you can pass to `queryClient.query`.
 
 ### queryClient?
 
diff --git a/packages/preact-query/src/usePrefetchQuery.tsx b/packages/preact-query/src/usePrefetchQuery.tsx
index f079c378960..b5c260b77b4 100644
--- a/packages/preact-query/src/usePrefetchQuery.tsx
+++ b/packages/preact-query/src/usePrefetchQuery.tsx
@@ -7,10 +7,10 @@ import type { UsePrefetchQueryOptions } from './types'
 /**
  * `usePrefetchQuery` does not return anything, it should be used just to fire a prefetch during render, before
  * a suspense boundary that wraps a component that uses `useSuspenseQuery`. You can pass everything to
- * `usePrefetchQuery` that you can pass to `queryClient.fetchQuery`, though `queryKey` is always required, and
+ * `usePrefetchQuery` that you can pass to `queryClient.query`, though `queryKey` is always required, and
  * `queryFn` is required unless a default query function has been defined.
  *
- * @param options - The {@link UsePrefetchQueryOptions} to use — everything you can pass to `queryClient.fetchQuery`.
+ * @param options - The {@link UsePrefetchQueryOptions} to use — everything you can pass to `queryClient.query`.
  * @param queryClient - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will
  * be used.
  * @returns `void` — nothing is returned.