Progressive rendering
A list has enough summary fields to render rows before detail requests finish.
TanStack · Pipe
placeholderData
placeholderData lets a query render with temporary data while the real request runs. Unlike initialData, the temporary value is not persisted in the cache and is marked with isPlaceholderData.
How it works
placeholderData supplies observer-level temporary data so a query can render successfully while its request runs. The temporary value is not written to the cache; the result exposes isPlaceholderData so the UI can distinguish it from fetched data.
Syntax
useQuery({ queryKey, queryFn, placeholderData })Parameters
| Name | Type | Description |
|---|---|---|
placeholderData | TData | ((previousData: TData | undefined, previousQuery: Query) => TData) | A temporary value or function producing temporary query data; it is used while the real data is fetched and is not persisted in the cache. |
Returns
A query result containing the temporary data, with isPlaceholderData set to true while that data is displayed; the fetched result replaces it when available.
Key points
- Temporary data affects the displayed query result but is not stored as cached query state.
- It is useful when partial or synthetic values can support an immediate, usable render.
- Configure placeholderData declaratively on a query when an immediate provisional result is needed.
- The query avoids the pending state because placeholder content is available from the start.
- The initial result reports success even though the displayed value is only provisional.
- A function form supports dynamic placeholders rather than one fixed value.
- The function can inspect the previous successful query's data and metadata, supporting smooth transitions between query keys.
Common mistakes
- Do not treat placeholderData as cached data: it only affects the current query result and does not populate the query cache.
- Use isPlaceholderData to avoid treating the temporary value as the completed server response.
Example: Render with placeholder data
import { useQuery } from '@tanstack/react-query'
export function TodoTitle({ id }: { id: number }) {
const query = useQuery({
queryKey: ['todo', id],
queryFn: () => fetch(`/api/todos/${id}`).then((r) => r.json()),
placeholderData: { id, title: 'Loading…' },
})
return <h2>{query.data.title}</h2>
}The component renders immediately with temporary todo data while the real response is fetched in the background.
When to use it
Lagged pagination
A page-number query changes keys and should keep the previous page visible during refetching.
Stable UI shape
A skeleton or lightweight fake object can provide the shape required by the view immediately.
Interview questions
QWhat does placeholderData do, and how does it differ from initialData?
placeholderData makes a query behave as though it already has data while the actual request proceeds. Unlike initialData, the supplied value is not persisted to the cache.
Follow-up: How can the UI identify the temporary state? Check the result's isPlaceholderData flag, which is true while placeholder data is being supplied.
QWhat query status should you expect when placeholderData is present?
A query using placeholderData starts in the success state rather than pending because it has displayable data. The real fetch still runs in the background and replaces the temporary result when it completes.
Follow-up: Why is this useful for loading states? It allows partial or fake data to render without showing an empty pending view.
QWhat can a placeholderData function access?
placeholderData may be a function. That function can receive data and query metadata from a previous successful query, enabling the prior result to remain visible during a key change.
Follow-up: What common pagination pattern follows from this? Return previousData from the placeholder function so old results remain visible until the new page arrives.
Related
initialDataisPlaceholderDatakeepPreviousDataqueryClientuseQuery