Rendering paginated data is a very common UI pattern and in TanStack Query, it "just works" by including the page information in the query key:
const result = injectQuery(() => ({
queryKey: ['projects', page()],
queryFn: fetchProjects,
}))
const result = injectQuery(() => ({
queryKey: ['projects', page()],
queryFn: fetchProjects,
}))
However, if you run this simple example, you might notice something strange:
The UI jumps in and out of the success and pending states because each new page is treated like a brand new query.
This experience is not optimal and unfortunately is how many tools today insist on working. But not TanStack Query! As you may have guessed, TanStack Query comes with an awesome feature called placeholderData that allows us to get around this.
Consider the following example where we would ideally want to increment a pageIndex (or cursor) for a query. If we were to use injectQuery, it would still technically work fine, but the UI would jump in and out of the success and pending states as different queries are created and destroyed for each page or cursor. By setting placeholderData to (previousData) => previousData or keepPreviousData function exported from TanStack Query, we get a few new things:
@Component({
selector: 'pagination-example',
template: `
<div>
<p>
In this example, each page of data remains visible as the next page is
fetched. The buttons and capability to proceed to the next page are also
suppressed until the next page cursor is known. Each page is cached as a
normal query too, so when going to previous pages, you'll see them
instantaneously while they are also re-fetched invisibly in the
background.
</p>
@if (query.status() === 'pending') {
<div>Loading...</div>
} @else if (query.status() === 'error') {
<div>Error: {{ query.error().message }}</div>
} @else {
<!-- 'data' will either resolve to the latest page's data -->
<!-- or if fetching a new page, the last successful page's data -->
<div>
@for (project of query.data().projects; track project.id) {
<p>{{ project.name }}</p>
}
</div>
}
<div>Current Page: {{ page() + 1 }}</div>
<button (click)="previousPage()" [disabled]="page() === 0">
Previous Page
</button>
<button
(click)="nextPage()"
[disabled]="query.isPlaceholderData() || !query.data()?.hasMore"
>
Next Page
</button>
<!-- Since the last page's data potentially sticks around between page requests, -->
<!-- we can use 'isFetching' to show a background loading -->
<!-- indicator since our status === 'pending' state won't be triggered -->
@if (query.isFetching()) {
<span> Loading...</span>
}
</div>
`,
})
export class PaginationExampleComponent {
page = signal(0)
#queryClient = injectQueryClient()
query = injectQuery(() => ({
queryKey: ['projects', this.page()],
queryFn: () => lastValueFrom(fetchProjects(this.page())),
placeholderData: keepPreviousData,
staleTime: 5000,
}))
constructor() {
effect(() => {
// Prefetch the next page!
if (!this.query.isPlaceholderData() && this.query.data()?.hasMore) {
this.#queryClient.prefetchQuery({
queryKey: ['projects', this.page() + 1],
queryFn: () => lastValueFrom(fetchProjects(this.page() + 1)),
})
}
})
}
previousPage() {
this.page.update((old) => Math.max(old - 1, 0))
}
nextPage() {
this.page.update((old) => (this.query.data()?.hasMore ? old + 1 : old))
}
}
@Component({
selector: 'pagination-example',
template: `
<div>
<p>
In this example, each page of data remains visible as the next page is
fetched. The buttons and capability to proceed to the next page are also
suppressed until the next page cursor is known. Each page is cached as a
normal query too, so when going to previous pages, you'll see them
instantaneously while they are also re-fetched invisibly in the
background.
</p>
@if (query.status() === 'pending') {
<div>Loading...</div>
} @else if (query.status() === 'error') {
<div>Error: {{ query.error().message }}</div>
} @else {
<!-- 'data' will either resolve to the latest page's data -->
<!-- or if fetching a new page, the last successful page's data -->
<div>
@for (project of query.data().projects; track project.id) {
<p>{{ project.name }}</p>
}
</div>
}
<div>Current Page: {{ page() + 1 }}</div>
<button (click)="previousPage()" [disabled]="page() === 0">
Previous Page
</button>
<button
(click)="nextPage()"
[disabled]="query.isPlaceholderData() || !query.data()?.hasMore"
>
Next Page
</button>
<!-- Since the last page's data potentially sticks around between page requests, -->
<!-- we can use 'isFetching' to show a background loading -->
<!-- indicator since our status === 'pending' state won't be triggered -->
@if (query.isFetching()) {
<span> Loading...</span>
}
</div>
`,
})
export class PaginationExampleComponent {
page = signal(0)
#queryClient = injectQueryClient()
query = injectQuery(() => ({
queryKey: ['projects', this.page()],
queryFn: () => lastValueFrom(fetchProjects(this.page())),
placeholderData: keepPreviousData,
staleTime: 5000,
}))
constructor() {
effect(() => {
// Prefetch the next page!
if (!this.query.isPlaceholderData() && this.query.data()?.hasMore) {
this.#queryClient.prefetchQuery({
queryKey: ['projects', this.page() + 1],
queryFn: () => lastValueFrom(fetchProjects(this.page() + 1)),
})
}
})
}
previousPage() {
this.page.update((old) => Math.max(old - 1, 0))
}
nextPage() {
this.page.update((old) => (this.query.data()?.hasMore ? old + 1 : old))
}
}
While not as common, the placeholderData option also works flawlessly with the injectInfiniteQuery function, so you can seamlessly allow your users to continue to see cached data while infinite query keys change over time.