Data Grid - Server-side lazy loading 🧪

Learn how to implement lazy-loading rows with a server-side data source.

Lazy loading changes the way pagination works by removing page controls and loading data dynamically (in a single list) as the user scrolls through the grid.

You can enable it with the unstable_lazyLoading prop paired with the unstable_dataSource prop.

Initially, data for the first page is fetched and displayed in the grid. The value of the total row count determines when the next page's data is loaded:

If the total row count is known, the Data Grid is filled with skeleton rows and fetches more data if one of the skeleton rows falls into the rendering context. This loading strategy is often referred to as viewport loading.
If the total row count is unknown, the Data Grid fetches more data when the user scrolls to the bottom. This loading strategy is often referred to as infinite loading.

Viewport loading

Viewport loading mode is enabled when the row count is known (and is greater than or equal to zero). The Grid fetches the first page immediately and adds skeleton rows to match the total row count. Other pages are fetched once the user starts scrolling and moves a skeleton row inside the rendering context (with the index range defined by virtualization).

If the user scrolls too fast, the Grid loads multiple pages with one request (by adjusting start and end parameters) to reduce the server load.

The demo below shows how viewport loading mode works:

Request throttling

As a user scrolls through the Grid, the rendering context changes and the Grid tries to fill in any missing rows by making a new server request. It also throttles new data fetches to avoid making unnecessary requests. The default throttle time is 500 milliseconds. Use the unstable_lazyLoadingRequestThrottleMs prop to set a custom time, as shown below:

Infinite loading

Infinite loading mode is enabled when the row count is unknown (either -1 or undefined). A new page is loaded when the scroll reaches the bottom of the viewport area.

You can use the scrollEndThreshold prop to change the area that triggers new requests.

The demo below shows how infinite loading mode works. Page size is set to 15 and the mock server is configured to return a total of 100 rows. When the response contains no new rows, the Grid stops requesting new data.

Updating the loading mode

The Grid changes the loading mode dynamically if the total row count gets updated by changing the rowCount prop, returning different rowCount in GridGetRowsResponse or via setRowCount() API.

Based on the previous and the new value for the total row count, the following scenarios are possible:

Unknown rowCount to known rowCount: When the row count is set to a valid value from an unknown value, the Data Grid switches to viewport loading mode. It checks the number of already fetched rows and adds skeleton rows to match the provided row count.
Known rowCount to unknown rowCount: If the row count is updated and set to -1, the Data Grid resets, fetches the first page, then sets itself to infinite loading mode.
Known rowCount greater than the actual row count: This can happen either by reducing the value of the row count after more rows were already fetched, or if the row count was unknown and the Grid (while in the infinite loading mode) already fetched more rows. In this case, the Grid resets, fetches the first page, and then continues in one mode or the other depending on the new value of the rowCount.

The demo below serves as a showcase of the behavior described above, and is not representative of something you would implement in a real-world scenario.

Nested lazy loading 🚧

When completed, it will be possible to use the unstable_lazyLoading flag in combination with tree data and row grouping.

Error handling

To handle errors, use the unstable_onDataSourceError() prop as described in Server-side data—Error handling.

You can pass the second parameter of type GridGetRowsParams to the getRows() method of the unstable_dataSource to retry the request. If successful, the Data Grid uses rows and rowCount data to determine if the rows should be appended at the end of the grid or if the skeleton rows should be replaced.

The following demo gives an example how to use GridGetRowsParams to retry a failed request.