Columns Tool Panel

The columns tool panel provides functions for managing the grid's columns.

Simple Example

Below shows a simple example of the columns tool panel. The following can be noted:

  • Grid property toolPanel='columns' which shows only the columns tool panel.
  • Grid property defaultColDef has enableValue, enableRowGroup and enablePivot set. This means all columns can be dragged to any of the Row Groups, Vales and Column sections. Although each column can be dragged to these sections, it does not make sense. For example, it does not make sense to aggregate the country column, but it does make sense to row group by country.

Things to try:

  • Checking / Unchecking columns will show / hide the columns.
  • Drag a column (eg Country) to Row Groups to row group.
  • Drag a column (eg Gold) to Values to aggregate.
  • Reset (refresh) the demo and do the following:
    • Click 'Pivot Mode'.
    • Drag 'Country' to 'Row Groups'.
    • Drag 'Year' to 'Column Labels'.
    • Drag 'Gold' to 'Values'.
    You will now have a pivot grid showing total gold medals for each country (rows showing countries) by year (columns showing years).

Remember to mark the column definitions with enableRowGroup for grouping, enablePivot for pivoting and enableValue for aggregation. Otherwise you won't be able to drag and drop the columns to the desired sections.

Selection Action

Selecting columns means different things depending on whether the grid is in pivot mode or not as follows:

  • Pivot Mode Off: When pivot mode is off, selecting a column toggles the visibility of the column. A selected column is visible and a non selected column is hidden. If you drag a column from the tool panel onto the grid it will make it visible.
  • Pivot Mode On: When pivot mode is on, selecting a column will trigger the column to be either aggregated, grouped or pivoted depending on what is allowed for that column.

Column Tool Panel Sections

The column tool panel is split into difference sections which are follows:

  • Pivot Mode Section: Check the 'Pivot Mode' checkbox to turn the grid into Pivot Mode. Uncheck to take the grid out of pivot mode.
  • Expand / Collapse All: Toggle to expand or collapse all column groups.
  • Columns Section: Display all columns, grouped by column groups, that are available to be displayed in the grid. The order of the columns is the order in which columns were provided to the grid and do not change even if the user changes the column order inside the grid.
  • Select / Un-select All: Toggle to select or un-select all columns in the columns section.
  • Select / Un-Select Column (or Group): Each column can be individually selected. What selection means depends on pivot mode and is explained below*.
  • Drag Handle: Each column can be dragged either with the mouse or via touch on touch devices. The column can then be dragged to one of the following:
    1. Row Groups Section
    2. Values (Pivot) Section
    3. Column Labels Section
    4. Onto the grid
  • Row Groups Section: Columns here will form the grids Row Grouping.
  • Values Section: Columns here will form the grids Aggregations. The grid calls this function 'Aggregations', however for the UI we follow Excel naming convention and call it 'Values'.
  • Column Labels (Pivot) Section: Columns here will form the grids Pivot. The grid calls this function 'Pivot', however for the UI we follow Excel naming convention and call it 'Column Labels'.

ag-Grid Tool Panel Section

Suppress Sections

It is possible to remove items from the tool panel. Items are suppressed by setting one or more of the following componentParams whenever you are using the agColumnsToolPanel component properties to true:

  • suppressRowGroups: to suppress Row Groups section.
  • suppressValues: to suppress Values section.
  • suppressPivots: to suppress Column Labels (Pivot) section.
  • suppressPivotMode: to suppress Pivot Mode section.
  • suppressColumnFilter: To suppress Column Filter section.
  • suppressColumnSelectAll: To suppress Select / Un-select all widget.
  • suppressColumnExpandAll: To suppress Expand / Collapse all widget.

To remove a particular column from the tool panel, set the column property suppressToolPanel to true. This is useful when you have a column working in the background, eg a column you want to group by, but not present to the user.

The example below shows the tool panel demonstrating the suppress options above. The following can be noted:

  • The following sections are not present in the tool panel: Row Groups, Values, Column Labels, Pivot Mode, Side Buttons, Column Filter, Select / Un-select All, Expand / Collapse All.
  • The columns Athlete and Age are also not present in the tool panel.

Styling Columns

You can add a CSS class to the columns in the tool panel by specifying toolPanelHeaderClass in the column definintion as follows: colDefs = { // set as string {headerName: "Gold", field: "gold", toolPanelClass: 'tp-gold'}, // set as array of strings {headerName: "Silver", field: "silver", toolPanelClass: ['tp-silver']}, // set as function returning string or array of strings {headerName: "Bronze", field: "bronze", toolPanelClass: function(params) { return 'tp-bronze'; }}, }

Changing Tool Panel Contents Height

By default, the tool panel panels stretch to fit the height of the grid, with maximum height set to 100vh. To tweak the height of them, you can tweak the .ag-column-panel-center selector:

.ag-column-panel-center { /* increase the total max height of tool panel contents */ max-height: 2000px; }

Column Tool Panel Example

The example below demonstrates the column tool panel using a mixture of items explained above. Note the following:

  • Columns country, year, date and sport all have enableRowGroup=true and enablePivot=true. This means you can drag the columns to the group and pivot sections, but you cannot drag them to the values sections.
  • The gold, silver and bronze all have enableValue=true. This means you can drag the columns to the values section, but you cannot drag them to the group or pivot sections.
  • The gold, silver and bronze columns have style applied using toolPanelClass
  • The country column uses a headerValueGetter to give the column a slightly different name when dependent on where it appears using the location parameter.

Read Only Functions

By setting the property functionsReadOnly=true, the grid will prevent changes to group, pivot or values through the GUI. This is useful if you want to show the user the group, pivot and values panel, so they can see what columns are used, but prevent them from making changes to the selection.

Next Up

Now that we covered the Columns Tool Panel, continue to the next section to learn about the Filters Tool Bar.