From 34a1eecfa5bd890ca877fd925b7fe36cea7e7809 Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Tue, 22 Sep 2026 17:26:19 +0900
Subject: [PATCH] docs({react,preact,solid,vue}-query/useQuery): add
 'initialDataUpdatedAt' to the seeding example

---
 docs/framework/preact/reference/functions/useQuery.md  |  8 ++++++--
 docs/framework/react/reference/functions/useQuery.md   |  8 ++++++--
 docs/framework/solid/reference/functions/useQuery.md   | 10 +++++++---
 .../framework/solid/reference/variables/createQuery.md |  6 +++++-
 docs/framework/vue/reference/functions/useQuery.md     | 10 +++++++---
 packages/preact-query/src/useQuery.ts                  |  6 +++++-
 packages/react-query/src/useQuery.ts                   |  6 +++++-
 packages/solid-query/src/useQuery.ts                   |  6 +++++-
 packages/vue-query/src/useQuery.ts                     |  6 +++++-
 9 files changed, 51 insertions(+), 15 deletions(-)

diff --git a/docs/framework/preact/reference/functions/useQuery.md b/docs/framework/preact/reference/functions/useQuery.md
index a0b65cad2fe..88b406adfc6 100644
--- a/docs/framework/preact/reference/functions/useQuery.md
+++ b/docs/framework/preact/reference/functions/useQuery.md
@@ -190,7 +190,7 @@ function Posts() {
 function useQuery<TQueryFnData, TError, TData, TQueryKey>(options: UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>, queryClient?: QueryClient): UseQueryResult<TData, TError>;
 ```
 
-Defined in: [packages/preact-query/src/useQuery.ts:281](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L281)
+Defined in: [packages/preact-query/src/useQuery.ts:285](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useQuery.ts#L285)
 
 ### Type Parameters
 
@@ -324,7 +324,9 @@ function Post({ postId }: { postId: number | undefined }) {
 }
 ```
 
-Seeding a detail query from an already-cached list, to skip the loading state:
+Seeding a detail query from an already-cached list, to skip the loading state. `initialDataUpdatedAt` carries
+over the list's own fetch time, so that if you set a `staleTime`, it's measured from when the list was
+fetched rather than from now:
 ```tsx
 import { useQuery, useQueryClient } from '@tanstack/preact-query'
 
@@ -338,6 +340,8 @@ function Post({ postId }: { postId: number }) {
       queryClient
         .getQueryData<Array<Post>>(['posts'])
         ?.find((post) => post.id === postId),
+    initialDataUpdatedAt: () =>
+      queryClient.getQueryState(['posts'])?.dataUpdatedAt,
   })
 
   if (isError) return <span>Error: {error.message}</span>
diff --git a/docs/framework/react/reference/functions/useQuery.md b/docs/framework/react/reference/functions/useQuery.md
index 5badc176158..c3c7837595b 100644
--- a/docs/framework/react/reference/functions/useQuery.md
+++ b/docs/framework/react/reference/functions/useQuery.md
@@ -192,7 +192,7 @@ function Posts() {
 function useQuery<TQueryFnData, TError, TData, TQueryKey>(options: UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>, queryClient?: QueryClient): UseQueryResult<TData, TError>;
 ```
 
-Defined in: [packages/react-query/src/useQuery.ts:281](https://github.com/TanStack/query/blob/main/packages/react-query/src/useQuery.ts#L281)
+Defined in: [packages/react-query/src/useQuery.ts:285](https://github.com/TanStack/query/blob/main/packages/react-query/src/useQuery.ts#L285)
 
 ### Type Parameters
 
@@ -326,7 +326,9 @@ function Post({ postId }: { postId: number | undefined }) {
 }
 ```
 
-Seeding a detail query from an already-cached list, to skip the loading state:
+Seeding a detail query from an already-cached list, to skip the loading state. `initialDataUpdatedAt` carries
+over the list's own fetch time, so that if you set a `staleTime`, it's measured from when the list was
+fetched rather than from now:
 ```tsx
 import { useQuery, useQueryClient } from '@tanstack/react-query'
 
@@ -340,6 +342,8 @@ function Post({ postId }: { postId: number }) {
       queryClient
         .getQueryData<Array<Post>>(['posts'])
         ?.find((post) => post.id === postId),
+    initialDataUpdatedAt: () =>
+      queryClient.getQueryState(['posts'])?.dataUpdatedAt,
   })
 
   if (isError) return <span>Error: {error.message}</span>
diff --git a/docs/framework/solid/reference/functions/useQuery.md b/docs/framework/solid/reference/functions/useQuery.md
index e102f8263d1..5531d898947 100644
--- a/docs/framework/solid/reference/functions/useQuery.md
+++ b/docs/framework/solid/reference/functions/useQuery.md
@@ -11,7 +11,7 @@ redirect_from:
 function useQuery<TQueryFnData, TError, TData, TQueryKey>(options: UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>, queryClient?: () => QueryClient): UseQueryResult<TData, TError>;
 ```
 
-Defined in: [packages/solid-query/src/useQuery.ts:181](https://github.com/TanStack/query/blob/main/packages/solid-query/src/useQuery.ts#L181)
+Defined in: [packages/solid-query/src/useQuery.ts:185](https://github.com/TanStack/query/blob/main/packages/solid-query/src/useQuery.ts#L185)
 
 Subscribes to a query: a declarative dependency on an asynchronous source of data that is tied to a unique key.
 The query runs when the options call for it — `enabled: false` skips the initial fetch.
@@ -159,7 +159,9 @@ function Post(props: { postId: number | undefined }) {
 }
 ```
 
-Seeding a detail query from an already-cached list, to skip the loading state:
+Seeding a detail query from an already-cached list, to skip the loading state. `initialDataUpdatedAt` carries
+over the list's own fetch time, so that if you set a `staleTime`, it's measured from when the list was
+fetched rather than from now:
 ```tsx
 import { useQuery, useQueryClient } from '@tanstack/solid-query'
 
@@ -173,6 +175,8 @@ function Post(props: { postId: number }) {
       queryClient
         .getQueryData<Array<Post>>(['posts'])
         ?.find((post) => post.id === props.postId),
+    initialDataUpdatedAt: () =>
+      queryClient.getQueryState(['posts'])?.dataUpdatedAt,
   }))
 
   return postQuery.isError ? <span>Error: {postQuery.error.message}</span> : <h1>{postQuery.data?.title}</h1>
@@ -215,7 +219,7 @@ function Posts() {
 function useQuery<TQueryFnData, TError, TData, TQueryKey>(options: DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>, queryClient?: () => QueryClient): DefinedUseQueryResult<TData, TError>;
 ```
 
-Defined in: [packages/solid-query/src/useQuery.ts:232](https://github.com/TanStack/query/blob/main/packages/solid-query/src/useQuery.ts#L232)
+Defined in: [packages/solid-query/src/useQuery.ts:236](https://github.com/TanStack/query/blob/main/packages/solid-query/src/useQuery.ts#L236)
 
 Subscribes to a query: a declarative dependency on an asynchronous source of data that is tied to a unique key.
 The query runs when the options call for it — `enabled: false` skips the initial fetch.
diff --git a/docs/framework/solid/reference/variables/createQuery.md b/docs/framework/solid/reference/variables/createQuery.md
index ab8c83ce07a..550b642b72c 100644
--- a/docs/framework/solid/reference/variables/createQuery.md
+++ b/docs/framework/solid/reference/variables/createQuery.md
@@ -164,7 +164,9 @@ function Post(props: { postId: number | undefined }) {
 }
 ```
 
-Seeding a detail query from an already-cached list, to skip the loading state:
+Seeding a detail query from an already-cached list, to skip the loading state. `initialDataUpdatedAt` carries
+over the list's own fetch time, so that if you set a `staleTime`, it's measured from when the list was
+fetched rather than from now:
 ```tsx
 import { useQuery, useQueryClient } from '@tanstack/solid-query'
 
@@ -178,6 +180,8 @@ function Post(props: { postId: number }) {
       queryClient
         .getQueryData<Array<Post>>(['posts'])
         ?.find((post) => post.id === props.postId),
+    initialDataUpdatedAt: () =>
+      queryClient.getQueryState(['posts'])?.dataUpdatedAt,
   }))
 
   return postQuery.isError ? <span>Error: {postQuery.error.message}</span> : <h1>{postQuery.data?.title}</h1>
diff --git a/docs/framework/vue/reference/functions/useQuery.md b/docs/framework/vue/reference/functions/useQuery.md
index 471bfacd9a7..4d0bf219f7e 100644
--- a/docs/framework/vue/reference/functions/useQuery.md
+++ b/docs/framework/vue/reference/functions/useQuery.md
@@ -88,7 +88,7 @@ const { data, isError, error } = useQuery({
 function useQuery<TQueryFnData, TError, TData, TQueryKey>(options: UndefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>, queryClient?: QueryClient): UseQueryReturnType<TData, TError>;
 ```
 
-Defined in: [packages/vue-query/src/useQuery.ts:206](https://github.com/TanStack/query/blob/main/packages/vue-query/src/useQuery.ts#L206)
+Defined in: [packages/vue-query/src/useQuery.ts:210](https://github.com/TanStack/query/blob/main/packages/vue-query/src/useQuery.ts#L210)
 
 `enabled` tracks reactive dependencies automatically as a `ref`, a plain value, or a reactive getter
 (`() => ...`). `queryKey` reacts through a `ref` or a reactive getter for the array itself, or `ref`s and
@@ -201,7 +201,9 @@ const { data, isLoading, isError, error } = useQuery({
 </template>
 ```
 
-Seeding a detail query from an already-cached list, to skip the loading state:
+Seeding a detail query from an already-cached list, to skip the loading state. `initialDataUpdatedAt` carries
+over the list's own fetch time, so that if you set a `staleTime`, it's measured from when the list was
+fetched rather than from now:
 ```vue
 <script setup lang="ts">
 import { useQuery, useQueryClient } from '@tanstack/vue-query'
@@ -216,6 +218,8 @@ const { data, isError, error } = useQuery({
     queryClient
       .getQueryData<Array<Post>>(['posts'])
       ?.find((post) => post.id === props.postId),
+  initialDataUpdatedAt: () =>
+    queryClient.getQueryState(['posts'])?.dataUpdatedAt,
 })
 </script>
 
@@ -257,7 +261,7 @@ const { data, isPlaceholderData, isError, error } = useQuery({
 function useQuery<TQueryFnData, TError, TData, TQueryKey>(options: MaybeRefOrGetter<UseQueryOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey>>, queryClient?: QueryClient): UseQueryReturnType<TData, TError>;
 ```
 
-Defined in: [packages/vue-query/src/useQuery.ts:282](https://github.com/TanStack/query/blob/main/packages/vue-query/src/useQuery.ts#L282)
+Defined in: [packages/vue-query/src/useQuery.ts:286](https://github.com/TanStack/query/blob/main/packages/vue-query/src/useQuery.ts#L286)
 
 Fallback overload for options whose `initialData` presence isn't statically known — for example, a
 `ref`/reactive object built up conditionally, rather than a plain object literal. Prefer one of the other
diff --git a/packages/preact-query/src/useQuery.ts b/packages/preact-query/src/useQuery.ts
index b579f13c5e5..46948d65724 100644
--- a/packages/preact-query/src/useQuery.ts
+++ b/packages/preact-query/src/useQuery.ts
@@ -223,7 +223,9 @@ export function useQuery<
  * ```
  *
  * @example
- * Seeding a detail query from an already-cached list, to skip the loading state:
+ * Seeding a detail query from an already-cached list, to skip the loading state. `initialDataUpdatedAt` carries
+ * over the list's own fetch time, so that if you set a `staleTime`, it's measured from when the list was
+ * fetched rather than from now:
  * ```tsx
  * import { useQuery, useQueryClient } from '@tanstack/preact-query'
  *
@@ -237,6 +239,8 @@ export function useQuery<
  *       queryClient
  *         .getQueryData<Array<Post>>(['posts'])
  *         ?.find((post) => post.id === postId),
+ *     initialDataUpdatedAt: () =>
+ *       queryClient.getQueryState(['posts'])?.dataUpdatedAt,
  *   })
  *
  *   if (isError) return <span>Error: {error.message}</span>
diff --git a/packages/react-query/src/useQuery.ts b/packages/react-query/src/useQuery.ts
index b67acc8604b..c6d552272f7 100644
--- a/packages/react-query/src/useQuery.ts
+++ b/packages/react-query/src/useQuery.ts
@@ -223,7 +223,9 @@ export function useQuery<
  * ```
  *
  * @example
- * Seeding a detail query from an already-cached list, to skip the loading state:
+ * Seeding a detail query from an already-cached list, to skip the loading state. `initialDataUpdatedAt` carries
+ * over the list's own fetch time, so that if you set a `staleTime`, it's measured from when the list was
+ * fetched rather than from now:
  * ```tsx
  * import { useQuery, useQueryClient } from '@tanstack/react-query'
  *
@@ -237,6 +239,8 @@ export function useQuery<
  *       queryClient
  *         .getQueryData<Array<Post>>(['posts'])
  *         ?.find((post) => post.id === postId),
+ *     initialDataUpdatedAt: () =>
+ *       queryClient.getQueryState(['posts'])?.dataUpdatedAt,
  *   })
  *
  *   if (isError) return <span>Error: {error.message}</span>
diff --git a/packages/solid-query/src/useQuery.ts b/packages/solid-query/src/useQuery.ts
index edfdb6a07e3..a6e73fb4962 100644
--- a/packages/solid-query/src/useQuery.ts
+++ b/packages/solid-query/src/useQuery.ts
@@ -127,7 +127,9 @@ import type {
  * ```
  *
  * @example
- * Seeding a detail query from an already-cached list, to skip the loading state:
+ * Seeding a detail query from an already-cached list, to skip the loading state. `initialDataUpdatedAt` carries
+ * over the list's own fetch time, so that if you set a `staleTime`, it's measured from when the list was
+ * fetched rather than from now:
  * ```tsx
  * import { useQuery, useQueryClient } from '@tanstack/solid-query'
  *
@@ -141,6 +143,8 @@ import type {
  *       queryClient
  *         .getQueryData<Array<Post>>(['posts'])
  *         ?.find((post) => post.id === props.postId),
+ *     initialDataUpdatedAt: () =>
+ *       queryClient.getQueryState(['posts'])?.dataUpdatedAt,
  *   }))
  *
  *   return postQuery.isError ? <span>Error: {postQuery.error.message}</span> : <h1>{postQuery.data?.title}</h1>
diff --git a/packages/vue-query/src/useQuery.ts b/packages/vue-query/src/useQuery.ts
index 42f7f45d860..bed2bb07fa9 100644
--- a/packages/vue-query/src/useQuery.ts
+++ b/packages/vue-query/src/useQuery.ts
@@ -152,7 +152,9 @@ export function useQuery<
  * ```
  *
  * @example
- * Seeding a detail query from an already-cached list, to skip the loading state:
+ * Seeding a detail query from an already-cached list, to skip the loading state. `initialDataUpdatedAt` carries
+ * over the list's own fetch time, so that if you set a `staleTime`, it's measured from when the list was
+ * fetched rather than from now:
  * ```vue
  * <script setup lang="ts">
  * import { useQuery, useQueryClient } from '@tanstack/vue-query'
@@ -167,6 +169,8 @@ export function useQuery<
  *     queryClient
  *       .getQueryData<Array<Post>>(['posts'])
  *       ?.find((post) => post.id === props.postId),
+ *   initialDataUpdatedAt: () =>
+ *     queryClient.getQueryState(['posts'])?.dataUpdatedAt,
  * })
  * </script>
  *