Skip to content
+

Data Grid - Pagination

Easily paginate your rows and only fetch what you need.

Enabling pagination

The default pagination behavior depends on your plan:

Community plan

For the Community Data Grid, pagination is enabled by default and cannot be disabled.

Press Enter to start editing

Pro and Premium

For the Pro and Premium Data Grid, pagination is disabled by default; use the pagination prop to enable it.

Press Enter to start editing

Size of the page

The DataGrid (MIT license) is limited to pages of up to 100 rows. If you want larger pages, you will need to upgrade to Pro plan or above.

By default, each page contains 100 rows. The user can change the size of the page through the selector in the footer.

Page size options

You can customize the options shown in the "Rows per page" select using the pageSizeOptions prop. You should provide an array of items, each item should be one of these types:

  • number, each number will be used for the option's label and value.

    <DataGrid pageSizeOptions={[5, 10, 25]}>
    
  • object, the value and label keys will be used respectively for the value and label of the option.

    <DataGrid pageSizeOptions={[10, 100, { value: 1000, label: '1,000' }]}>
    
Press Enter to start editing

Automatic page size

Use the autoPageSize prop to auto-scale the pageSize to match the container height and the max number of rows that can be displayed without a vertical scroll bar.

Pagination model

The pagination model is an object containing the current page and the size of the page. The default value is { page: 0, pageSize: 100 }. To change the default value, make it controlled by paginationModel prop or initialize a custom value using initialState.pagination.paginationModel.

Initializing the pagination model

To initialize the pagination model without controlling it, provide the paginationModel to the initialState prop. If you don't provide a value for one of the properties, the default value will be used.

<DataGrid
  initialState={{
    pagination: {
      paginationModel: { pageSize: 25, page: 0 },
    },
  }}
/>
Press Enter to start editing

Controlled pagination model

Pass the paginationModel prop to control the size and current page of the grid. You can use the onPaginationModelChange prop to listen to changes to the paginationModel and update the prop accordingly.

const [paginationModel, setPaginationModel] = React.useState({
  pageSize: 25,
  page: 0,
});

<DataGrid
  paginationModel={paginationModel}
  onPaginationModelChange={setPaginationModel}
/>;
Press Enter to start editing

Server-side pagination

By default, the pagination is handled on the client. This means you have to give the rows of all pages to the data grid. If your dataset is too big, and you want to fetch the pages on demand, you can use server-side pagination.

In general, the server-side pagination could be categorized into two types:

  • Index-based pagination
  • Cursor-based pagination

Index-based pagination

The index-based pagination uses the page and pageSize to fetch the data from the server page by page.

To enable server-side pagination, you need to:

  • Set the paginationMode prop to server
  • Use the onPaginationModelChange prop to react to the page changes and load the data from the server

The server-side pagination can be further categorized into sub-types based on the availability of the total number of rows or rowCount.

The Data Grid uses the rowCount to calculate the number of pages and to show the information about the current state of the pagination in the footer. You can provide the rowCount in one of the following ways:

  • Initialize. Use the initialState.pagination.rowCount prop to initialize the rowCount.
  • Control. Use the rowCount prop along with onRowCountChange to control the rowCount and reflect the changes when the row count is updated.
  • Set using the API. Use the apiRef.current.setRowCount method to set the rowCount after the Grid is initialized.

There can be three different possibilities regarding the availability of the rowCount on the server-side:

  1. Row count is available (known)
  2. Row count is not available (unknown)
  3. Row count is available but is not accurate and may update later on (estimated)

You can configure rowCount, paginationMeta.hasNextPage, and estimatedRowCount props to handle the above scenarios.

rowCount paginationMeta.hasNextPage estimatedRowCount
Known row count number
Unknown row count -1 boolean
Estimated row count -1 boolean number

Known row count

Pass the props to the Data Grid as explained in the table above to handle the case when the actual row count is known, as the following example demonstrates.

Press Enter to start editing

Unknown row count

Pass the props to the Data Grid as explained in the table above to handle the case when the actual row count is unknown, as the following example demonstrates.

Press Enter to start editing

Estimated row count

Estimated row count could be considered a hybrid approach that switches between the "Known row count" and "Unknown row count" use cases.

Initially, when an estimatedRowCount is set and rowCount={-1}, the Data Grid behaves as in the "Unknown row count" use case, but with the estimatedRowCount value shown in the pagination footer.

