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. This prop has the same format as the returned value of apiRef.current.exportState().

⚠️ 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={{
    ...data.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 @mui/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 apiRef as its first argument.

const pageSize = gridPageSizeSelector(apiRef);

Note: Calling with apiRef.current.state also works but it may cause side effects when multiple grid instances are in the same page. If you still need to call it with the state, do not forget to pass the instance ID as the example:

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

<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}
  pagination
  pageSize={10}
  hideFooter
  components={{
    Toolbar,
  }}
/>

Catalog of selectors

Some selectors are yet to be documented.

Columns

Signature:
gridColumnDefinitionsSelector: (apiRef: GridApiRef) => GridStateColDef<any, any, any>[]
// or
gridColumnDefinitionsSelector: (state: GridState, instanceId?: number) => GridStateColDef<any, any, any>[]
Example
gridColumnDefinitionsSelector(apiRef)
// or
gridColumnDefinitionsSelector(state, apiRef.current.instanceId)
Signature:
gridColumnFieldsSelector: (apiRef: GridApiRef) => string[]
// or
gridColumnFieldsSelector: (state: GridState, instanceId?: number) => string[]
Example
gridColumnFieldsSelector(apiRef)
// or
gridColumnFieldsSelector(state, apiRef.current.instanceId)
Signature:
gridColumnLookupSelector: (apiRef: GridApiRef) => GridColumnLookup
// or
gridColumnLookupSelector: (state: GridState, instanceId?: number) => GridColumnLookup
Example
gridColumnLookupSelector(apiRef)
// or
gridColumnLookupSelector(state, apiRef.current.instanceId)
Signature:
gridFilterableColumnDefinitionsSelector: (apiRef: GridApiRef) => GridStateColDef<any, any, any>[]
// or
gridFilterableColumnDefinitionsSelector: (state: GridState, instanceId?: number) => GridStateColDef<any, any, any>[]
Example
gridFilterableColumnDefinitionsSelector(apiRef)
// or
gridFilterableColumnDefinitionsSelector(state, apiRef.current.instanceId)
Signature:
gridFilterableColumnLookupSelector: (apiRef: GridApiRef) => GridColumnLookup
// or
gridFilterableColumnLookupSelector: (state: GridState, instanceId?: number) => GridColumnLookup
Example
gridFilterableColumnLookupSelector(apiRef)
// or
gridFilterableColumnLookupSelector(state, apiRef.current.instanceId)

Visible Columns

Signature:
gridColumnPositionsSelector: (apiRef: GridApiRef) => number[]
// or
gridColumnPositionsSelector: (state: GridState, instanceId?: number) => number[]
Example
gridColumnPositionsSelector(apiRef)
// or
gridColumnPositionsSelector(state, apiRef.current.instanceId)
Signature:
gridColumnVisibilityModelSelector: (apiRef: GridApiRef) => GridColumnVisibilityModel
// or
gridColumnVisibilityModelSelector: (state: GridState, instanceId?: number) => GridColumnVisibilityModel
Example
gridColumnVisibilityModelSelector(apiRef)
// or
gridColumnVisibilityModelSelector(state, apiRef.current.instanceId)
Signature:
gridColumnsTotalWidthSelector: (apiRef: GridApiRef) => number
// or
gridColumnsTotalWidthSelector: (state: GridState, instanceId?: number) => number
Example
gridColumnsTotalWidthSelector(apiRef)
// or
gridColumnsTotalWidthSelector(state, apiRef.current.instanceId)
Signature:
gridVisibleColumnDefinitionsSelector: (apiRef: GridApiRef) => GridStateColDef<any, any, any>[]
// or
gridVisibleColumnDefinitionsSelector: (state: GridState, instanceId?: number) => GridStateColDef<any, any, any>[]
Example
gridVisibleColumnDefinitionsSelector(apiRef)
// or
gridVisibleColumnDefinitionsSelector(state, apiRef.current.instanceId)
Signature:
gridVisibleColumnFieldsSelector: (apiRef: GridApiRef) => string[]
// or
gridVisibleColumnFieldsSelector: (state: GridState, instanceId?: number) => string[]
Example
gridVisibleColumnFieldsSelector(apiRef)
// or
gridVisibleColumnFieldsSelector(state, apiRef.current.instanceId)

Filtering

Signature:
gridFilterModelSelector: (apiRef: GridApiRef) => GridFilterModel
// or
gridFilterModelSelector: (state: GridState, instanceId?: number) => GridFilterModel
Example
gridFilterModelSelector(apiRef)
// or
gridFilterModelSelector(state, apiRef.current.instanceId)
Signature:
gridFilterStateSelector: (state: GridState) => GridFilterState
Example
const filterState = gridFilterStateSelector(apiRef.current.state);
Signature:
gridFilteredSortedRowEntriesSelector: (apiRef: GridApiRef) => { id: GridRowId; model: any }[]
// or
gridFilteredSortedRowEntriesSelector: (state: GridState, instanceId?: number) => { id: GridRowId; model: any }[]
Example
gridFilteredSortedRowEntriesSelector(apiRef)
// or
gridFilteredSortedRowEntriesSelector(state, apiRef.current.instanceId)
Signature:
gridFilteredSortedRowIdsSelector: (apiRef: GridApiRef) => GridRowId[]
// or
gridFilteredSortedRowIdsSelector: (state: GridState, instanceId?: number) => GridRowId[]
Example
gridFilteredSortedRowIdsSelector(apiRef)
// or
gridFilteredSortedRowIdsSelector(state, apiRef.current.instanceId)
Signature:
gridVisibleRowCountSelector: (apiRef: GridApiRef) => number
// or
gridVisibleRowCountSelector: (state: GridState, instanceId?: number) => number
Example
gridVisibleRowCountSelector(apiRef)
// or
gridVisibleRowCountSelector(state, apiRef.current.instanceId)
Signature:
gridVisibleSortedRowEntriesSelector: (apiRef: GridApiRef) => { id: GridRowId; model: any }[]
// or
gridVisibleSortedRowEntriesSelector: (state: GridState, instanceId?: number) => { id: GridRowId; model: any }[]
Example
gridVisibleSortedRowEntriesSelector(apiRef)
// or
gridVisibleSortedRowEntriesSelector(state, apiRef.current.instanceId)
Signature:
gridVisibleSortedRowIdsSelector: (apiRef: GridApiRef) => GridRowId[]
// or
gridVisibleSortedRowIdsSelector: (state: GridState, instanceId?: number) => GridRowId[]
Example
gridVisibleSortedRowIdsSelector(apiRef)
// or
gridVisibleSortedRowIdsSelector(state, apiRef.current.instanceId)
Signature:
gridVisibleSortedTopLevelRowEntriesSelector: (apiRef: GridApiRef) => { id: GridRowId; model: any }[]
// or
gridVisibleSortedTopLevelRowEntriesSelector: (state: GridState, instanceId?: number) => { id: GridRowId; model: any }[]
Example
gridVisibleSortedTopLevelRowEntriesSelector(apiRef)
// or
gridVisibleSortedTopLevelRowEntriesSelector(state, apiRef.current.instanceId)
Signature:
gridVisibleTopLevelRowCountSelector: (apiRef: GridApiRef) => number
// or
gridVisibleTopLevelRowCountSelector: (state: GridState, instanceId?: number) => number
Example
gridVisibleTopLevelRowCountSelector(apiRef)
// or
gridVisibleTopLevelRowCountSelector(state, apiRef.current.instanceId)

Pagination

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)

