Skip to content
Edit this page

Data Grid - Pagination

Easily paginate your rows and only fetch what you need.

⚠️ The default pagination behavior depends on your plan.

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

Size of the page

The MIT DataGrid is limited to pages of up to 100 rows. If you want larger pages, you will need to migrate to the Pro plan

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

<DataGrid
  pageSize={pageSize}
  onPageSizeChange={(newPageSize) => setPageSize(newPageSize)}
  rowsPerPageOptions={[5, 10, 20]}
  pagination
  {...data}
/>

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.

⚠️ You can't use both the autoPageSize and autoHeight props at the same time because autoHeight scales the height of the grid according to the pageSize.

Initialize the page size

To initialize the page size without controlling it, provide the page size to the initialState prop.

<DataGrid
  initialState={{
    pagination: {
      pageSize: 10,
    },
  }}
/>

<DataGrid
  {...data}
  initialState={{
    ...data.initialState,
    pagination: {
      pageSize: 25,
    },
  }}
/>

Controlled page size

Use the pageSize prop to control the size of the pages.

You can use the onPageSizeChange prop to listen to changes to the page size and update the prop accordingly.

<DataGrid
  pageSize={pageSize}
  onPageSizeChange={(newPage) => setPageSize(newPage)}
  pagination
  {...data}
/>

Current page

Initialize the page

To initialize the page without controlling it, provide the page to the initialState prop.

<DataGrid
  initialState={{
    pagination: {
      page: 1,
    },
  }}
/>

<DataGrid
  {...data}
  initialState={{
    ...data.initialState,
    pagination: {
      page: 1,
    },
  }}
  pageSize={5}
  rowsPerPageOptions={[5]}
  pagination
/>

Controlled page

Use the page prop to control the size of the pages.

You can use the onPageChange prop to listen to changes to the page and update the prop accordingly.

<DataGrid
  page={page}
  onPageChange={(newPage) => setPage(newPage)}
  pageSize={5}
  rowsPerPageOptions={[5]}
  pagination
  {...data}
/>

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 grid. If your dataset is too big, and you only want to fetch the current page, you can use server-side pagination.

Note: For more information regarding server-side pagination in combination with controlled selection check here

Basic implementation

  • Set the prop paginationMode to server
  • Provide a rowCount prop to let the grid know how many pages there are
  • Add an onPageChange callback to load the rows when the page changes

Since rowCount prop is used to compute the number of available pages, switching it to undefined during loading reset page to zero. To avoid this problem, we recommend to keep the previous value of rowCount while loading as follow:

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

<DataGrid rowCount={rowCountState} />;

<DataGrid
  rows={data}
  rowCount={rowCountState}
  loading={isLoading}
  rowsPerPageOptions={[5]}
  pagination
  page={page}
  pageSize={pageSize}
  paginationMode="server"
  onPageChange={(newPage) => setPage(newPage)}
  onPageSizeChange={(newPageSize) => setPageSize(newPageSize)}
  columns={columns}
  initialState={initialState}
/>

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

⚠️ Only use this API as the last option. Give preference to the props to control the grid.

Signature:
setPage: (page: number) => void
Signature:
setPageSize: (pageSize: number) => void

Selectors

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) => { id: GridRowId; model: any }[]
// or
gridPaginatedVisibleSortedGridRowEntriesSelector: (state: GridState, instanceId?: number) => { id: GridRowId; model: any }[]
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:
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