Angular Data GridGrid State

This section covers saving and restoring the grid state, such as the filter model, selected rows, etc.

Saving and Restoring State Copy Link

The following buttons log saving and restoring state to the developer console.

The initial state is provided via the grid option initialState. It is only read once when the grid is created.

<ag-grid-angular
    [initialState]="initialState"
    /* other grid options ... */ />

this.initialState = {
    filter: {
        filterModel: {
            year: {
                filterType: 'set',
                values: ['2012'],
            }
        }
    },
    columnVisibility: {
        hiddenColIds: ['athlete'],
    },
    rowGroup: {
        groupColIds: ['athlete'],
    }
};

The current grid state can be retrieved by listening to the state updated event, which is fired with the latest state when it changes, or via api.getState().

The state is also passed in the Grid Pre-Destroyed Event, which can be used to get the state when the grid is destroyed.

State Contents Copy Link

The following is captured in the grid state:

• Aggregation Functions (column state)
• Opened Column Groups
• Column Order (column state)
• Pinned Columns (column state)
• Column Sizes (column state)
• Hidden Columns (column state)
• Column Filter Model
• Advanced Filter Model
• Focused Cell (Client-Side Row Model only)
• Current Page
• Pivot Mode and Columns (column state)
• Cell Selection
• Row Group Columns (column state)
• Expanded Row Groups
• Row Selection (retrievable for all row models, but can only be set for Client-Side Row Model and Server-Side Row Model)
• Pinned Rows
• Show Values As (column state)
• Side Bar
• Sort (column state)
• Calculated Columns added or modified by end users

All state properties are optional, so a property can be excluded if you do not want to restore it.

If applying some but not all of the column state properties, then initialState.partialColumnState must be set to true.

partialColumnState controls which column state sections you supply, not whether those sections may themselves be partial. Any section you include must match its documented shape.

The state also contains the grid version number. When applying state with older version numbers, any old state properties will be automatically migrated to the current format.

The grid state is designed to be serialisable, so any functions will be stripped out. For example, aggregation functions should be Registered as Custom Functions to work with state rather than being set as Directly Applied Functions.

Column and Group IDs Copy Link

Columns are identified in the state by their Column ID, and Column Groups by their groupId. These IDs are the only link between a saved state and the columns it describes, so they need to mean the same thing when the state is restored as they did when it was saved.

A column that provides neither colId nor field - one using only a valueGetter, for example - is given a positional ID instead. That ID follows the column's position in columnDefs rather than the column itself. If the definitions are reordered between saving and restoring, each column's state is applied to whichever column now occupies its old position.

This affects every column state section: sizes, sort, pinning, visibility, order and header names. A restored grid can silently show another column's width, or a header the user renamed on the wrong column.

Column groups behave the same way. A group definition without a groupId is given a generated ID which changes when the column definitions change, so the open / closed state of that group may not be restored.

Setting State Copy Link

The best way to restore grid state is via initial state as described above. However, it is also possible to restore state on an existing grid via api.setState(state).

It is possible to maintain the existing state for individual state contents by passing a second argument to setState that contains the top-level properties to ignore. E.g. api.setState(state, ['filter']) will maintain the existing filter state in the grid.

Converting Column State to Grid State Copy Link

State retrieved via the Column State APIs can be converted into grid state via the helper functions convertColumnState and convertColumnGroupState.

const state = {
    ...convertColumnState(columnState),
    ...convertColumnGroupState(columnGroupState)
};