Column Definitions

Each column in the grid is defined using a column definition. Columns are positioned in the grid according to the order the ColDef's are specified in the grid options. The following example shows a simple grid with 3 columns defined:

var gridOptions = { // define 3 columns columnDefs: [ {headerName: 'Athlete', field: 'athlete'}, {headerName: 'Sport', field: 'sport'}, {headerName: 'Age', field: 'age'} ], // other grid options here... }

See Column Properties for a list of all properties that can be applied to a column.

If you want the columns to be grouped, then you include them as groups like the following:

var gridOptions = { columnDefs: [ // put the three columns into a group {headerName: 'Group A', children: [ {headerName: 'Athlete', field: 'athlete'}, {headerName: 'Sport', field: 'sport'}, {headerName: 'Age', field: 'age'} ] } ], // other grid options here... }

Groups are explained in more detail in the section Column Groups.

Custom Column Types

In addition to the above, the grid provides additional ways to help simplify and avoid duplication of column definitions. This is done through the following:

  • defaultColDef: contains column properties all columns will inherit.
  • defaultColGroupDef: contains column group properties all column groups will inherit.
  • columnTypes: specific column types containing properties that column definitions can inherit.
Default columns and column types can specify any of the column properties available on a column.

The following code snippet shows these three properties configures:

var gridOptions = { rowData: myRowData, // define columns columnDefs: [ // uses the default column properties {headerName: 'Col A', field: 'a'}, // overrides the default with a number filter {headerName: 'Col B', field: 'b', filter: 'agNumberColumnFilter'}, // overrides the default using a column type {headerName: 'Col C', field: 'c', type: 'nonEditableColumn'}, // overrides the default using a multiple column types {headerName: 'Col D', field: 'd', type: ['dateColumn', 'nonEditableColumn']} ], // a default column definition with properties that get applied to every column defaultColDef: { // set every column width width: 100, // make every column editable editable: true, // make every column use 'text' filter by default filter: 'agTextColumnFilter' }, // if we had column groups, we could provide default group items here defaultColGroupDef: {} // define a column type (you can define as many as you like) columnTypes: { "nonEditableColumn": {editable: false}, "dateColumn": {filter: 'agDateColumnFilter', filterParams: {comparator: myDateComparator}, suppressMenu:true} } } // other grid options here... }

When the grid creates a column it starts with the default column, then adds in anything from the column type, then finally adds in items from the column definition.

For example, the following is an outline of the steps used when creating 'Col C' shown above:

// Step 1: the grid starts with an empty merged definition {} // Step 2: default column properties are merged in {width: 100, editable: true, filter: 'agTextColumnFilter'} // Step 3: column type properties are merged in (using the 'type' property) {width: 100, editable: false, filter: 'agNumberColumnFilter'} // Step 4: finally column definition properties are merged in {headerName: 'Col C', field: 'c', width: 100, editable: false, filter: 'agNumberColumnFilter'}

The following examples demonstrates this configuration.

Provided Column Types

Numeric Columns

The grid provides a handy shortcut for formatting numeric columns. Setting the column definition type to numericColumn aligns the column header and contents to the right, which makes the scanning of the data easier for the user.

var gridOptions = { columnDefs: [ { headerName: "Column A", field: "a" }, { headerName: "Column B", field: "b", type: "numericColumn" } ] }

Updating Column Definitions

After the grid has been initialised it may be necessary to update the column definition. It is important to understand that when a column is created it is assigned a copy of the column definition defined in the GridOptions. For this reason it is necessary to obtain the column definition directly from the column.

The following example shows how to update a column header name after the grid has been initialised. As we want to update the header name immediately we explicitly invoke refreshHeader() via the Grid API.

// get a reference to the column var col = gridOptions.columnApi.getColumn("colId"); // obtain the column definition from the column var colDef = col.getColDef(); // update the header name colDef.headerName = "New Header"; // the column is now updated. to reflect the header change, get the grid refresh the header gridOptions.api.refreshHeader();

Saving and Restoring Column State

It is possible to save and subsequently restore the column state via the Column API. Examples of state include column visibility, width, row groups and values.

This is primarily achieved using the following methods:

  • columnApi.getColumnState(): Returns the state of a particular column.
  • columnApi.setColumnState(state): To set the state of a particular column.

The column state used by the above methods is an array of objects that mimic the colDef's which can be converted to and from JSON. An example is shown below:

[ {colId: "athlete", aggFunc: "sum", hide: false, rowGroupIndex: 0, width: 150, pinned: null}, {colId: "age", aggFunc: null, hide: true, rowGroupIndex: null, width: 90, pinned: 'left'} ]

The values have the following meaning:

  • colId: The ID of the column. See column definitions for explanation of column ID
  • aggFunc: If this column is a value column, this field specifies the aggregation function. If the column is not a value column, this field is null.
  • hide: True if the column is hidden, otherwise false.
  • rowGroupIndex: The index of the row group. If the column is not grouped, this field is null. If multiple columns are used to group, this index provides the order of the grouping.
  • width: The width of the column. If the column was resized, this reflects the new value.
  • pinned: The pinned state of the column. Can be either 'left' or 'right'
To suppress events raised when invoking columnApi.setColumnState(state), and also columnApi.resetColumnState(), use: gridOptions.suppressSetColumnStateEvents = true.

Column API Example

The example below shows using the grid's Column API.

This example also includes Column Groups which are covered in the next section, in order to demonstrate saving and restoring the expanded state.

Column Changes

It is possible to add and remove columns after the grid is created. This is done by either calling api.setColumnDefs() or setting the bound property columnDefs.

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 (columns that remain will keep their state including position, filter and sort).

Comparison of column definitions is done on 1) object reference comparison and 2) column ID eg colDef.colId. If either the object reference matches, or the column ID matches, then the grid treats the columns as the same column. For example if the grid has a column with ID 'country' and the user sets new columns, one of which also has ID of 'country', then the old country column is kept in place of the new one keeping it's internal state such as width, position, sort and filter.

The example below demonstrates changing columns. Select the checkboxes for the columns to display and hit Apply. Note the following:

  • Column Width: If you change the width of a column (eg Year) and then add or remove other columns (eg remove Age) then the width of Year remains unchanged.
  • Column Sort: If you sort the data by a column (eg Year) and then add or remove other columns (eg remove Age) then the sort remains unchanged. Conversely if you remove a column with a sort (eg remove Year while also sorting by Year) then the sort order is removed.
  • Column Filter: If you filter the data by a column (eg Year) and then add or remove other columns (eg remove Year) then the filter remains unchanged. Conversely if you remove a column with a filter (eg remove Year while also filtering on Year) then the filter is removed.
  • Row Group & Pivot: If you row group or pivot the data by a column (eg Year) and then add or remove other columns (eg remove Age) then the row group or pivot remains unchanged. Conversely if you remove a column with a row group or pivot (eg remove Year while also row grouping or pivoting on Year) then the row group or pivot is removed.
  • The Columns Tool Panel and Filters Tool Panel updates with the new columns. The order of columns in both tool panels will always match the order of the columns supplied in the column definitions. To observe this, hit the Reverse button which does same as Apply but reverses the order of the columns first. This will result in the columns appearing in the tool panels in reverse order.

Group Changes

Similar to adding and removing columns, you can also add and remove column groups. If the column definitions passed in have column groups, then the columns will grouped to the new configuration.

In the example below, note the following:

  • Select No Groups to show all columns without any grouping.
  • Select Participant in Group to show all participant columns only in a group.
  • Select Medals in Group to show all medal columns only in a group.
  • Select Participant and Medals in Group to show participant and medal columns in groups.
  • As groups are added and removed, note that the state of the individual columns is preserved. To observe this, try moving, resizing, sorting, filtering etc and then add and remove groups, all the changed state will be preserved.