Column Definitions contain both stateful and non-stateful attributes. Stateful attributes can have their values changed by the grid (eg Column sort can be changed by the user clicking on the column header). Non-stateful attributes do not change from what is set in the Column Definition (eg once the Header Name is set as part of a Column Definition, it typically does not change).
The full list of stateful attributes of Columns are as follows:
- Row Group
- Column Order
This section details how such state items can be changed.
Save and Apply State
There are two API methods provided for getting and setting Column State.
columnApi.getColumnState() gets the current column state and
columnApi.applyColumnState() sets the column state.
The example below demonstrates saving and restoring column state. Try the following:
- Click 'Save State' to save the Column State.
- Change some column state e.g. resize columns, move columns around, apply column sorting or row grouping etc.
- Click 'Restore State' and the columns state is set back to where it was when you clicked 'Save State'.
- Click 'Reset State' and the state will go back to what was defined in the Column Definitions.
Column State Interface
The structure of a Column State is as follows:
It is possible to focus on particular columns and / or particular attributes when getting and / or applying Column State. This allows fine grained control over the Column State, e.g. setting what Columns are Pinned, without impacting any other state attribute.
Applying Partial State
When applying column state, in cases where some state attributes or columns are missing from the Column State, the following rules apply:
If a Column State is missing attributes, or attributes are provided as
undefined, then those missing / undefined attributes are not updated. For example if a Column has a Column State with just
pinned, then Pinned is applied to that Column but other attributes, such as Sort, are left intact.
When state is applied and there are additional Columns in the grid that do not appear in the provided
state, then the
params.defaultStateis applied to those additional Columns.
params.defaultStateis not provided, then any additional Columns in the grid will not be updated.
Combining these rules together leaves for flexible fine grained state control. Take the following code snippets as examples:
The example below shows some fine grained access to Column State.
Saving Partial State
Using the techniques above, it is possible to save and restore a subset of the parameters in the state. The example below demonstrates this by selectively saving and restoring a) sort state and b) column visibility and order state.
Note than when saving and restoring Sort state, other state attributes (width, row group, column order etc) are not impacted.
Likewise when saving and restoring visibility and order, only visibility and order will be impacted when re-applying the state.
There are a few items to note on specific state attributes. They are as follows:
Null vs Undefined
For all state attributes,
undefined means "do not apply this attribute"
null means "clear this attribute".
For example setting
sort=null will clear sort on a column whereas setting
sort=undefined will leave whatever sort, if any, that is currently present.
The only exception is with regards to Column width. For width, both
null will skip the attribute. This is because Width is mandatory - there
is no such things as a Column with no width.
Width and Flex
When Flex is active on a Column, the grid ignores the
width attribute when setting the Width.
getColumnState() is called, both
flex are returned.
applyColumnState() is called, if
flex is present then
If you want to restore a Column's width to the exact same pixel width as specified in the Column State,
flex=null for that Column's state to turn Flex off.
Row Group and Pivot
There are two attributes representing both Row Group and Pivot. First using the boolean attributes
pivot and then secondly using the index attributes
getColumnState() is called, all of
pivotIndex are returned. When
applyColumnState() is called, preference is given to the index variants. For example
rowGroupIndex are present,
Column Events will get raised when applying Column State as these events would
normally get raised. For example
columnPinned event will get raised if applying
the state results in a column getting pinned or unpinned.
The example below demonstrates events getting raised based on Column State changes. The example logs event information to the console, so best open the example in a new tab and observe the dev console.
To suppress events raised when invoking
set the grid property
The example below is similar to the example above, except no events are raised when the state is changed via the buttons.
Column Group State
Column Group State is concerned with the state of Column Groups. There is only one state attribute for Column Groups, which is whether the group is open or closed.
To get the state of Column Groups use the API method
set the Column Group state use the API method
The example below demonstrates getting and setting Column Group State. Note the following:
- Clicking 'Save State' will save the opened / closed state of column groups.
- Clicking 'Restore State' will restore the previously saved state.
- Clicking 'Reset State' will reset the column state to match the Column Definitions, i.e. all Column Groups will be closed.