Column State

Column definitions have both stateful and non-stateful attributes. Stateful attributes can have
their values changed by the grid (for example, 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
(for example, once the header name is set as part of a column definition, it typically does not change).

The DOM also has stateful vs non-stateful attributes. For example, consider a DOM element and
setting element.style.width="100px" will indefinitely set width to 100 pixels,
the browser will not change this value. However setting element.scrollTop=200 will
set the scroll position, but the browser can change the scroll position further following user
interaction, thus scroll position is stateful as the browser can change the state.

The full list of stateful attributes of columns are represented by the columnState interface:

columnState Properties

Column State Retrieval

Use columnState to retrieve columns current state. In this example columnState is an input to the callback,
meaning the callback runs each time the state changes. Note how reordering or resizing the columns changes the current
state, which is displayed below the grid.

Save and Restore Column State

Note that when columnState is set, the order of the columns is set to match the order of the newly provided Column
State, this is usually the desired and expected behaviour when we want to restore a full state.
If the desired behaviour is that column’s order should be maintained,
see Maintain the Column Order below.

The example below demonstrates saving and restoring Column State. Try the following:

• Click ‘Save State’ to save the Column State.
• Change some column state. For example, resize columns, move columns around or apply column sorting.
• Click ‘Restore State’ and the column’s 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.

Apply Partial Column State

While setting columnState, it is possible to provide only partial state for each column, the properties that are not
set will keep their value, like the example below that only add the 'hide': True, keeping all other states the same.

new_state = [
    {"colId": "athlete"},
    {"colId": "sport"},
    {"colId": "country", 'hide': True},
    {"colId": "age", 'hide': True},
    {"colId": "year"},
    {"colId": "total"},
]

Note the following:
- The full column set must be provided, even if there is no state change.
- Like for a full update, the order of the columns of the new state will be applied.
See Maintain the Column Order
below to keep the current order of the columns.

Here is an example showing a partial state update, hiding the columns Country and Age.
Note that, if you modify the column order, when applying the new state, its column order is also applied, removing your
custom order.

Maintain the Column Order

When we set a new columnState, the column order of the new Column State will also be applied. If the current column
order must be maintained and only few properties must be updated, the easiest way is to retrieve the current state and
modify the properties that need to be changed, then apply this modified state.

Another way to maintain the column order, particularly suited for saved state and more complex state, is to provide the
new state with the full set of columns, then re-order this new state to match the current columns order and apply this
new re-ordered state. See the
examples Save and Restore Partial Column State
and Update Column State - More examples
below.

Here is an example showing how to maintain the column order when updating the state.
Like the previous example, the columns Country and Age are hidden, but this time, the column order is
maintained.

Save and Restore Partial Column State

The following example shows how to save a partial Column State, and how to restore only the saved properties, keeping
all other properties parameters as is. You can also choose to restore the column order or the keep the current order.

Update Column State - More examples

The code below shows more examples updating the Column State.

• The first row of buttons modifies the sort and sortIndex properties.
  • The first button adds a sort to Athlete. If sorts are already applied on other columns, the sort on
    Athlete will be added after the existing sorts.
  • The second button clears the existing sorts and applies a multi-sort on Country then on Sport
  • The third button clears all the sorts.
• The button ‘New Order’ modifies only the column order.
• The slider changes the width of all numeric columns.
• The button ‘Complex State’ shows a more complex state update, setting the width, pinned, sort and sortIndex
  state of all columns.
• The button ‘Reset State’ triggers the resetColumnState() which will reapply the current ‘columnDefs’ of the grid.

Note that those examples maintain the column order, except, obviously the ‘New order’ button, and the ‘Complex State’
that pins Athlete on the left and Total on the right, but the order of other columns are maintained.

Width and Flex

When flex is active on a Column, the grid ignores the width attribute when setting the width.

When getting columnState, both width and flex are returned. When setting columnState, if flex is present
then width is ignored.

If you want to restore a Column’s width to the exact same pixel width as specified in the Column State,
set flex=None for that Column’s state to turn Flex off.