[Data Grid] Add recipe for cursor pagination with data source #19700

siriwatknp · 2025-09-25T02:32:46Z

Preview: https://deploy-preview-19700--material-ui-x.netlify.app/x/react-data-grid/server-side-data/recipes/#cursor-based-pagination

Summary

This PR enhances the Data Grid documentation by adding comprehensive examples and explanations for cursor-based pagination, addressing a common server-side data pattern where traditional offset pagination isn't suitable.

Changes

Documentation Updates

docs/data/data-grid/server-side-data/recipes.md
- Added new "Cursor-based pagination" section explaining the concept and requirements
- Documented two implementation approaches: blocking and non-blocking
- Included clear explanations of when to use each approach

New Demo Components

ServerSideCursorBlocking.js - Blocking approach
- Controls paginationModel state to ensure cursor availability
- Simpler implementation, suitable for most use cases
- Prevents navigation until previous response arrives
ServerSideCursorNonBlocking.js - Non-blocking approach
- Uses custom cache with pushKey() and getLast() methods
- Allows immediate pagination with request queuing
- More complex but provides better UX for fast navigation

Technical Implementation

Blocking Approach

Updates pagination model only when cursor is available
Uses mapPageToNextCursor ref to track cursors
Conditional pagination model updates based on cursor availability

Non-blocking Approach

Custom Cache class implementation
Request order tracking before responses arrive
Asynchronous cursor resolution for seamless navigation

Benefits

Clear guidance: Developers now have concrete examples for implementing cursor pagination
Multiple strategies: Covers different UX requirements and complexity levels
Production-ready: Examples include proper state management and edge case handling
Educational: Demonstrates advanced Data Grid features like paginationMeta and custom caching

I have followed (at least) the PR section of the contributing guide.

mui-bot · 2025-09-25T02:34:36Z

Deploy preview: https://deploy-preview-19700--material-ui-x.netlify.app/

Updated pages:

docs/data/data-grid/server-side-data/recipes.md

Bundle size report

Bundle	Parsed size	Gzip size
@mui/x-data-grid	0B^(0.00%)	0B^(0.00%)
@mui/x-data-grid-pro	0B^(0.00%)	0B^(0.00%)
@mui/x-data-grid-premium	0B^(0.00%)	0B^(0.00%)
@mui/x-charts	0B^(0.00%)	0B^(0.00%)
@mui/x-charts-pro	0B^(0.00%)	0B^(0.00%)
@mui/x-charts-premium	0B^(0.00%)	0B^(0.00%)
@mui/x-date-pickers	0B^(0.00%)	0B^(0.00%)
@mui/x-date-pickers-pro	0B^(0.00%)	0B^(0.00%)
@mui/x-tree-view	0B^(0.00%)	0B^(0.00%)
@mui/x-tree-view-pro	0B^(0.00%)	0B^(0.00%)

Details of bundle changes

Generated by 🚫 dangerJS against 64d79ee

packages/x-data-grid/src/internals/utils/cache.ts

…o docs/cursor-pagination

docs/data/data-grid/server-side-data/ServerSideCursorBlocking.tsx

docs/data/data-grid/server-side-data/ServerSideCursorNonBlocking.tsx

…o docs/cursor-pagination

michelengelen

LGTM, but I'll defer the approval to @MBilalShafi who has more insight into this feature

MBilalShafi · 2025-10-20T18:50:39Z

docs/data/data-grid/server-side-data/ServerSideCursorBlocking.tsx

Should we block the switching of the next page in this demo like the one in unknown case here until the page being fetched has been fetched to avoid incorrect values set for all the skipped pages?

Screen.Recording.2025-10-20.at.23.44.49.mov

MBilalShafi · 2025-10-20T19:05:22Z

docs/data/data-grid/server-side-data/ServerSideCursorNonBlocking.tsx

Since the methods getLast and pushKey are used in the userland and not used internally, for a better separation of concerns, does it makes sense to use the default data source cache (not pass a custom one) and maintain a separate class encapsulating cacheKeys, getLast, and pushKey in the userland and consume it in the dataSource.getRows() method?

If needed, it can interact with the internal cache using apiRef.current.dataSource.cache.

Wdyt?

I don't think so.

apiRef.current.dataSource.cache is not documented yet

