Skip to content
Edit this page

Data Grid - State

Initialize and read the state of the data grid.

Initialize the state

Some state keys can be initialized with the initialState prop.

⚠️ The initialState can only be used to set the initial value of the state, the grid will not react if you change the initialState value later on.

If you need to fully control specific models, use the control props instead (e.g. prop.filterModel or prop.sortModel). You can find more information on the corresponding feature documentation page.

<DataGrid
  {...data}
  loading={loading}
  initialState={{
    filter: {
      filterModel: {
        items: [{ columnField: 'quantity', operatorValue: '>', value: 10000 }],
      },
    },
    sorting: {
      sortModel: [{ field: 'desk', sort: 'asc' }],
    },
  }}
/>

Access the state

The state is exposed on the apiRef object. It is strongly advised not to access the state values directly because the state itself is not considered a public API and its structure can change.

The x-data-grid-pro package exposes a set of state selectors that take the apiRef.current.state as an argument and return a value. You can use them to get data from the state without worrying about its internal structure.

Direct selector access

The simplest way to use a selector is to call it as a function with the state as its first argument.

const pageSize = gridPageSizeSelector(apiRef.current.state);

<Button size="small" onClick={handleSelectFirstVisibleRow}>
  Toggle the selection of the 1st row of the page
</Button>
<Box sx={{ width: '100%', height: 400, bgcolor: 'background.paper' }}>
  <DataGridPro apiRef={apiRef} pagination pageSize={10} {...data} />
</Box>

With useGridSelector

If you want to access sole state value in the render of your components, you can use the useGridSelector hook.

const pageSize = useGridSelector(apiRef, gridPageSizeSelector);

⚠️ This hook can only be used inside the context of the grid, such as custom components. Otherwise, you will have an error saying that the state is not initialized during the first render.

<DataGridPro
  {...data}
  loading={loading}
  apiRef={apiRef}
  pagination
  pageSize={10}
  hideFooter
  components={{
    Toolbar,
  }}
/>

Catalog of selectors

Some selectors are yet to be documented.

Filtering

Signature:
gridFilterModelSelector: (state: GridState) => GridFilterModel
Example
const filterModel = gridFilterModelSelector(
  apiRef.current.state
);
Signature:
gridVisibleRowCountSelector: (state: GridState) => number
Example
const visibleRowCount = gridVisibleRowCountSelector(
  apiRef.current.state
);
Signature:
gridVisibleSortedRowEntriesSelector: (state: GridState) => { id: GridRowId; model: { [key: string]: any } }[]
Example
const visibleSortedRowEntries = gridVisibleSortedRowEntriesSelector(
  apiRef.current.state
);
Signature:
gridVisibleSortedRowIdsSelector: (state: GridState) => GridRowId[]
Example
const visibleSortedRowIds = gridVisibleSortedRowIdsSelector(
  apiRef.current.state
);
Signature:
gridVisibleSortedTopLevelRowEntriesSelector: (state: GridState) => { id: GridRowId; model: { [key: string]: any } }[]
Example
const visibleSortedTopLevelRowEntries = gridVisibleSortedTopLevelRowEntriesSelector(
  apiRef.current.state
);
Signature:
gridVisibleTopLevelRowCountSelector: (state: GridState) => number
Example
const visibleTopLevelRowCount = gridVisibleTopLevelRowCountSelector(
  apiRef.current.state
);

Pagination

Signature:
gridPageCountSelector: (state: GridState) => number
Example
const pageCount = gridPageCountSelector(
  apiRef.current.state
);
Signature:
gridPageSelector: (state: GridState) => number
Example
const page = gridPageSelector(
  apiRef.current.state
);
Signature:
gridPageSizeSelector: (state: GridState) => number
Example
const pageSize = gridPageSizeSelector(
  apiRef.current.state
);
Signature:
gridPaginatedVisibleSortedGridRowEntriesSelector: (state: GridState) => { id: GridRowId; model: { [key: string]: any } }[]
Example
const paginatedVisibleSortedGridRowEntries = gridPaginatedVisibleSortedGridRowEntriesSelector(
  apiRef.current.state
);
Signature:
gridPaginatedVisibleSortedGridRowIdsSelector: (state: GridState) => GridRowId[]
Example
const paginatedVisibleSortedGridRowIds = gridPaginatedVisibleSortedGridRowIdsSelector(
  apiRef.current.state
);
Signature:
gridPaginationRowRangeSelector: (state: GridState) => { firstRowIndex: number; lastRowIndex: number } | null
Example
const paginationRowRange = gridPaginationRowRangeSelector(
  apiRef.current.state
);

Sorting

Signature:
gridSortModelSelector: (state: GridState) => GridSortModel
Example
const sortModel = gridSortModelSelector(
  apiRef.current.state
);
Signature:
gridSortedRowEntriesSelector: (state: GridState) => { id: GridRowId; model: { [key: string]: any } }[]
Example
const sortedRowEntries = gridSortedRowEntriesSelector(
  apiRef.current.state
);
Signature:
gridSortedRowIdsSelector: (state: GridState) => GridRowId[]
Example
const sortedRowIds = gridSortedRowIdsSelector(
  apiRef.current.state
);

Save and restore the state

⚠️ This feature isn't implemented yet. It's coming.

👍 Upvote issue #820 if you want to see it land faster.

API