Column API

The column api has methods for interacting with the columns of the grid. Using the column API, you have FULL control of how the columns are displayed. It has everything you need should you wish to build your own column management GUI (instead of what's provided in the tool panel).

gridOptions.columnApi.setColumnVisible('country', false);
It is important to NEVER update the details of a column directly (I'm talking about a Column, not a colDef). The grid should be left to update the attributes of the column. For example, if you want to change a columns width, do NOT change the width on the Column object, use the columnApi.setColumnWidth() method instead.

Below lists all the methods on the column API. At the bottom of this page there is an example. Note that when talking about columns, a Column Group refers to grouping of the columns in the header, a Row Group refers to grouping of the data when doing aggregation and grouping of rows.

Most of the methods below work with Columns, not colDef's. A Column is a grid internal representation for a column. When you pass a list of colDefs to the grid (via gridOptions.colDefs) the grid wraps each of these colDefs in a Column object. It is the Column object that contains the run-time information about the column. For example, if the column width changes, the actual column width is updated in the Column object, the colDef never has it's details changed. The fact that the colDef is never changed allows you to use the same colDef across many grids (probably only useful to a select few of you).

The grid API exposes functions that go beyond events and properties that you application can call. The grid needs to be initialised before the API can be accessed.

Javascript and AngularJS 1.x

Use columnApi placed inside gridOptions by the grid during initialisation.

React

Use the column API passed to you via the onGridReady callback of the React component. You can also use the columnApi placed inside gridOptions by the grid during initialisation.

Angular 2

Use columnApi placed inside gridOptions by the grid during initialisation. You can also use columnApi directly on the Angular grid component.

VueJS

Use columnApi placed inside gridOptions by the grid during initialisation. You can also use columnApi directly on the VueJS grid component.

Web Components

Use columnApi placed inside gridOptions by the grid during initialisation. You can also use columnApi directly on the DOM element.

Aurelia Components

Use columnApi placed inside gridOptions by the grid during initialisation. You can also use columnApi directly on the DOM element.

Column Keys

Some of the API methods take Column Key (named colKey). This means you can pass either a column object (that you receive from calling one of the other methods) or you pass in the Column ID. The Column ID is either the id you provide in the column definition, the field of the columns, or a generated ID if both are missing. The grid also ensures column ID's are unique.

List of Column API Functions

Function Description
sizeColumnsToFit(width) Don't use this! You are better off using gridApi.sizeColumnsToFit(), which first works out the available width, and then calls this method. Only use this method if you want to size to something other than the available width.
setColumnGroupOpened(group, newValue) Call this if you want to open or close a column group.
getColumnGroup(name) Returns the column group with the given name.
getDisplayNameForColumn(column) Returns the display name for a column. Useful if you are doing your own header rendering and want the grid to work out if headerValueGetter is used, or if you are doing your own column management GUI, to know what to show as the column name.
getDisplayNameForColumnGroup(columnGroup) Returns the display name for a column group (when grouping columns).
getColumn(colKey) Returns the column with the given 'key'. The key can either be the colId (a string) or the colDef (an object).
setColumnState(columnState) Sets the state of the columns. See example below. Returns false if one or more columns could not be found.
resetColumnState() Sets the state back to match the originally provided column definitions.
getColumnState() Gets the state of the columns. See example below.
isPinning() Returns true if pinning left or right, otherwise false.
isPinningLeft() Returns true if pinning left, otherwise false.
isPinningRight() Returns true if pinning right, otherwise false.
getDisplayedColAfter(col) Returns the column to the right of the provided column, taking into consideration open / closed column groups and visible columns. This is useful if you need to know what column is beside yours eg if implementing your own cell navigation.
getDisplayedColBefore(col) Same as getVisibleColAfter except gives col to the left.
setColumnVisible(colKey, visible) Sets the visibility of a column. Key can be the column id or Column object.
setColumnsVisible(colKeys, visible) Same as setColumnVisible, but provide a list of column keys.
setColumnPinned(colKey, pinned) Sets the column pinned / unpinned. Key can be the column id, field, ColDef object or Column object.
setColumnsPinned(colKeys, pinned) Same as setColumnPinned, but provide a list of column keys.
autoSizeColumn(colKey) Auto-sizes a column based on it's contents.
autoSizeColumns(colKeys) Same as autoSizeColumn, but provide a list of column keys.
getAllColumns() Returns all the columns, regardless of visible or not.
getAllGridColumns() Returns all the grid columns, same as getAllColumns(), except a) it has the order of the columns that are presented in the grid and b) it's after the 'pivot' step, so if pivoting, has the value columns for the pivot.
getAllDisplayedVirtualColumns() Same as getAllGridColumns(), except only returns rendered columns - ie columns not within the viewport that are not rendered, due to column virtualisation, are not displayed.
getDisplayedCenterColumns(), getDisplayedLeftColumns(), getDisplayedRightColumns(), getAllDisplayedColumns() Returns all columns currently displayed (eg are visible and if in a group, the group is showing the columns) for the pinned left, center and pinned right portions of the grid.
getLeftDisplayedColumnGroups(), getCenterDisplayedColumnGroups(), getRightDisplayedColumnGroups(), getAllDisplayedColumnGroups() Returns all 'root' column headers. If you are not grouping columns, these return the columns. If you are grouping, these return the top level groups - you can navigate down through each one to get the other lower level headers and finally the columns at the bottom.
moveColumn(colKey, toIndex) Moves a column to toIndex. The column is first removed, then added at the 'toIndex' location, thus index locations will change to the right of of the column after the removal
moveColumns(colKeys[], toIndex) Same as moveColumn but works on list.
moveColumnByIndex(fromIndex, toIndex) Same as moveColumn but works on index locations.
setColumnAggFunc(column, aggFunc) Sets the agg function for a column. Set to one of [min,max,sum].
setColumnWidth(column, newWidth, finished=true) Sets the column width. The finished flag gets included in the resulting event and not used internally by the grid. The finished flag is intended for dragging, where a dragging action will produce many 'columnWidth' events, so the consumer of events knows when it receives the last event in a stream. The finished parameter is optional, it defaults to 'true'.
getRowGroupColumns(), addRowGroupColumn(colKey), addRowGroupColumns(colKeys), removeRowGroupColumn(colKey), removeRowGroupColumns(colKeys), setRowGroupColumns(colKeys), moveRowGroupColumn(fromIndex, toIndex) Methods for management of column row groups.
getPivotColumns(), setPivotColumns(colKeys), removePivotColumn(), removePivotColumns(colKeys), addPivotColumn(colKey), addPivotColumns(colKeys) Methods for management of column pivots.
isPivotMode(), setPivotMode(mode) Methods to get / set the pivot mode.
getSecondaryPivotColumn(pivotKeys, valueColId) Returns the pivot column for the given pivotKeys and valueColumn. Useful to then call operations on the pivot column.
getValueColumns(), removeValueColumn(colKey), removeValueColumns(colKeys), addValueColumn(colKey), addValueColumns(colKeys) Methods for management of value column aggregates (for aggregating when grouping or pivoting).

Deep Dive - Save / Restore Full State

It is also possible to store the entire state of the columns and restore them again via the API. This includes visibility, width, row groups and values.

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

The methods above get and set the state. The result is a Javascript array object that can be converted to / from JSON. An example of what the JSON might look like is as follows:

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

It is intended that the values in the json mimic the values in the column definitions. So if you want to re-apply the state to a set of column definitions as the default values, override the values of the same name in the corresponding column definition.

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'

The example below shows hiding / showing columns as well as saving / restoring the entire state. The example also registers for column events, the result of which are printed to the console.

Saving / Restoring State, Sort and Filter

The above example shows how to store the state of the columns. This does not include filters or sorts. To also store the filter and sort with the state, you will need to use all the following methods:

// get / set state
gridOptions.columnApi.getColumnState();
gridOptions.columnApi.setColumnState(json);

// get / set sort
gridOptions.api.getSortModel();
gridOptions.api.setSortModel(json);

// get / set filter
gridOptions.api.getFilterModel();
gridOptions.api.setFilterModel(json);