How to Paginate in Firestore: Simple Guide with Examples

To paginate in Firestore, use limit() to set the number of documents per page and startAfter() with the last document from the previous page to fetch the next set. This lets you load data in chunks without skipping or repeating documents.

Syntax

Firestore pagination uses query cursors to control which documents to fetch next. The main methods are:

• limit(n): Limits the number of documents returned to n.
• startAfter(doc): Starts the query after the specified document doc.
• orderBy(field): Orders documents by a field, required for cursor methods.

Combine these to fetch pages of data sequentially.

javascript

const firstPage = firestore.collection('items')
  .orderBy('name')
  .limit(10);

const nextPage = firestore.collection('items')
  .orderBy('name')
  .startAfter(lastDoc)
  .limit(10);

Example

This example fetches the first 3 documents ordered by name, then fetches the next 3 documents starting after the last one from the first page.

javascript

import { getFirestore, collection, query, orderBy, limit, startAfter, getDocs } from 'firebase/firestore';

const db = getFirestore();

async function paginate() {
  // First page
  const firstQuery = query(collection(db, 'items'), orderBy('name'), limit(3));
  const firstSnapshot = await getDocs(firstQuery);
  firstSnapshot.forEach(doc => console.log('First page doc:', doc.id, doc.data()));

  // Get last document from first page
  const lastDoc = firstSnapshot.docs[firstSnapshot.docs.length - 1];

  // Next page
  const nextQuery = query(collection(db, 'items'), orderBy('name'), startAfter(lastDoc), limit(3));
  const nextSnapshot = await getDocs(nextQuery);
  nextSnapshot.forEach(doc => console.log('Next page doc:', doc.id, doc.data()));
}

paginate();

Output

First page doc: doc1 {name: 'Apple'}
First page doc: doc2 {name: 'Banana'}
First page doc: doc3 {name: 'Cherry'}
Next page doc: doc4 {name: 'Date'}
Next page doc: doc5 {name: 'Fig'}
Next page doc: doc6 {name: 'Grape'}

Common Pitfalls

Common mistakes when paginating Firestore data include:

• Not using orderBy() before startAfter(), which causes errors.
• Using document data instead of the document snapshot as the cursor in startAfter().
• Not handling the case when there are no more documents to fetch.

Always keep the last document snapshot from the previous page to use as the cursor for the next page.

javascript

/* Wrong: Using data instead of document snapshot */
const nextQueryWrong = query(collection(db, 'items'), orderBy('name'), startAfter(lastDoc.data().name), limit(3));

/* Right: Use the document snapshot directly */
const nextQueryRight = query(collection(db, 'items'), orderBy('name'), startAfter(lastDoc), limit(3));

Quick Reference

Method	Purpose
limit(n)	Limits the number of documents returned to n
orderBy(field)	Orders documents by a field, required for pagination
startAfter(doc)	Starts query after the specified document snapshot
startAt(doc)	Starts query at the specified document snapshot (inclusive)

Key Takeaways

Use orderBy() with limit() to define pages in Firestore queries.

Use startAfter() with the last document snapshot to fetch the next page.

Always keep the last document snapshot from the previous page as the cursor.

Do not use document data as a cursor; use the document snapshot instead.

Handle the case when no more documents are available to avoid errors.