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"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

Property Type Description
aggFunc string | IAggFunc | null The aggregation function applied
flex number | null Column’s flex if flex is set
hide boolean | null True if the column is hidden
pinned ‘left’ | ‘right’ | boolean | null Set if column is pinned
pivot boolean | null True if pivot active
pivotIndex number | null The order of the pivot, if pivoting by many columns
rowGroup boolean | null True if row group active
rowGroupIndex number | null The order of the row group, if grouping by many columns
sort ‘asc’ | ‘desc’ | null Sort applied to the column
sortIndex number | null The order of the sort, if sorting by many columns
width number Width of the column in pixels

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:

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

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

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.

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.