Updating Column Definitions

The Column Definitions page demonstrated how to set the
initial column definitions for a grid. Here, we look at how to update column definitions after they’ve been initially
set.

Add and Remove Columns

To add or remove columns, use a callback to update the grid’s column definitions by using the grid’s columnDefs
property as an output.

In this example, you can use the button to toggle between including and excluding the columns that show the numbers for
each medal type. Note how any state applied to a column (for example, sort, filter, and width) is retained if the column
still exists after the new definitions are applied.

Update Properties

All properties of a column definition can be updated. For example, if you want to change the header name of a column,
update the headerName on its column definition within a callback and use the grid’s columnDefs as an output on the
callback.

The example below demonstrates updating column definitions to change how columns are configured.

Note the following:

• There are two sets of columnDefs defined in the example, the second set including a headerName for each column
  (transforming the headers with leet formatting). Using the first button, you can
  toggle between using each one on the grid.
• The second button sets/removes the valueFormatter for each column by modifying the current columnDefs in the
  callback, thus the header formatting is not modified.
• If the valueFormatter is set with the second button, it will be removed by applying one of those sets, as those sets
  don’t use this parameter.
• Any resizing or sorting of the columns is retained when the headers update.

Partial Update

Dash 2.9 introduced Partial Property Updates using the Patch
class.

This feature allows to update only a part of a property of a component. Thus, it is possible to use a Patch to make a
partial update on the columnDefs.

Here is an example using the Patch class to update only the header of the first column.

Update Stateful Properties

Some column properties are stateful properties, meaning their values can change while the user is interacting with the grid.
Those properties are handled by the grid property columnState. See
the Column State page for more information.

They can be defined with columnDefs using either their Initial Attribute or their Stateful Attribute:

• Initial Attributes: used only when the column is Created.
• Stateful Attributes: used when the column is Created or Updated

The stateful properties of columnDefs and their corresponding initial properties are listed below:

Here is an example showing the difference between initial and stateful column definition properties.

Note the following:

• The column Year uses initialSort and initialWidth. If the width or the sort order are modified, when
  re-applying columnDefs, its initial values are not restored.
• The column Athlete uses pinned and width. If the width is modified or the column is unpinned or pinned to the
  right, when re-applying columnDefs, its initial values are restored.
• When the columns are removed and re-defined with columnDefs, the properties of both columns are restored.

If only stateful properties should be updated, consider to use columnState instead of columnDefs.
(see Column State page)

Maintain Column Order

When Column Definitions are provided to the grid, the order of the columns inside the grid is set to match the order of
the newly provided Column Definitions. This means every time columns are set, the order is guaranteed to match the order
of the Column Definitions. This is usually the desired and expected behaviour.

You may wish for the order of the columns to not match the Column Definitions. For example suppose the user has
rearranged columns to their desired order, and then the application updates the Column Definitions (for example, changes the
Cell Renderer used), then it would be undesirable to reset the column order, as the user’s arranged order would be lost.

If the desired behaviour is that column’s order should be maintained, set the grid property :

dashGridOptions = {"maintainColumnOrder": True}

Here is an example showing the difference between maintaining the column order or not while setting columnDefs.

Note the following:

• The order of the two sets of columnDefs is different, and the second set uses headerName (transforming the headers
  with leet formatting)
• If maintainColumnOrder is disabled, switching the columnDefs will also apply the corresponding column order,
  removing the current order including if the user set a custom order.
• If maintainColumnOrder is enabled, switching the columnDefs will have no effect on the column order, the
  current order will be kept, which is useful if the user set a custom order.

If there are new columns added (for example, the new set of columnDefs has additional columns to those currently present),
then these new columns will always be added at the end.

Update Column Groups

Column groups can be updated in the same way as columns, by updating the column group definition.

Here is an example switching between two columnDefs sets using column groups.
These two sets are the same except that the first has the additional column group property 'openByDefault': True for
both groups which expands the groups when setting columnDefs

For expandable groups, to maintain the open/closed state while switching columnDefs, the column group
property groupId have to be assigned in the column group definition.

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

The following example shows this behavior using groupId.

• The columns Group A and Group C assign the groupId, the open/closed state is maintain while switching
  the columnDefs
• The column Group B doesn’t have a groupId set, thus, the group closes (default state) when the columnDefs is
  modified.
• Moreover, the headerName of Group A and the children of Group C are different between the two columnDefs sets.