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.

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

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

Row count is available (known)
Row count is not available (unknown)
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.

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

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

Press Enter to start editing

If the value rowCount becomes undefined during loading, it will reset the page to zero. To avoid this issue, you can memoize the rowCount value to ensure it doesn't change during loading:

const rowCountRef = React.useRef(pageInfo?.totalRowCount || 0);

const rowCount = React.useMemo(() => {
  if (pageInfo?.totalRowCount !== undefined) {
    rowCountRef.current = pageInfo.totalRowCount;
  }
  return rowCountRef.current;
}, [pageInfo?.totalRowCount]);

<DataGrid rowCount={rowCount} />;

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.

<DataGrid
  apiRef={apiRef}
  rows={rows}
  {...data}
  initialState={{ ...data.initialState, pagination: { rowCount: -1 } }}
  paginationMeta={paginationMeta}
  loading={isLoading}
  pageSizeOptions={[5, 10, 25, 50]}
  paginationModel={paginationModel}
  paginationMode="server"
  onPaginationModelChange={setPaginationModel}
/>

<DataGrid
  apiRef={apiRef}
  rows={rows}
  {...data}
  initialState={{ ...data.initialState, pagination: { rowCount: -1 } }}
  paginationMeta={paginationMeta}
  loading={isLoading}
  pageSizeOptions={[5, 10, 25, 50]}
  paginationModel={paginationModel}
  paginationMode="server"
  onPaginationModelChange={setPaginationModel}
/>

Press Enter to start editing

The value of the hasNextPage variable might become undefined during loading if it's handled by some external fetching hook resulting in unwanted computations, one possible solution could be to memoize the paginationMeta:

const paginationMetaRef = React.useRef<GridPaginationMeta>();

const paginationMeta = React.useMemo(() => {
  if (
    hasNextPage !== undefined &&
    paginationMetaRef.current?.hasNextPage !== hasNextPage
  ) {
    paginationMetaRef.current = { hasNextPage };
  }
  return paginationMetaRef.current;
}, [hasNextPage]);

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.

<Button onClick={() => apiRef.current.setRowCount(1000)}>Set Row Count</Button>
<div style={{ height: 400 }}>
  <DataGrid
    apiRef={apiRef}
    rows={rows}
    {...data}
    initialState={{ ...data.initialState, pagination: { rowCount: -1 } }}
    estimatedRowCount={100}
    paginationMeta={paginationMeta}
    loading={isLoading}
    pageSizeOptions={[10, 25, 50, 100]}
    paginationModel={paginationModel}
    paginationMode="server"
    onPaginationModelChange={setPaginationModel}
  />
</div>

<Button onClick={() => apiRef.current.setRowCount(1000)}>Set Row Count</Button>
<div style={{ height: 400 }}>
  <DataGrid
    apiRef={apiRef}
    rows={rows}
    {...data}
    initialState={{ ...data.initialState, pagination: { rowCount: -1 } }}
    estimatedRowCount={100}
    paginationMeta={paginationMeta}
    loading={isLoading}
    pageSizeOptions={[10, 25, 50, 100]}
    paginationModel={paginationModel}
    paginationMode="server"
    onPaginationModelChange={setPaginationModel}
  />
</div>

Press Enter to start editing

🌍 Localization of the estimated row count

The Data Grid uses the Table Pagination component from the Material UI library which doesn't support estimated row count. Until this is supported natively by the Table Pagination component, a workaround to make the localization work is to provide the labelDisplayedRows function to the localeText.MuiTablePagination property as per the locale you are interested in.

The Grid injects an additional variable estimated to the labelDisplayedRows function which you can use to accomodate the estimated row count. The following example demonstrates how to show the estimated row count in the pagination footer in the Croatian (hr-HR) language.

const labelDisplayedRows = ({ from, to, count, estimated }) => {
  if (!estimated) {
    return `${from}–${to} od ${count !== -1 ? count : `više nego ${to}`}`,
  }
  return `${from}–${to} od ${count !== -1 ? count : `više nego ${estimated > to ? estimated : to}`}`;
}

<DataGrid
  {...data}
  localeText={{
    MuiTablePagination: {
      labelDisplayedRows,
    },
  }}
/>

For more information, see Translation keys section of the localization documentation.

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.

Row count

KnownUnknownEstimated

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.

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

setPaginationMeta()

Sets the paginationMeta to a new value.

Signature:

setPaginationMeta: (paginationMeta: GridPaginationMeta) => void

setPaginationModel()

Sets the paginationModel to a new value.

Signature:

setPaginationModel: (model: GridPaginationModel) => void

setRowCount()

Sets the rowCount to a new value.

Signature:

setRowCount: (rowCount: number) => 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) => GridRowEntry<GridValidRowModel>[]
// or
gridPaginatedVisibleSortedGridRowEntriesSelector: (state: GridState, instanceId?: number) => GridRowEntry<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)

gridPaginationMetaSelector

Get the pagination meta

Signature:

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

Example

gridPaginationMetaSelector(apiRef)
// or
gridPaginationMetaSelector(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)

gridPaginationRowCountSelector

Get the row count

Signature:

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

Example

gridPaginationRowCountSelector(apiRef)
// or
gridPaginationRowCountSelector(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