docs: Add placeholder data guide

Author: tannerlinsley

docs/src/manifests/manifest.json

@@ -115,6 +115,11 @@
           "path": "/guides/infinite-queries",
           "editUrl": "/guides/infinite-queries.md"
         },
+        {
+          "title": "Placeholder Query Data",
+          "path": "/guides/placeholder-query-data",
+          "editUrl": "/guides/placeholder-query-data.md"
+        },
         {
           "title": "Initial Query Data",
           "path": "/guides/initial-query-data",

docs/src/pages/guides/initial-query-data.md

@@ -3,9 +3,19 @@ id: initial-query-data
 title: Initial Query Data
 ---
 
-## Initial Data
+There are many ways to supply initial data for a query to the cache before you need it:
 
-There may be times when you already have the initial data for a query synchronously available in your app. If and when this is the case, you can use the `config.initialData` option to set the initial data for a query and skip the initial loading state!
+- Declaratively:
+  - Provide `initialData` to a query to prepopulate the its cache if empty
+- Imperatively:
+  - [Prefetch the data using `queryClient.prefetchQuery`](../prefetching)
+  - [Manually place the data into the cache using `queryClient.setQueryData`](../prefetching)
+
+## Using `initialData` to prepopulate a query
+
+There may be times when you already have the initial data for a query available in your app and can simply provide it directly to your query. If and when this is the case, you can use the `config.initialData` option to set the initial data for a query and skip the initial loading state!
+
+> IMPORTANT: `initialData` is persisted to the cache, so it is not recommended to provide placeholder, partial or incomplete data to this option and instead use `placeholderData`
 
 ```js
 function Todos() {
@@ -15,7 +25,7 @@ function Todos() {
 }
 ```
 
-## Using Initial Data with `staleTime`
+### Initial Data and `staleTime`
 
 `initialData` is treated exactly the same as normal data, which means that is follows the same rules and expectations of `staleTime`.
 
@@ -32,9 +42,9 @@ function Todos() {
 
 > If you would rather treat your data as **prefetched data**, we recommend that you use the `prefetchQuery` or `fetchQuery` APIs to populate the cache beforehand, thus letting you configure your `staleTime` independently from your initialData
 
-## Initial Data Function
+### Initial Data Function
 
-If the process for accessing a query's initial data is intensive or just not something you want to perform on every render, you can pass a function as the `initialData` value. This function will be executed only once when the query is initialized, saving you precious memory and CPU:
+If the process for accessing a query's initial data is intensive or just not something you want to perform on every render, you can pass a function as the `initialData` value. This function will be executed only once when the query is initialized, saving you precious memory and/or CPU:
 
 ```js
 function Todos() {
@@ -46,7 +56,7 @@ function Todos() {
 }
 ```
 
-## Initial Data from Cache
+### Initial Data from Cache
 
 In some circumstances, you may be able to provide the initial data for a query from the cached result of another. A good example of this would be searching the cached data from a todos list query for an individual todo item, then using that as the initial data for your individual todo query:
 

docs/src/pages/guides/placeholder-query-data.md

@@ -0,0 +1,58 @@
+---
+id: placeholder-query-data
+title: Placeholder Query Data
+---
+
+## What is placeholder data?
+
+Placeholder data allows a query to behave as if it already has data, similar to the `initialData`, but **the data is not persisted to the cache**. This comes in handy for situations where you have enough partial (or fake) data to render the query successfully while the actual data is fetched in the background.
+
+> Example: An individual blog post query could pull "preview" data from a parent list of blog posts that only include title and a small snippet of the post body. You would not want to persist this partial data to the query result of the individual query, but it is useful for showing the content layout as quickly as possible while the actual query finishes to fetch the entire object.
+
+There are a few ways to supply placeholder data for a query to the cache before you need it:
+
+- Declaratively:
+  - Provide `placeholderData` to a query to prepopulate the its cache if empty
+- Imperatively:
+  - [Prefetch or fetch the data using `queryClient` and the `placeholderData` option](../prefetching)
+
+## Placeholder Data as a Value
+
+```js
+function Todos() {
+  const result = useQuery('todos', () => fetch('/todos'), {
+    placeholderData: placeholderTodos,
+  })
+}
+```
+
+### Placeholder Data as a Function
+
+If the process for accessing a query's placeholder data is intensive or just not something you want to perform on every render, you can pass a function as the `placeholderData` value. This function will be executed only once when the query is placeholderized, saving you precious memory and/or CPU:
+
+```js
+function Todos() {
+  const result = useQuery('todos', () => fetch('/todos'), {
+    placeholderData: () => {
+      return generateFakeTodos()
+    },
+  })
+}
+```
+
+### Placeholder Data from Cache
+
+In some circumstances, you may be able to provide the placeholder data for a query from the cached result of another. A good example of this would be searching the cached data from a blog post list query for a preview version of the post, then using that as the placeholder data for your individual post query:
+
+```js
+function Todo({ blogPostId }) {
+  const result = useQuery(['blogPost', blogPostId], () => fetch('/blogPosts'), {
+    placeholderData: () => {
+      // Use the smaller/preview version of the blogPost from the 'blogPosts' query as the placeholder data for this blogPost query
+      return queryClient
+        .getQueryData('blogPosts')
+        ?.find(d => d.id === blogPostId)
+    },
+  })
+}
+```