If the number of rows loaded exceeds the estimatedRowCount, the Data Grid ignores the estimatedRowCount and the behavior is identical to the "Unknown row count" use case.

When the hasNextPage returns false or rowCount is set to a positive number, the Data Grid switches to the "Known row count" behavior.

In the following example, the actual row count is 1000 but the Data Grid is initially provided with estimatedRowCount={100}. You can set the rowCount to the actual row count by pressing the "Set Row Count" button.

Press Enter to start editing

Cursor-based pagination

You can also handle servers with cursor-based pagination. To do so, you just have to keep track of the next cursor associated with each page you fetched.

Custom pagination UI

You can customize the rendering of the pagination in the footer following the component section of the documentation.

apiRef

The Data Grid exposes a set of methods that enables all of these features using the imperative apiRef. To know more about how to use it, check the API Object section.

Signature:
setPage: (page: number) => void
Signature:
setPageSize: (pageSize: number) => void
Signature:
setPaginationMeta: (paginationMeta: GridPaginationMeta) => void
Signature:
setPaginationModel: (model: GridPaginationModel) => void
Signature:
setRowCount: (rowCount: number) => void
Signature:
gridPageCountSelector: (apiRef: GridApiRef) => number
// or
gridPageCountSelector: (state: GridState, instanceId?: number) => number
Example
gridPageCountSelector(apiRef)
// or
gridPageCountSelector(state, apiRef.current.instanceId)
Signature:
gridPageSelector: (apiRef: GridApiRef) => number
// or
gridPageSelector: (state: GridState, instanceId?: number) => number
Example
gridPageSelector(apiRef)
// or
gridPageSelector(state, apiRef.current.instanceId)
Signature:
gridPageSizeSelector: (apiRef: GridApiRef) => number
// or
gridPageSizeSelector: (state: GridState, instanceId?: number) => number
Example
gridPageSizeSelector(apiRef)
// or
gridPageSizeSelector(state, apiRef.current.instanceId)
Signature:
gridPaginatedVisibleSortedGridRowEntriesSelector: (apiRef: GridApiRef) => GridRowEntry<GridValidRowModel>[]
// or
gridPaginatedVisibleSortedGridRowEntriesSelector: (state: GridState, instanceId?: number) => GridRowEntry<GridValidRowModel>[]
Example
gridPaginatedVisibleSortedGridRowEntriesSelector(apiRef)
// or
gridPaginatedVisibleSortedGridRowEntriesSelector(state, apiRef.current.instanceId)
Signature:
gridPaginatedVisibleSortedGridRowIdsSelector: (apiRef: GridApiRef) => GridRowId[]
// or
gridPaginatedVisibleSortedGridRowIdsSelector: (state: GridState, instanceId?: number) => GridRowId[]
Example
gridPaginatedVisibleSortedGridRowIdsSelector(apiRef)
// or
gridPaginatedVisibleSortedGridRowIdsSelector(state, apiRef.current.instanceId)
Signature:
gridPaginationMetaSelector: (apiRef: GridApiRef) => GridPaginationMeta
// or
gridPaginationMetaSelector: (state: GridState, instanceId?: number) => GridPaginationMeta
Example
gridPaginationMetaSelector(apiRef)
// or
gridPaginationMetaSelector(state, apiRef.current.instanceId)
Signature:
gridPaginationModelSelector: (apiRef: GridApiRef) => GridPaginationModel
// or
gridPaginationModelSelector: (state: GridState, instanceId?: number) => GridPaginationModel
Example
gridPaginationModelSelector(apiRef)
// or
gridPaginationModelSelector(state, apiRef.current.instanceId)
Signature:
gridPaginationRowCountSelector: (apiRef: GridApiRef) => number
// or
gridPaginationRowCountSelector: (state: GridState, instanceId?: number) => number
Example
gridPaginationRowCountSelector(apiRef)
// or
gridPaginationRowCountSelector(state, apiRef.current.instanceId)
Signature:
gridPaginationRowRangeSelector: (apiRef: GridApiRef) => { firstRowIndex: number; lastRowIndex: number } | null
// or
gridPaginationRowRangeSelector: (state: GridState, instanceId?: number) => { firstRowIndex: number; lastRowIndex: number } | null
Example
gridPaginationRowRangeSelector(apiRef)
// or
gridPaginationRowRangeSelector(state, apiRef.current.instanceId)

More information about the selectors and how to use them on the dedicated page

API