Skip to content
+

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

Press Enter to start editing

Access the state

The state is exposed on the apiRef object.

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 paginationModel = gridPaginationModelSelector(apiRef);

With useGridSelector

If you only need to access the state value in the render of your components, use the useGridSelector hook. This hook ensures there is a reactive binding such that when the state changes, the component in which this hook is used is re-rendered.

const paginationModel = useGridSelector(apiRef, gridPaginationModelSelector);
Press Enter to start editing

Catalog of selectors

Some selectors have not yet been documented.

Aggregation

Signature:
gridAggregationLookupSelector: (apiRef: GridApiRef) => GridAggregationLookup
// or
gridAggregationLookupSelector: (state: GridState, instanceId?: number) => GridAggregationLookup
Example
gridAggregationLookupSelector(apiRef)
// or
gridAggregationLookupSelector(state, apiRef.current.instanceId)
Signature:
gridAggregationModelSelector: (apiRef: GridApiRef) => GridAggregationModel
// or
gridAggregationModelSelector: (state: GridState, instanceId?: number) => GridAggregationModel
Example
gridAggregationModelSelector(apiRef)
// or
gridAggregationModelSelector(state, apiRef.current.instanceId)

Columns

Signature:
gridColumnDefinitionsSelector: (apiRef: GridApiRef) => GridStateColDef[]
// or
gridColumnDefinitionsSelector: (state: GridState, instanceId?: number) => GridStateColDef[]
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:
gridColumnsStateSelector: (state: GridState) => GridColumnsState
Example
const columnsState = gridColumnsStateSelector(apiRef.current.state);
Signature:
gridFilterableColumnDefinitionsSelector: (apiRef: GridApiRef) => GridStateColDef[]
// or
gridFilterableColumnDefinitionsSelector: (state: GridState, instanceId?: number) => GridStateColDef[]
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:
gridPinnedColumnsSelector: (state: GridState) => GridPinnedColumnFields
Example
const pinnedColumns = gridPinnedColumnsSelector(apiRef.current.state);
Signature:
gridVisibleColumnDefinitionsSelector: (apiRef: GridApiRef) => GridStateColDef[]
// or
gridVisibleColumnDefinitionsSelector: (state: GridState, instanceId?: number) => GridStateColDef[]
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)
Signature:
gridVisiblePinnedColumnDefinitionsSelector: (apiRef: GridApiRef) => { left: GridStateColDef[]; right: GridStateColDef[] }
// or
gridVisiblePinnedColumnDefinitionsSelector: (state: GridState, instanceId?: number) => { left: GridStateColDef[]; right: GridStateColDef[] }
Example
gridVisiblePinnedColumnDefinitionsSelector(apiRef)
// or
gridVisiblePinnedColumnDefinitionsSelector(state, apiRef.current.instanceId)

Filtering

