Initial Data and Placeholder Data
You'll learn: How to provide immediate data to TanStack Query to skip loading states when you already know what should be displayed.
The Problem with Always Loading
By default, useQuery returns isLoading: true on first render while it fetches data. But sometimes you already have data to show—maybe from server-side rendering, from another query's cache, or from a previous page. Why show a spinner when you can show content immediately?
Initial Data: Pre-Populating the Cache
initialData lets you provide data upfront. TanStack Query treats it as if the fetch already completed:
const { data } = useQuery({
queryKey: ['user', userId],
queryFn: fetchUser,
initialData: {
id: userId,
name: 'Loading...',
email: ''
}
})
The component renders immediately with your initial data, then TanStack Query still fetches in the background and updates when the real data arrives.
Use case: You know the structure but want to show something while loading, or you're hydrating from SSR data.
Placeholder Data: Temporary, Non-Cached
placeholderData is similar but doesn't populate the cache. It's displayed only while loading, then replaced entirely:
const { data } = useQuery({
queryKey: ['posts', page],
queryFn: fetchPosts,
placeholderData: previousData // from a different query
})
Use case: Showing the previous page's data while fetching the next page, or displaying a generic skeleton object.
The Key Difference
- initialData: Treated as real cached data, affects
isLoadingandstatus - placeholderData: Temporary display only, query still shows as loading
Key Takeaway: Use initialData to seed the cache with known data, and placeholderData to show temporary content without affecting cache state—both eliminate jarring loading spinners when you have something to display.