Cursor-based pagination (startAfter, endBefore) in Firebase - Commands & Configuration

Introduction

When you have many items in a database and want to show them page by page, cursor-based pagination helps you get the next or previous set of items easily without skipping or repeating. It uses a specific item as a starting point to continue fetching data.

When you want to load chat messages in small chunks as the user scrolls.

When displaying a list of products in pages without loading all at once.

When you want to fetch the next set of user comments after the last one shown.

When you want to go back to previous pages smoothly without reloading everything.

When you want to avoid performance issues caused by offset-based pagination on large datasets.

Commands

Fetch the document of the last user shown to use as a cursor for the next page.

Terminal

firebase firestore:documents:get users/user123

Expected Output

{

  "name": "users/user123",

  "fields": {

    "username": {"stringValue": "alice"},

    "age": {"integerValue": "30"}

  }

}

Get the next 5 users ordered by username, starting after the user with username 'alice'. This fetches the next page of results.

Terminal

firebase firestore:query 'users' --order-by 'username' --start-after 'alice' --limit 5

Expected Output

[

  {"username": "bob", "age": 25},

  {"username": "carol", "age": 28},

  {"username": "dave", "age": 22},

  {"username": "eve", "age": 35},

  {"username": "frank", "age": 27}

]

→

--start-after - Starts fetching documents after the specified cursor value.

→

--limit - Limits the number of documents returned.

→

--order-by - Orders the documents by a field.

Get the previous 5 users ordered by username, ending before the user with username 'bob'. This fetches the previous page of results.

Terminal

firebase firestore:query 'users' --order-by 'username' --end-before 'bob' --limit 5

Expected Output

[

  {"username": "aaron", "age": 29},

  {"username": "adam", "age": 31},

  {"username": "amelia", "age": 26},

  {"username": "andrew", "age": 24},

  {"username": "alice", "age": 30}

]

→

--end-before - Ends fetching documents before the specified cursor value.

→

--limit - Limits the number of documents returned.

→

--order-by - Orders the documents by a field.

Key Concept

If you remember nothing else from this pattern, remember: cursor-based pagination uses a specific item as a marker to fetch the next or previous set of data smoothly and efficiently.

Common Mistakes

Using offset-based pagination instead of cursor-based pagination.

Offset pagination can skip or repeat items when data changes and is slower on large datasets.

Use startAfter or endBefore with a document snapshot or field value as a cursor.

Not ordering the query by the same field used in the cursor.

The cursor depends on the order; mismatched order causes errors or wrong results.

Always use the same orderBy field as the cursor value.

Using a cursor value that does not exist or is not from the previous query.

The query will fail or return empty results because the cursor is invalid.

Use the last document from the previous page as the cursor.

Summary

Use startAfter with a document or field value to get the next page of results.

Use endBefore with a document or field value to get the previous page of results.

Always order your query by the same field used for the cursor to ensure correct pagination.