Sorting

Signature:
gridSortModelSelector: (apiRef: GridApiRef) => GridSortModel
// or
gridSortModelSelector: (state: GridState, instanceId?: number) => GridSortModel
Example
gridSortModelSelector(apiRef)
// or
gridSortModelSelector(state, apiRef.current.instanceId)
Signature:
gridSortedRowEntriesSelector: (apiRef: GridApiRef) => { id: GridRowId; model: any }[]
// or
gridSortedRowEntriesSelector: (state: GridState, instanceId?: number) => { id: GridRowId; model: any }[]
Example
gridSortedRowEntriesSelector(apiRef)
// or
gridSortedRowEntriesSelector(state, apiRef.current.instanceId)
Signature:
gridSortedRowIdsSelector: (apiRef: GridApiRef) => GridRowId[]
// or
gridSortedRowIdsSelector: (state: GridState, instanceId?: number) => GridRowId[]
Example
gridSortedRowIdsSelector(apiRef)
// or
gridSortedRowIdsSelector(state, apiRef.current.instanceId)

Save and restore the state

The current state of the grid can be exported using apiRef.current.exportState(). It can then be restored by either passing the returned value to the initialState prop or to the apiRef.current.restoreState() method.

Watch out for controlled models and their callbacks (onFilterModelChange if you use filterModel, for instance), as the grid will call those callbacks when restoring the state. But if the callback is not defined or if calling it does not update the prop value, then the restored value will not be applied.

⚠️ To avoid breaking changes, the grid only saves the column visibility if you are using the new api Make sure to initialize props.initialState.columns.columnVisibilityModel or to control props.columnVisibilityModel.

The easier way is to initialize the model with an empty object:

<DataGrid
  initialState={{
    columns: { columnVisibilityModel: {} },
  }}
/>

Restore the state with initialState

You can pass the state returned by apiRef.current.exportState() to the initialState prop. In the demo below, clicking on Recreate the 2nd grid will re-mount the 2nd grid with the current state of the 1st grid.

⚠️ If you restore the page using initialState before the data is fetched, the grid will automatically move to the 1st page.

Restore the state with apiRef

You can pass the state returned by apiRef.current.exportState() to the apiRef.current.restoreState method. In the demo below, clicking on Save current view will create a snapshot of the changes made in the state, considering the initial state. You can apply these changes on the grid later selecting a saved view in the Custom view menu.

Restore part of the state

It is possible to restore specific properties of the state using the apiRef.current.restoreState() method. For instance, to only restore the pinned columns:

apiRef.current.restoreState({
  pinnedColumns: ['brand'],
});

⚠️ Most of the state keys are not fully independent.

Restoring the pagination without restoring the filters or the sorting will work, but the rows displayed after the re-import will not be the same as before the export.

API