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

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

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

Press Enter to start editing

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);

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={{ height: 400, mt: 1 }}>
  <DataGridPro apiRef={apiRef} pagination pageSize={10} {...data} />
</Box>

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

Press Enter to start editing

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);

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

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

Press Enter to start editing

Catalog of selectors

Some selectors are yet to be documented.

Aggregation

gridAggregationLookupSelector

Get the aggregation results as a lookup.

Signature:

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

Example

gridAggregationLookupSelector(apiRef)
// or
gridAggregationLookupSelector(state, apiRef.current.instanceId)

gridAggregationModelSelector

Get the aggregation model, containing the aggregation function of each column. If a column is not in the model, it is not aggregated.

Signature:

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

Example

gridAggregationModelSelector(apiRef)
// or
gridAggregationModelSelector(state, apiRef.current.instanceId)

Columns

gridColumnDefinitionsSelector

Get the columns as an array.

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)

gridColumnFieldsSelector

Get the field of each column.

Signature:

gridColumnFieldsSelector: (apiRef: GridApiRef) => string[]
// or
gridColumnFieldsSelector: (state: GridState, instanceId?: number) => string[]

Example

gridColumnFieldsSelector(apiRef)
// or
gridColumnFieldsSelector(state, apiRef.current.instanceId)

gridColumnLookupSelector

Get the columns as a lookup (an object containing the field for keys and the definition for values).

Signature:

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

Example

gridColumnLookupSelector(apiRef)
// or
gridColumnLookupSelector(state, apiRef.current.instanceId)

gridFilterableColumnDefinitionsSelector

Get the filterable columns as an array.

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)

gridFilterableColumnLookupSelector

Get the filterable columns as a lookup (an object containing the field for keys and the definition for values).

Signature:

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

Example

gridFilterableColumnLookupSelector(apiRef)
// or
gridFilterableColumnLookupSelector(state, apiRef.current.instanceId)

Visible Columns

gridColumnPositionsSelector

Get the left position in pixel of each visible columns relative to the left of the first column.

Signature:

gridColumnPositionsSelector: (apiRef: GridApiRef) => number[]
// or
gridColumnPositionsSelector: (state: GridState, instanceId?: number) => number[]

Example

gridColumnPositionsSelector(apiRef)
// or
gridColumnPositionsSelector(state, apiRef.current.instanceId)

gridColumnVisibilityModelSelector

Get the column visibility model, containing the visibility status of each column. If a column is not registered in the model, it is visible.

Signature:

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

Example

gridColumnVisibilityModelSelector(apiRef)
// or
gridColumnVisibilityModelSelector(state, apiRef.current.instanceId)

gridColumnsTotalWidthSelector

Get the summed width of all the visible columns.

Signature:

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

Example

gridColumnsTotalWidthSelector(apiRef)
// or
gridColumnsTotalWidthSelector(state, apiRef.current.instanceId)

gridVisibleColumnDefinitionsSelector

Get the visible columns as a lookup (an object containing the field for keys and the definition for values).

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)

gridVisibleColumnFieldsSelector

Get the field of each visible column.

Signature:

gridVisibleColumnFieldsSelector: (apiRef: GridApiRef) => string[]
// or
gridVisibleColumnFieldsSelector: (state: GridState, instanceId?: number) => string[]

Example

gridVisibleColumnFieldsSelector(apiRef)
// or
gridVisibleColumnFieldsSelector(state, apiRef.current.instanceId)

Filtering

gridFilterModelSelector

Get the current filter model.

Signature:

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

Example

gridFilterModelSelector(apiRef)
// or
gridFilterModelSelector(state, apiRef.current.instanceId)

gridFilterStateSelector

Signature:

gridFilterStateSelector: (state: GridState) => GridFilterState

Example

const filterState = gridFilterStateSelector(apiRef.current.state);

gridFilteredSortedRowEntriesSelector

Get the id and the model of the rows accessible after the filtering process. Contains the collapsed children.

Signature:

gridFilteredSortedRowEntriesSelector: (apiRef: GridApiRef) => { id: GridRowId; model: GridValidRowModel }[]
// or
gridFilteredSortedRowEntriesSelector: (state: GridState, instanceId?: number) => { id: GridRowId; model: GridValidRowModel }[]

Example

gridFilteredSortedRowEntriesSelector(apiRef)
// or
gridFilteredSortedRowEntriesSelector(state, apiRef.current.instanceId)

gridFilteredSortedRowIdsSelector

Get the id of the rows accessible after the filtering process. Contains the collapsed children.

Signature:

gridFilteredSortedRowIdsSelector: (apiRef: GridApiRef) => GridRowId[]
// or
gridFilteredSortedRowIdsSelector: (state: GridState, instanceId?: number) => GridRowId[]

Example

gridFilteredSortedRowIdsSelector(apiRef)
// or
gridFilteredSortedRowIdsSelector(state, apiRef.current.instanceId)

gridQuickFilterValuesSelector

Get the current quick filter values.

Signature:

