JavaScript Data GridUpdating Column Definitions

The section Column Definitions explained how to configure columns. It is possible to change the configuration of the Columns after they are initially set. This section goes through how to update Column Definitions.

Adding & Removing Columns

It is possible to add and remove columns by updating the list of Column Definitions provided to the grid.

When new columns are set, the grid will compare with current columns and work out which columns are old (to be removed), new (new columns created) or kept.

The example below demonstrates adding and removing columns from a grid. Note the following:

• Selecting the buttons to toggle between including or excluding the medal columns.

In the example above, note that any state applied to any column (e.g. sort, filter, width) will be kept if the column still exists after the new definitions are applied. For example try the following:

• Resize Country column. Note changing columns doesn't impact its width.
• Sort Country column. Note changing columns doesn't impact its sort.

Updating Column Definitions

All properties of a column definition can be updated. For example if you want to change the Header Name of a column, you update the headerName on the Column Definition and then set the list of Column Definitions into the grid again.

It is not possible to update the Column Definition of just one column in isolation. Only a new set of Column Definitions can be applied.

The example below demonstrates updating column definitions to change how columns are configured. Note the following:

• All Columns are provided with just the field attribute set on the Column Definition.
• 'Set Header Names' and 'Remove Header Names' sets and then subsequently removes the headerName attribute on all Columns.
• 'Set Value Formatter' and 'Remove Value Formatter' sets and then subsequently removes the valueFormatter attribute on all Columns.
• Note that any resizing, sorting etc of the Columns is kept intact between updates to the Column Definitions.

Changing Column State

Parts of the Column Definitions represent Column State. Column State is stateful information and represents changing values of the grid.

All stateful attributes of Column Definitions are as follows:

The Initial Attribute will be used only when the Column is Created. The Stateful Attribute will be used when the Column is Created or Updated.

columnDefs: [
    // using initial values, get applied when Column is created
    { field: 'country', initialWidth: 200, initialPinned: 'left' },
    // using stateful values, get applied when Column is created or updated
    { field: 'country', width: 200, pinned: 'left' }
],

The example below shows Column Definitions using initial attributes. Note the following:

• The initialWidth, initialSort and initialPinned are applied only when the columns are created.
• If you update the width, sort or pinned of a column by interacting with the grid's UI and then hit 'Set Columns with Initials', the columns state will not change.
• Removing the columns first and then setting them again will use the initial values again.

The following example shows Column Definitions using stateful attributes. Note the following:

• The width, sort and pinned stateful attributes are applied whenever Column Definitions are set.
• If you update the width, sort or pinned of a column by interacting with the grid's UI and then hit 'Set Columns with State', the columns state will change and the changes made via the UI will be lost.
• Note the defaultColDef is used to remove state. For example sort=null is set so that any sorting the user might have done on another column is cleared down. Otherwise, the grid would see the sort attribute as undefined which means the state should not be changed.

null vs undefined

When a stateful attribute is set to undefined the grid ignores the attribute.

When a stateful attribute is set to null the grid clears the attribute.

For example the setting pinned=null will clear pinning on a column whereas pinned=undefined means the grid will leave pinned state as it is for that column.

If you don't want to upset any column state (e.g. if you don't want to undo any change the user has made to the columns via the grid's UI, such as applying a sort by clicking on a header, or dragging a column's width) then do not set the state attributes as by default they will be undefined.

Matching Columns

When a new Column Definition is passed to the grid, the grid needs to work out if it's an update of a Column or a new Column.

Most of the time the field attribute will match the Column. However field is both an optional and non-unique attribute, e.g. a valueGetter could be used instead of field, or two columns could share the same field.

Given the field is not a unique identifier, the grid uses the following rules to match columns:

1. If colId provided, match using colId
2. Otherwise if field provided, match using field
3. Otherwise match using object equality on Column Definition instance

In other words, to have the grid correctly match Columns make sure each Column has either a field or colId.

The example below demonstrates the different matching strategies. Note the following:

• All columns, with the exception of Country, are matched correctly. This means any column width, sort etc will be kept between changes to the columns. Country will have its state reset, as it will be treated as a new column each time.
• Athlete column is matched by object equality as the same column definition instance is provided to the grid each time.
• Age column is matched by colId. The colId is needed as the column has no field attribute.
• All other columns except Country are matched using the field attribute.
• Country column is not matched as it's a different object instance and has no colId or field attributes.

Maintain Column Order

When providing new Column Definitions to the grid, the order in which they are provided is the order in which the columns are displayed. This can mean that when overwriting columns with a new set of columns, any columns moved by the user will have their position reset.

If you instead want to prioritise the order of the columns as they appear in the grid, set the grid property maintainColumnOrder to true.

const gridOptions = {
    maintainColumnOrder: true,

    // other grid options ...
}

In the example below, note the following:

• The grid is configured with maintainColumnOrder=true.
• The columns can be reordered by dragging them.
• Two buttons exist, Column Set A and Column Set B. Clicking these buttons will swap between two column definitions, each with a different order of columns.
• Swapping between the column sets does not reset or change the column order, instead preserving the grid state.
• A Clear button also exists, when clicking this the columns are removed, and subsequently applying a column set applies their order.

If there are new Columns added, then these new Columns will always be added at the end.

In order for the Column Order to be maintained, the grid needs to match the Columns. This can be done by ensuring each Column has a unique field or colId defined. Any Columns that can't be matched will be treated as new Columns and placed at the end.

Column Events

Column Events will get raised when setting new Column Definitions that update the current Columns. 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 Definition changes. The example logs event information to the console, so best open the example in a new tab and observe the dev console.

Column Definition Retrieval

There will be times where you'll want to retrieve the current Column Definition in order to perhaps persist them, or perhaps retrieve, alter and then re-apply the modified columns.

The current column definitions can be retrieved with getColumnDefs:

api.getColumnDefs();

Column Groups

Column Groups can be updated in the same way as Columns, you just update the Column Group Definition. For expandable groups, to have open / closed state to be maintained, you need to assign groupId in the Column Group Definition.

const gridOptions = {
    columnDefs: [
        {
            headerName: 'Group A',
            groupId: 'groupA',
            children: [
                { field: 'name' },
                { field: 'age', columnGroupShow: 'open' }
            ]
        }
    ],

    // other grid options ...
}

In the example below, note the following:

1. Clicking the top buttons alternates the columns from two sets of definitions.
2. Column Group A - groupId is provided, so expand / collapse is preserved. The Header Name also changes.
3. Column Group B - groupId is NOT provided, so expand / collapse is lost, group always closes when updates happen.
4. Column Group C - groupId is provided, so expand / collapse is preserved. Child columns are changed.