Data Grid - Pagination

Easily paginate your rows and only fetch what you need.

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 configure the page size the user can choose from with the pageSizeOptions prop.

It's possible to customize the options shown in the "Rows per page" select using the pageSizeOptions prop. You should either provide an array of:

numbers, each number will be used for the option's label and value.
objects, the value and label keys will be used respectively for the value and label of the option (useful for language strings such as 'All').

<DataGrid
  {...data}
  initialState={{
    ...data.initialState,
    pagination: { paginationModel: { pageSize: 5 } },
  }}
  pageSizeOptions={[5, 10, 25]}
/>

<DataGrid
  {...data}
  initialState={{
    ...data.initialState,
    pagination: { paginationModel: { pageSize: 5 } },
  }}
  pageSizeOptions={[5, 10, 25]}
/>

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.

Height of the container

Pagination on Pro and Premium

The default pagination behavior depends on your plan.

On the DataGrid, pagination is enabled by default and can't be disabled.
On the DataGridPro and DataGridPremium, pagination is disabled by default; use the pagination prop to enable it.

The following example activates pagination on a DataGridPremium component.

<DataGridPremium
  rows={rows}
  columns={columns}
  slots={{
    toolbar: CustomToolbar,
  }}
  pagination
  autoPageSize
/>

<DataGridPremium
  rows={rows}
  columns={columns}
  slots={{
    toolbar: CustomToolbar,
  }}
  pagination
  autoPageSize
/>

Press Enter to start editing

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 },
    },
  }}
/>

<DataGrid
  {...data}
  initialState={{
    ...data.initialState,
    pagination: {
      ...data.initialState?.pagination,
      paginationModel: {
        pageSize: 25,
        /* page: 0 // default value will be used if not passed */
      },
    },
  }}
/>

<DataGrid
  {...data}
  initialState={{
    ...data.initialState,
    pagination: {
      ...data.initialState?.pagination,
      paginationModel: {
        pageSize: 25,
        /* page: 0 // default value will be used if not passed */
      },
    },
  }}
/>

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}
/>;

<DataGrid
  paginationModel={paginationModel}
  onPaginationModelChange={setPaginationModel}
  {...data}
/>

<DataGrid
  paginationModel={paginationModel}
  onPaginationModelChange={setPaginationModel}
  {...data}
/>

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 only want to fetch the current page, you can use server-side pagination.

Basic implementation

Set the prop paginationMode to server
Provide a rowCount prop to let the data grid know how many pages there are
Use the onPaginationModelChange prop callback to load the rows when the page changes

Since the rowCount prop is used to compute the number of available pages, switching it to undefined during loading resets the page to zero. To avoid this problem, you can keep the previous value of rowCount while loading as follows:

const [rowCountState, setRowCountState] = React.useState(rowCount);
React.useEffect(() => {
  setRowCountState((prevRowCountState) =>
    rowCount !== undefined ? rowCount : prevRowCountState,
  );
}, [rowCount, setRowCountState]);

<DataGrid rowCount={rowCountState} />;

<DataGrid
  rows={rows}
  {...data}
  rowCount={rowCountState}
  loading={isLoading}
  pageSizeOptions={[5]}
  paginationModel={paginationModel}
  paginationMode="server"
  onPaginationModelChange={setPaginationModel}
/>

<DataGrid
  rows={rows}
  {...data}
  rowCount={rowCountState}
  loading={isLoading}
  pageSizeOptions={[5]}
  paginationModel={paginationModel}
  paginationMode="server"
  onPaginationModelChange={setPaginationModel}
/>

Press Enter to start editing

Cursor implementation

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 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.

setPage()

Sets the displayed page to the value given by page.

Signature:

setPage: (page: number) => void

setPageSize()

Sets the number of displayed rows to the value given by pageSize.

Signature:

setPageSize: (pageSize: number) => void

setPaginationModel()

Sets the paginationModel to a new value.

Signature:

setPaginationModel: (model: GridPaginationModel) => void

Selectors

gridPageCountSelector

Get the amount of pages needed to display all the rows if the pagination is enabled

Signature:

gridPageCountSelector: (apiRef: GridApiRef) => number
// or
gridPageCountSelector: (state: GridState, instanceId?: number) => number

Example

gridPageCountSelector(apiRef)
// or
gridPageCountSelector(state, apiRef.current.instanceId)

gridPageSelector

Get the index of the page to render if the pagination is enabled

Signature:

gridPageSelector: (apiRef: GridApiRef) => number
// or
gridPageSelector: (state: GridState, instanceId?: number) => number

Example

gridPageSelector(apiRef)
// or
gridPageSelector(state, apiRef.current.instanceId)

gridPageSizeSelector

Get the maximum amount of rows to display on a single page if the pagination is enabled

Signature:

gridPageSizeSelector: (apiRef: GridApiRef) => number
// or
gridPageSizeSelector: (state: GridState, instanceId?: number) => number

Example

gridPageSizeSelector(apiRef)
// or
gridPageSizeSelector(state, apiRef.current.instanceId)

gridPaginatedVisibleSortedGridRowEntriesSelector

Get the id and the model of each row to include in the current page if the pagination is enabled.

Signature:

gridPaginatedVisibleSortedGridRowEntriesSelector: (apiRef: GridApiRef) => { id: GridRowId; model: GridValidRowModel }[]
// or
gridPaginatedVisibleSortedGridRowEntriesSelector: (state: GridState, instanceId?: number) => { id: GridRowId; model: GridValidRowModel }[]

Example

gridPaginatedVisibleSortedGridRowEntriesSelector(apiRef)
// or
gridPaginatedVisibleSortedGridRowEntriesSelector(state, apiRef.current.instanceId)

gridPaginatedVisibleSortedGridRowIdsSelector

Get the id of each row to include in the current page if the pagination is enabled.

Signature:

gridPaginatedVisibleSortedGridRowIdsSelector: (apiRef: GridApiRef) => GridRowId[]
// or
gridPaginatedVisibleSortedGridRowIdsSelector: (state: GridState, instanceId?: number) => GridRowId[]

Example

gridPaginatedVisibleSortedGridRowIdsSelector(apiRef)
// or
gridPaginatedVisibleSortedGridRowIdsSelector(state, apiRef.current.instanceId)

gridPaginationModelSelector

Get the pagination model

Signature:

gridPaginationModelSelector: (apiRef: GridApiRef) => GridPaginationModel
// or
gridPaginationModelSelector: (state: GridState, instanceId?: number) => GridPaginationModel

Example

gridPaginationModelSelector(apiRef)
// or
gridPaginationModelSelector(state, apiRef.current.instanceId)

gridPaginationRowRangeSelector

Get the index of the first and the last row to include in the current page if the pagination is enabled.

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