Course contentsShow
← React
Lesson 1779 of 2,39642. Data Fetching LibrariesFree lesson

Initial Data and Placeholder Data

Providing initial or placeholder data to avoid loading states for cached or known data.

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 isLoading and status
  • 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.