it sounds more complicated than let user handle their own cache (there could be project specific logic that we haven't think of), so for simplicity, let's use a custom cache implementation which is already documented.

MBilalShafi · 2025-10-20T19:07:41Z

docs/data/data-grid/server-side-data/ServerSideCursorNonBlocking.tsx

+        columns={columns}
+        dataSource={dataSource}
+        dataSourceCache={cache}
+        pagination


Should we add an error handling (onDataSourceError()) to this demo, causing the page to reset on the last loaded one if one of them fails?

Because all the responses are chained together, if one of them fails, the view will remain into loading state forever.

Example: https://stackblitz.com/edit/gy5p4ufa?file=src%2FDemo.tsx

Screen.Recording.2025-10-21.at.00.03.43.mov

That's a good point. I think if there is an error, the page will have to reset back to the latest success query

Here is updated version with error handling. I set the error to happen on page 8 to demonstrate the error handling. I took this approach because it's the simplest one.

I tried to use onDataSourceError but it does not work well for this non-blocking demo.

Screen.Recording.2568-10-21.at.16.52.03.mov

…o docs/cursor-pagination

siriwatknp added 2 commits September 25, 2025 09:17

support cursor-based pagination

dc0f53a

add recipe

39fb891

siriwatknp added scope: data grid Changes related to the data grid. type: new feature Expand the scope of the product to solve a new problem. labels Sep 25, 2025

siriwatknp added 5 commits September 25, 2025 10:15

split cache interface

3da0152

refactor

980d595

move docs

f4d39d6

update docs

6d25195

add size method

5e6eef6

siriwatknp commented Sep 25, 2025

View reviewed changes

packages/x-data-grid/src/internals/utils/cache.ts Show resolved Hide resolved

siriwatknp added 5 commits September 26, 2025 09:23

Merge branch 'master' of https://github.com/mui-org/material-ui-x int…

6a45f23

…o docs/cursor-pagination

revert changes

b0e488c

add cursor recipes

fc30e53

Merge branch 'master' of https://github.com/mui-org/material-ui-x int…

0da43e9

…o docs/cursor-pagination

restore

cfbeff3

siriwatknp changed the title ~~[Data Grid] Support cursor pagination with recipe~~ [Data Grid] Add recipe for cursor pagination with data source Sep 30, 2025

siriwatknp requested a review from a team September 30, 2025 04:27

siriwatknp marked this pull request as ready for review September 30, 2025 04:27

adjust minmax delay

ae60bef

siriwatknp mentioned this pull request Oct 14, 2025

[data grid] Clarification for dataSource usage and cursor-based pagination #18878

Open

MBilalShafi reviewed Oct 15, 2025

View reviewed changes

docs/data/data-grid/server-side-data/ServerSideCursorBlocking.tsx Show resolved Hide resolved

docs/data/data-grid/server-side-data/ServerSideCursorNonBlocking.tsx Show resolved Hide resolved

siriwatknp added 3 commits October 16, 2025 13:35

Merge branch 'master' of https://github.com/mui-org/material-ui-x int…

3b798a1

…o docs/cursor-pagination

apply suggestion to useRef for paginationModel

0537221

update demos

5f6965a

siriwatknp requested a review from MBilalShafi October 20, 2025 03:40

michelengelen reviewed Oct 20, 2025

View reviewed changes

MBilalShafi reviewed Oct 20, 2025

View reviewed changes

siriwatknp added 2 commits October 21, 2025 11:41

Merge branch 'master' of https://github.com/mui-org/material-ui-x int…

c29ef7a

…o docs/cursor-pagination

fix blocking demo

e1d7677

siriwatknp added 2 commits October 21, 2025 16:35

update demo to handle error

5c0b468

Merge branch 'master' into docs/cursor-pagination

64d79ee

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

[Data Grid] Add recipe for cursor pagination with data source #19700

[Data Grid] Add recipe for cursor pagination with data source #19700

Uh oh!

siriwatknp commented Sep 25, 2025 •

edited

Loading

Uh oh!

mui-bot commented Sep 25, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

michelengelen left a comment

Uh oh!

MBilalShafi Oct 20, 2025

Uh oh!

MBilalShafi Oct 20, 2025 •

edited

Loading

Uh oh!

siriwatknp Oct 21, 2025

Uh oh!

MBilalShafi Oct 20, 2025

Uh oh!

siriwatknp Oct 21, 2025

Uh oh!

siriwatknp Oct 21, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

[Data Grid] Add recipe for cursor pagination with data source #19700

Are you sure you want to change the base?

[Data Grid] Add recipe for cursor pagination with data source #19700

Uh oh!

Conversation

siriwatknp commented Sep 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Documentation Updates

New Demo Components

Technical Implementation

Blocking Approach

Non-blocking Approach

Benefits

Uh oh!

mui-bot commented Sep 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bundle size report

Uh oh!

Uh oh!

Uh oh!

Uh oh!

michelengelen left a comment

Choose a reason for hiding this comment

Uh oh!

MBilalShafi Oct 20, 2025

Choose a reason for hiding this comment

Uh oh!

MBilalShafi Oct 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

siriwatknp Oct 21, 2025

Choose a reason for hiding this comment

Uh oh!

MBilalShafi Oct 20, 2025

Choose a reason for hiding this comment

Uh oh!

siriwatknp Oct 21, 2025

Choose a reason for hiding this comment

Uh oh!

siriwatknp Oct 21, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

siriwatknp commented Sep 25, 2025 •

edited

Loading

mui-bot commented Sep 25, 2025 •

edited

Loading

MBilalShafi Oct 20, 2025 •

edited

Loading