Signature:
gridExpandedRowCountSelector: (apiRef: GridApiRef) => number
// or
gridExpandedRowCountSelector: (state: GridState, instanceId?: number) => number
Example
gridExpandedRowCountSelector(apiRef)
// or
gridExpandedRowCountSelector(state, apiRef.current.instanceId)
Signature:
gridExpandedSortedRowEntriesSelector: (apiRef: GridApiRef) => GridRowEntry<GridValidRowModel>[]
// or
gridExpandedSortedRowEntriesSelector: (state: GridState, instanceId?: number) => GridRowEntry<GridValidRowModel>[]
Example
gridExpandedSortedRowEntriesSelector(apiRef)
// or
gridExpandedSortedRowEntriesSelector(state, apiRef.current.instanceId)
Signature:
gridExpandedSortedRowIdsSelector: (apiRef: GridApiRef) => GridRowId[]
// or
gridExpandedSortedRowIdsSelector: (state: GridState, instanceId?: number) => GridRowId[]
Example
gridExpandedSortedRowIdsSelector(apiRef)
// or
gridExpandedSortedRowIdsSelector(state, apiRef.current.instanceId)
Signature:
gridFilterModelSelector: (apiRef: GridApiRef) => GridFilterModel
// or
gridFilterModelSelector: (state: GridState, instanceId?: number) => GridFilterModel
Example
gridFilterModelSelector(apiRef)
// or
gridFilterModelSelector(state, apiRef.current.instanceId)
Signature:
gridFilteredDescendantRowCountSelector: (apiRef: GridApiRef) => number
// or
gridFilteredDescendantRowCountSelector: (state: GridState, instanceId?: number) => number
Example
gridFilteredDescendantRowCountSelector(apiRef)
// or
gridFilteredDescendantRowCountSelector(state, apiRef.current.instanceId)
Signature:
gridFilteredRowCountSelector: (apiRef: GridApiRef) => number
// or
gridFilteredRowCountSelector: (state: GridState, instanceId?: number) => number
Example
gridFilteredRowCountSelector(apiRef)
// or
gridFilteredRowCountSelector(state, apiRef.current.instanceId)
Signature:
gridFilteredSortedRowEntriesSelector: (apiRef: GridApiRef) => GridRowEntry<GridValidRowModel>[]
// or
gridFilteredSortedRowEntriesSelector: (state: GridState, instanceId?: number) => GridRowEntry<GridValidRowModel>[]
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:
gridFilteredSortedTopLevelRowEntriesSelector: (apiRef: GridApiRef) => GridRowEntry<GridValidRowModel>[]
// or
gridFilteredSortedTopLevelRowEntriesSelector: (state: GridState, instanceId?: number) => GridRowEntry<GridValidRowModel>[]
Example
gridFilteredSortedTopLevelRowEntriesSelector(apiRef)
// or
gridFilteredSortedTopLevelRowEntriesSelector(state, apiRef.current.instanceId)
Signature:
gridFilteredTopLevelRowCountSelector: (apiRef: GridApiRef) => number
// or
gridFilteredTopLevelRowCountSelector: (state: GridState, instanceId?: number) => number
Example
gridFilteredTopLevelRowCountSelector(apiRef)
// or
gridFilteredTopLevelRowCountSelector(state, apiRef.current.instanceId)
Signature:
gridQuickFilterValuesSelector: (apiRef: GridApiRef) => any[] | undefined
// or
gridQuickFilterValuesSelector: (state: GridState, instanceId?: number) => any[] | undefined
Example
gridQuickFilterValuesSelector(apiRef)
// or
gridQuickFilterValuesSelector(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) => GridRowEntry<GridValidRowModel>[]
// or
gridPaginatedVisibleSortedGridRowEntriesSelector: (state: GridState, instanceId?: number) => GridRowEntry<GridValidRowModel>[]
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:
gridPaginationMetaSelector: (apiRef: GridApiRef) => GridPaginationMeta
// or
gridPaginationMetaSelector: (state: GridState, instanceId?: number) => GridPaginationMeta
Example
gridPaginationMetaSelector(apiRef)
// or
gridPaginationMetaSelector(state, apiRef.current.instanceId)
Signature:
gridPaginationModelSelector: (apiRef: GridApiRef) => GridPaginationModel
// or
gridPaginationModelSelector: (state: GridState, instanceId?: number) => GridPaginationModel
Example
gridPaginationModelSelector(apiRef)
// or
gridPaginationModelSelector(state, apiRef.current.instanceId)
Signature:
gridPaginationRowCountSelector: (apiRef: GridApiRef) => number
// or
gridPaginationRowCountSelector: (state: GridState, instanceId?: number) => number
Example
gridPaginationRowCountSelector(apiRef)
// or
gridPaginationRowCountSelector(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) => GridRowEntry<GridValidRowModel>[]
// or
gridSortedRowEntriesSelector: (state: GridState, instanceId?: number) => GridRowEntry<GridValidRowModel>[]
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)

Virtualization

Signature:
gridVirtualizationColumnEnabledSelector: (apiRef: GridApiRef) => boolean
// or
gridVirtualizationColumnEnabledSelector: (state: GridState, instanceId?: number) => boolean
Example
gridVirtualizationColumnEnabledSelector(apiRef)
// or
gridVirtualizationColumnEnabledSelector(state, apiRef.current.instanceId)
Signature:
gridVirtualizationEnabledSelector: (apiRef: GridApiRef) => boolean
// or
gridVirtualizationEnabledSelector: (state: GridState, instanceId?: number) => boolean
Example
gridVirtualizationEnabledSelector(apiRef)
// or
gridVirtualizationEnabledSelector(state, apiRef.current.instanceId)
Signature:
gridVirtualizationSelector: (state: GridState) => GridVirtualizationState
Example
const virtualization = gridVirtualizationSelector(apiRef.current.state);

Save and restore the state

The current state of the Data 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 Data Grid calls 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.

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 second Data Grid with the current state of the first Grid.

Save and restore the state from external storage

You can use apiRef.current.exportState() to save a snapshot of the state to an external storage (for example using local storage or redux). This way the state can be persisted on refresh or navigating to another page.

In the following demo, the state is saved to localStorage and restored when the page is refreshed. This is done by listening on the beforeunload event. When the component is unmounted, the useLayoutEffect cleanup function is being used instead.

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 Data 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'],
});

API