gridQuickFilterValuesSelector: (apiRef: GridApiRef) => any[] | undefined
// or
gridQuickFilterValuesSelector: (state: GridState, instanceId?: number) => any[] | undefined

Example

gridQuickFilterValuesSelector(apiRef)
// or
gridQuickFilterValuesSelector(state, apiRef.current.instanceId)

gridVisibleRowCountSelector

Get the amount of rows accessible after the filtering process.

Signature:

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

Example

gridVisibleRowCountSelector(apiRef)
// or
gridVisibleRowCountSelector(state, apiRef.current.instanceId)

gridVisibleSortedRowEntriesSelector

Get the id and the model of the rows accessible after the filtering process. Does not contain the collapsed children.

Signature:

gridVisibleSortedRowEntriesSelector: (apiRef: GridApiRef) => { id: GridRowId; model: GridValidRowModel }[]
// or
gridVisibleSortedRowEntriesSelector: (state: GridState, instanceId?: number) => { id: GridRowId; model: GridValidRowModel }[]

Example

gridVisibleSortedRowEntriesSelector(apiRef)
// or
gridVisibleSortedRowEntriesSelector(state, apiRef.current.instanceId)

gridVisibleSortedRowIdsSelector

Get the id of the rows accessible after the filtering process. Does not contain the collapsed children.

Signature:

gridVisibleSortedRowIdsSelector: (apiRef: GridApiRef) => GridRowId[]
// or
gridVisibleSortedRowIdsSelector: (state: GridState, instanceId?: number) => GridRowId[]

Example

gridVisibleSortedRowIdsSelector(apiRef)
// or
gridVisibleSortedRowIdsSelector(state, apiRef.current.instanceId)

gridVisibleSortedTopLevelRowEntriesSelector

Get the id and the model of the top level rows accessible after the filtering process.

Signature:

gridVisibleSortedTopLevelRowEntriesSelector: (apiRef: GridApiRef) => { id: GridRowId; model: GridValidRowModel }[]
// or
gridVisibleSortedTopLevelRowEntriesSelector: (state: GridState, instanceId?: number) => { id: GridRowId; model: GridValidRowModel }[]

Example

gridVisibleSortedTopLevelRowEntriesSelector(apiRef)
// or
gridVisibleSortedTopLevelRowEntriesSelector(state, apiRef.current.instanceId)

gridVisibleTopLevelRowCountSelector

Get the amount of top level rows accessible after the filtering process.

Signature:

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

Example

gridVisibleTopLevelRowCountSelector(apiRef)
// or
gridVisibleTopLevelRowCountSelector(state, apiRef.current.instanceId)

Pagination

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

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)

Sorting

gridSortModelSelector

Get the current sorting model.

Signature:

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

Example

gridSortModelSelector(apiRef)
// or
gridSortModelSelector(state, apiRef.current.instanceId)

gridSortedRowEntriesSelector

Get the id and the model of the rows after the sorting process.

Signature:

gridSortedRowEntriesSelector: (apiRef: GridApiRef) => { id: GridRowId; model: GridValidRowModel }[]
// or
gridSortedRowEntriesSelector: (state: GridState, instanceId?: number) => { id: GridRowId; model: GridValidRowModel }[]

Example

gridSortedRowEntriesSelector(apiRef)
// or
gridSortedRowEntriesSelector(state, apiRef.current.instanceId)

gridSortedRowIdsSelector

Get the id of the rows after the sorting process.

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.

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

Data grid - State

Initialize the state

Access the state

Direct selector access

With useGridSelector

Catalog of selectors

Aggregation

gridAggregationLookupSelector

Signature:

Example

gridAggregationModelSelector

Signature:

Example

Columns

gridColumnDefinitionsSelector

Signature:

Example

gridColumnFieldsSelector

Signature:

Example

gridColumnLookupSelector

Signature:

Example

gridFilterableColumnDefinitionsSelector

Signature:

Example

gridFilterableColumnLookupSelector

Signature:

Example

Visible Columns

gridColumnPositionsSelector

Signature:

Example

gridColumnVisibilityModelSelector

Signature:

Example

gridColumnsTotalWidthSelector

Signature:

Example

gridVisibleColumnDefinitionsSelector

Signature:

Example

gridVisibleColumnFieldsSelector

Signature:

Example

Filtering

gridFilterModelSelector

Signature:

Example

gridFilterStateSelector

Signature:

Example

gridFilteredSortedRowEntriesSelector

Signature:

Example

gridFilteredSortedRowIdsSelector

Signature:

Example

gridQuickFilterValuesSelector

Signature:

Example

gridVisibleRowCountSelector

Signature:

Example

gridVisibleSortedRowEntriesSelector

Signature:

Example

gridVisibleSortedRowIdsSelector

Signature:

Example

gridVisibleSortedTopLevelRowEntriesSelector

Signature:

Example

gridVisibleTopLevelRowCountSelector

Signature:

Example

Pagination

gridPageCountSelector

Signature:

Example

With `useGridSelector`

Restore the state with `initialState`

Restore the state with `apiRef`