Open History to see the last commit
1---
2id: placeholder-query-data
3title: Placeholder Query Data
4---
5β
6## What is placeholder data?
7β
8Placeholder data allows a query to behave as if it already has data, similar to the `initialData` option, 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.
9β
10> 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.
11β
12There are a few ways to supply placeholder data for a query to the cache before you need it:
13β
14- Declaratively:
15 - Provide `placeholderData` to a query to prepopulate its cache if empty
16- Imperatively:
17 - [Prefetch or fetch the data using `queryClient` and the `placeholderData` option](./prefetching.md)
18β
19When we use `placeholderData`, our Query will not be in a `pending` state - it will start out as being in `success` state, because we have `data` to display - even if that data is just "placeholder" data. To distinguish it from "real" data, we will also have the `isPlaceholderData` flag set to `true` on the Query result.
20β
21## Placeholder Data as a Value
22β
23[//]: # 'ExampleValue'
24β
25```tsx
26function Todos() {
27 const result = useQuery({
28 queryKey: ['todos'],
29 queryFn: () => fetch('/todos'),
30 placeholderData: placeholderTodos,
31 })
32}
33```
34β
35[//]: # 'ExampleValue'
36[//]: # 'Memoization'
37β
38### Placeholder Data Memoization
39β
40If the process for accessing a query's placeholder data is intensive or just not something you want to perform on every render, you can memoize the value:
41β
42```tsx
43function Todos() {
44 const placeholderData = useMemo(() => generateFakeTodos(), [])
45 const result = useQuery({
46 queryKey: ['todos'],
47 queryFn: () => fetch('/todos'),
48 placeholderData,
49 })
50}
51```
52β
53[//]: # 'Memoization'
54β
55## Placeholder Data as a Function
56β
57`placeholderData` can also be a function, where you can get access to the data and Query meta information of a "previous" successful Query. This is useful for situations where you want to use the data from one query as the placeholder data for another query. When the QueryKey changes, e.g. from `['todos', 1]` to `['todos', 2]`, we can keep displaying "old" data instead of having to show a loading spinner while data is _transitioning_ from one Query to the next. For more information, see [Paginated Queries](./paginated-queries.md).
58β
59[//]: # 'ExampleFunction'
60β
61```tsx
62const result = useQuery({
63 queryKey: ['todos', id],
64 queryFn: () => fetch(`/todos/${id}`),
65 placeholderData: (previousData, previousQuery) => previousData,
66})
67```
68β
69[//]: # 'ExampleFunction'
70β
71### Placeholder Data from Cache
72β
73In 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:
74β
75[//]: # 'ExampleCache'
76β
77```tsx
78function BlogPost({ blogPostId }) {
79 const queryClient = useQueryClient()
80 const result = useQuery({
81 queryKey: ['blogPost', blogPostId],
82 queryFn: () => fetch(`/blogPosts/${blogPostId}`),
83 placeholderData: () => {
84 // Use the smaller/preview version of the blogPost from the 'blogPosts'
85 // query as the placeholder data for this blogPost query
86 return queryClient
87 .getQueryData(['blogPosts'])
88 ?.find((d) => d.id === blogPostId)
89 },
90 })
91}
92```
93β
94[//]: # 'ExampleCache'
95[//]: # 'Materials'
96β
97## Further reading
98β
99For a comparison between `Placeholder Data` and `Initial Data`, see the [article by TkDodo](https://tkdodo.eu/blog/placeholder-and-initial-data-in-react-query).
100β
101[//]: # 'Materials'