JavaScript Data GridColumns Tool Panel - Configuration

Version 36.3.0

Choose which sections and columns the Columns Tool Panel shows, arrange its list of columns, and make grouping, aggregation and pivoting read only.

main.ts

import {
  ClientSideRowModelModule,
  ColDef,
  ColGroupDef,
  GridApi,
  GridOptions,
  ModuleRegistry,
  NumberFilterModule,
  TextFilterModule,
  createGrid,
  enableDevValidations,
} from "ag-grid-community";
import {
  ColumnMenuModule,
  ColumnsToolPanelModule,
  ContextMenuModule,
  PivotModule,
  SetFilterModule,
} from "ag-grid-enterprise";
import { IOlympicData } from "./interfaces";

if (process.env.NODE_ENV !== "production") {
  // Enable extended validations only for development
  enableDevValidations();
}

ModuleRegistry.registerModules([
  NumberFilterModule,
  ClientSideRowModelModule,
  ColumnsToolPanelModule,
  ColumnMenuModule,
  ContextMenuModule,
  PivotModule,
  SetFilterModule,
  TextFilterModule,
]);

const columnDefs: (ColDef | ColGroupDef)[] = [
  {
    headerName: "Athlete",
    children: [
      {
        field: "athlete",
        filter: "agTextColumnFilter",
        enableRowGroup: true,
        enablePivot: true,
        minWidth: 150,
      },
      { field: "age", enableRowGroup: true, enablePivot: true },
      {
        field: "country",
        enableRowGroup: true,
        enablePivot: true,
        minWidth: 125,
      },
    ],
  },
  {
    headerName: "Competition",
    children: [
      { field: "year", enableRowGroup: true, enablePivot: true },
      { field: "date", enableRowGroup: true, enablePivot: true, minWidth: 180 },
    ],
  },
  { field: "sport", enableRowGroup: true, enablePivot: true, minWidth: 125 },
  {
    headerName: "Medals",
    children: [
      { field: "gold", enableValue: true },
      { field: "silver", enableValue: true },
      { field: "bronze", enableValue: true },
      { field: "total", enableValue: true },
    ],
  },
];

let gridApi: GridApi<IOlympicData>;

const gridOptions: GridOptions<IOlympicData> = {
  columnDefs: columnDefs,
  defaultColDef: {
    flex: 1,
    minWidth: 100,
    filter: true,
  },
  autoGroupColumnDef: {
    minWidth: 200,
  },
  sideBar: "columns",
};

const gridDiv = document.querySelector<HTMLElement>("#myGrid")!;
gridApi = createGrid(gridDiv, gridOptions);

fetch("https://www.ag-grid.com/example-assets/olympic-winners.json")
  .then((response) => response.json())
  .then((data: IOlympicData[]) => gridApi!.setGridOption("rowData", data));

The example above shows the Columns Tool Panel with its default configuration, sideBar: 'columns'. Note the following:

Columns can only be dragged into the Row Groups, Values and Column Labels sections when their column definition allows it, using enableRowGroup, enableValue and enablePivot respectively.
The athlete, age, country, year, date and sport columns set enableRowGroup and enablePivot, so they can be dragged to the Row Groups section, and to the Column Labels section once Pivot Mode is on.
The medal columns set enableValue, so they can be dragged to the Values section.

Section Visibility Copy Link

To remove a section from the Columns Tool Panel, set suppressPivotMode, suppressRowGroups, suppressValues or suppressPivots in toolPanelParams. To remove a control from the top area, set suppressColumnExpandAll, suppressColumnSelectAll or suppressColumnFilter.

Section Visibility API Copy Link

Show or hide the Pivot Mode, Row Groups, Values and Column Labels sections after the grid is created by calling setPivotModeSectionVisible(), setRowGroupsSectionVisible(), setValuesSectionVisible() or setPivotSectionVisible():

// get the Columns Tool Panel instance
const columnsToolPanel = api.getToolPanelInstance('columns');

// hides the Row Groups section
columnsToolPanel.setRowGroupsSectionVisible(false);

// shows the Column Labels section
columnsToolPanel.setPivotSectionVisible(true);

The example below hides all of these sections and controls with the parameters above. Note the following:

The Pivot Mode, Row Groups, Values and Column Labels checkboxes show and hide each section using the api methods.
The Expand / Collapse All, Select / Unselect All and Search controls stay hidden, as they can only be set through toolPanelParams.
The date column is hidden from the tool panel; see Hiding Columns.

main.ts

import {
  ClientSideRowModelModule,
  GridApi,
  GridOptions,
  ModuleRegistry,
  createGrid,
  enableDevValidations,
} from "ag-grid-community";
import {
  ColumnMenuModule,
  ColumnsToolPanelModule,
  ContextMenuModule,
  PivotModule,
} from "ag-grid-enterprise";
import { IOlympicData } from "./interfaces";

if (process.env.NODE_ENV !== "production") {
  // Enable extended validations only for development
  enableDevValidations();
}

ModuleRegistry.registerModules([
  ClientSideRowModelModule,
  ColumnsToolPanelModule,
  ColumnMenuModule,
  ContextMenuModule,
  PivotModule,
]);

let gridApi: GridApi<IOlympicData>;

const gridOptions: GridOptions<IOlympicData> = {
  columnDefs: [
    { headerName: "Name", field: "athlete", minWidth: 200 },
    { field: "age", enableRowGroup: true },
    { field: "country", minWidth: 200 },
    { field: "year" },
    { field: "date", suppressColumnsToolPanel: true, minWidth: 180 },
    { field: "sport", minWidth: 200 },
    { field: "gold", aggFunc: "sum" },
    { field: "silver", aggFunc: "sum" },
    { field: "bronze", aggFunc: "sum" },
    { field: "total", aggFunc: "sum" },
  ],
  defaultColDef: {
    flex: 1,
    minWidth: 100,
    enablePivot: true,
  },
  autoGroupColumnDef: {
    minWidth: 200,
  },
  sideBar: {
    toolPanels: [
      {
        id: "columns",
        labelDefault: "Columns",
        labelKey: "columns",
        iconKey: "columns",
        toolPanel: "agColumnsToolPanel",
        toolPanelParams: {
          suppressRowGroups: true,
          suppressValues: true,
          suppressPivots: true,
          suppressPivotMode: true,
          suppressColumnFilter: true,
          suppressColumnSelectAll: true,
          suppressColumnExpandAll: true,
        },
      },
    ],
    defaultToolPanel: "columns",
  },
};

function togglePivotModeSection() {
  const columnsToolPanel = gridApi!.getToolPanelInstance("columns")!;
  columnsToolPanel.setPivotModeSectionVisible(
    document.querySelector<HTMLInputElement>("#pivotModeSection")!.checked,
  );
}

function toggleRowGroupsSection() {
  const columnsToolPanel = gridApi!.getToolPanelInstance("columns")!;
  columnsToolPanel.setRowGroupsSectionVisible(
    document.querySelector<HTMLInputElement>("#rowGroupsSection")!.checked,
  );
}

function toggleValuesSection() {
  const columnsToolPanel = gridApi!.getToolPanelInstance("columns")!;
  columnsToolPanel.setValuesSectionVisible(
    document.querySelector<HTMLInputElement>("#valuesSection")!.checked,
  );
}

function togglePivotSection() {
  const columnsToolPanel = gridApi!.getToolPanelInstance("columns")!;
  columnsToolPanel.setPivotSectionVisible(
    document.querySelector<HTMLInputElement>("#pivotSection")!.checked,
  );
}

const gridDiv = document.querySelector<HTMLElement>("#myGrid")!;
gridApi = createGrid(gridDiv, gridOptions);

fetch("https://www.ag-grid.com/example-assets/olympic-winners.json")
  .then((response) => response.json())
  .then((data: IOlympicData[]) => gridApi!.setGridOption("rowData", data));

if (typeof window !== "undefined") {
  // Attach external event handlers to window so they can be called from index.html
  (<any>window).togglePivotModeSection = togglePivotModeSection;
  (<any>window).toggleRowGroupsSection = toggleRowGroupsSection;
  (<any>window).toggleValuesSection = toggleValuesSection;
  (<any>window).togglePivotSection = togglePivotSection;
}

Hiding Columns Copy Link

To remove a column from the tool panel, set suppressColumnsToolPanel on its column definition. This is useful for a column that works in the background, such as one the grid groups by, that users should not see.

Suppress Column Reordering Copy Link

By default, reordering columns in the grid also reorders them in the Columns section. Set suppressSyncLayoutWithGrid to keep the tool panel order fixed.

Users can also reorder columns by dragging them within the Columns section. Set suppressColumnMove to prevent this. suppressSyncLayoutWithGrid also prevents it, so suppressColumnMove is only needed on its own when the tool panel should still follow the grid order.

const gridOptions = {
    sideBar: {
        toolPanels: [
            {
                id: 'columns',
                labelDefault: 'Columns',
                labelKey: 'columns',
                iconKey: 'columns',
                toolPanel: 'agColumnsToolPanel',
                toolPanelParams: {
                    // tool panel columns won't move when columns are reordered in the grid
                    suppressSyncLayoutWithGrid: true,
                    // prevents columns being reordered from the Columns Tool Panel
                    suppressColumnMove: true,
                },
            },
        ],
        defaultToolPanel: 'columns',
    },

    // other grid options ...
}

The example below enables both properties. Note the following:

Moving columns in the grid doesn't reorder columns in the Columns Tool Panel, as suppressSyncLayoutWithGrid=true.
Columns can't be reordered from the Columns Tool Panel, as both properties are enabled.

main.ts

import {
  ClientSideRowModelModule,
  GridApi,
  GridOptions,
  ModuleRegistry,
  NumberFilterModule,
  TextFilterModule,
  createGrid,
  enableDevValidations,
} from "ag-grid-community";
import {
  ColumnMenuModule,
  ColumnsToolPanelModule,
  ContextMenuModule,
  PivotModule,
} from "ag-grid-enterprise";
import { IOlympicData } from "./interfaces";

if (process.env.NODE_ENV !== "production") {
  // Enable extended validations only for development
  enableDevValidations();
}

ModuleRegistry.registerModules([
  NumberFilterModule,
  ClientSideRowModelModule,
  ColumnsToolPanelModule,
  ColumnMenuModule,
  ContextMenuModule,
  PivotModule,
  TextFilterModule,
]);

let gridApi: GridApi<IOlympicData>;

const gridOptions: GridOptions<IOlympicData> = {
  columnDefs: [
    {
      headerName: "Athlete",
      children: [
        {
          headerName: "Name",
          field: "athlete",
          minWidth: 200,
          filter: "agTextColumnFilter",
        },
        { field: "age" },
        { field: "country", minWidth: 200 },
      ],
    },
    {
      headerName: "Competition",
      children: [{ field: "year" }, { field: "date", minWidth: 180 }],
    },
    { colId: "sport", field: "sport", minWidth: 200 },
    {
      headerName: "Medals",
      children: [
        { field: "gold" },
        { field: "silver" },
        { field: "bronze" },
        { field: "total" },
      ],
    },
  ],
  defaultColDef: {
    flex: 1,
    minWidth: 100,
    // allow every column to be aggregated
    enableValue: true,
    // allow every column to be grouped
    enableRowGroup: true,
    // allow every column to be pivoted
    enablePivot: true,
    filter: true,
  },
  autoGroupColumnDef: {
    minWidth: 200,
  },
  sideBar: {
    toolPanels: [
      {
        id: "columns",
        labelDefault: "Columns",
        labelKey: "columns",
        iconKey: "columns",
        toolPanel: "agColumnsToolPanel",
        toolPanelParams: {
          // tool panel columns won't move when columns are reordered in the grid
          suppressSyncLayoutWithGrid: true,
          // prevents columns being reordered from the columns tool panel
          suppressColumnMove: true,
        },
      },
    ],
    defaultToolPanel: "columns",
  },
};

const gridDiv = document.querySelector<HTMLElement>("#myGrid")!;
gridApi = createGrid(gridDiv, gridOptions);

fetch("https://www.ag-grid.com/example-assets/olympic-winners.json")
  .then((response) => response.json())
  .then((data: IOlympicData[]) => gridApi!.setGridOption("rowData", data));

Custom Column Layout Copy Link

By default, the Columns section follows the order of columnDefs and stays in sync as columns move in the grid. To define a different layout, pass Column Definitions to setColumnLayout() on the Columns Tool Panel instance.

Given these column definitions supplied to the grid:

const gridOptions = {
    columnDefs: [
        { field: 'a' },
        { field: 'b' },
        { field: 'c' }
    ],

    // other grid options ...
}

The following layout adds a group, reorders the columns and omits column b:

const columnsToolPanel = api.getToolPanelInstance('columns');
columnsToolPanel.setColumnLayout([
    {
        headerName: 'Group 1', // group doesn't appear in grid
        children: [
            { field: 'c' }, // custom column order with column "b" omitted
            { field: 'a' }
        ]
    }
]);

The layout can contain column groups that don't exist in the grid, and can omit or reorder columns, but every column it references must already exist in the grid.

When providing a custom layout, enable suppressSyncLayoutWithGrid so that moving columns in the grid does not replace it (see Suppress Column Reordering).

The example below shows two custom layouts for the Columns Tool Panel. Note the following:

When the grid is initialised, the Columns Tool Panel layout matches gridOptions.columnDefs.
Custom Sort Layout calls setColumnLayout(colDefs) with the columns in ascending order.
Custom Group Layout calls setColumnLayout(colDefs) with column groups that don't appear in the grid.
Moving columns in the grid doesn't affect the custom layouts, as suppressSyncLayoutWithGrid is enabled.
Moving columns within the Columns Tool Panel is disabled, as suppressSyncLayoutWithGrid and suppressColumnMove are enabled.

main.ts

import {
  ClientSideRowModelModule,
  GridApi,
  GridOptions,
  ModuleRegistry,
  NumberFilterModule,
  TextFilterModule,
  createGrid,
  enableDevValidations,
} from "ag-grid-community";
import {
  ColumnMenuModule,
  ColumnsToolPanelModule,
  ContextMenuModule,
  PivotModule,
  SetFilterModule,
} from "ag-grid-enterprise";
import { IOlympicData } from "./interfaces";

if (process.env.NODE_ENV !== "production") {
  // Enable extended validations only for development
  enableDevValidations();
}

ModuleRegistry.registerModules([
  NumberFilterModule,
  ClientSideRowModelModule,
  ColumnsToolPanelModule,
  ColumnMenuModule,
  ContextMenuModule,
  SetFilterModule,
  PivotModule,
  TextFilterModule,
]);

let gridApi: GridApi<IOlympicData>;

const gridOptions: GridOptions<IOlympicData> = {
  columnDefs: [
    {
      headerName: "Athlete",
      children: [
        {
          headerName: "Name",
          field: "athlete",
          minWidth: 200,
          filter: "agTextColumnFilter",
        },
        { field: "age" },
        { field: "country", minWidth: 200 },
      ],
    },
    {
      headerName: "Competition",
      children: [{ field: "year" }, { field: "date", minWidth: 180 }],
    },
    { colId: "sport", field: "sport", minWidth: 200 },
    {
      headerName: "Medals",
      children: [
        { field: "gold" },
        { field: "silver" },
        { field: "bronze" },
        { field: "total" },
      ],
    },
  ],
  defaultColDef: {
    flex: 1,
    minWidth: 100,
    // allow every column to be aggregated
    enableValue: true,
    // allow every column to be grouped
    enableRowGroup: true,
    // allow every column to be pivoted
    enablePivot: true,
    filter: true,
  },
  autoGroupColumnDef: {
    minWidth: 200,
  },
  sideBar: {
    toolPanels: [
      {
        id: "columns",
        labelDefault: "Columns",
        labelKey: "columns",
        iconKey: "columns",
        toolPanel: "agColumnsToolPanel",
        toolPanelParams: {
          // prevents custom layout changing when columns are reordered in the grid
          suppressSyncLayoutWithGrid: true,
          // prevents columns being reordered from the columns tool panel
          suppressColumnMove: true,
        },
      },
    ],
    defaultToolPanel: "columns",
  },
};

const sortedToolPanelColumnDefs = [
  {
    headerName: "Athlete",
    children: [
      { field: "age" },
      { field: "country" },
      { headerName: "Name", field: "athlete" },
    ],
  },
  {
    headerName: "Competition",
    children: [{ field: "date" }, { field: "year" }],
  },
  {
    headerName: "Medals",
    children: [
      { field: "bronze" },
      { field: "gold" },
      { field: "silver" },
      { field: "total" },
    ],
  },
  { colId: "sport", field: "sport" },
];

function setCustomSortLayout() {
  const columnsToolPanel = gridApi!.getToolPanelInstance("columns");
  columnsToolPanel!.setColumnLayout(sortedToolPanelColumnDefs);
}

const customToolPanelColumnDefs = [
  {
    headerName: "Dummy Group 1",
    children: [
      { field: "age" },
      { headerName: "Name", field: "athlete" },
      {
        headerName: "Dummy Group 2",
        children: [{ colId: "sport" }, { field: "country" }],
      },
    ],
  },
  {
    headerName: "Medals",
    children: [
      { field: "total" },
      { field: "bronze" },
      {
        headerName: "Dummy Group 3",
        children: [{ field: "silver" }, { field: "gold" }],
      },
    ],
  },
];

function setCustomGroupLayout() {
  const columnsToolPanel = gridApi!.getToolPanelInstance("columns");
  columnsToolPanel!.setColumnLayout(customToolPanelColumnDefs);
}

const gridDiv = document.querySelector<HTMLElement>("#myGrid")!;
gridApi = createGrid(gridDiv, gridOptions);

fetch("https://www.ag-grid.com/example-assets/olympic-winners.json")
  .then((response) => response.json())
  .then((data: IOlympicData[]) => gridApi!.setGridOption("rowData", data));

if (typeof window !== "undefined") {
  // Attach external event handlers to window so they can be called from index.html
  (<any>window).setCustomSortLayout = setCustomSortLayout;
  (<any>window).setCustomGroupLayout = setCustomGroupLayout;
}

Read Only Functions Copy Link

Set the grid option functionsReadOnly=true to prevent users changing grouping, pivoting or aggregation through the UI. The Row Groups, Values and Column Labels sections stay visible, so users can see which columns are in use but cannot change them.

The example below starts with functionsReadOnly=true. Note the following:

The grid is in pivot mode, grouped by country and sport, pivoted by year, with silver and bronze aggregated.
Columns cannot be dragged into or removed from the Row Groups, Values and Column Labels sections.
Untick Functions Read Only to allow changes again.

main.ts

import {
  ClientSideRowModelModule,
  ColDef,
  GridApi,
  GridOptions,
  ModuleRegistry,
  createGrid,
  enableDevValidations,
} from "ag-grid-community";
import {
  ColumnMenuModule,
  ColumnsToolPanelModule,
  ContextMenuModule,
  PivotModule,
  RowGroupingPanelModule,
} from "ag-grid-enterprise";
import { IOlympicData } from "./interfaces";

if (process.env.NODE_ENV !== "production") {
  // Enable extended validations only for development
  enableDevValidations();
}

ModuleRegistry.registerModules([
  ClientSideRowModelModule,
  ColumnsToolPanelModule,
  ColumnMenuModule,
  ContextMenuModule,
  PivotModule,
  RowGroupingPanelModule,
]);

const columnDefs: ColDef[] = [
  {
    field: "athlete",
    minWidth: 200,
    enableRowGroup: true,
    enablePivot: true,
  },
  {
    field: "age",
    enableValue: true,
  },
  {
    field: "country",
    minWidth: 200,
    enableRowGroup: true,
    enablePivot: true,
    rowGroupIndex: 1,
  },
  {
    field: "year",
    enableRowGroup: true,
    enablePivot: true,
    pivotIndex: 1,
  },
  {
    field: "date",
    minWidth: 180,
    enableRowGroup: true,
    enablePivot: true,
  },
  {
    field: "sport",
    minWidth: 200,
    enableRowGroup: true,
    enablePivot: true,
    rowGroupIndex: 2,
  },
  {
    field: "gold",
    hide: true,
    enableValue: true,
  },
  {
    field: "silver",
    hide: true,
    enableValue: true,
    aggFunc: "sum",
  },
  {
    field: "bronze",
    hide: true,
    enableValue: true,
    aggFunc: "sum",
  },
  {
    headerName: "Total",
    field: "total",
  },
];

let gridApi: GridApi<IOlympicData>;

const gridOptions: GridOptions<IOlympicData> = {
  columnDefs: columnDefs,
  defaultColDef: {
    flex: 1,
    minWidth: 150,
  },
  autoGroupColumnDef: {
    minWidth: 250,
  },
  pivotMode: true,
  sideBar: "columns",
  rowGroupPanelShow: "always",
  pivotPanelShow: "always",
  functionsReadOnly: true,
  onGridReady: (params) => {
    (document.getElementById("read-only") as HTMLInputElement).checked = true;
  },
};

function setReadOnly() {
  gridApi!.setGridOption(
    "functionsReadOnly",
    (document.getElementById("read-only") as HTMLInputElement).checked,
  );
}

const gridDiv = document.querySelector<HTMLElement>("#myGrid")!;
gridApi = createGrid(gridDiv, gridOptions);

fetch("https://www.ag-grid.com/example-assets/olympic-winners.json")
  .then((response) => response.json())
  .then((data: IOlympicData[]) => gridApi!.setGridOption("rowData", data));

if (typeof window !== "undefined") {
  // Attach external event handlers to window so they can be called from index.html
  (<any>window).setReadOnly = setReadOnly;
}

Parameters Copy Link

The Columns section and the Column Chooser use the same column selection panel. Their shared options are defined by IColumnSelectionPanelParams, while IToolPanelColumnCompParams adds options specific to the Columns Tool Panel. See Providing Parameters to Tool Panels for how to pass these to the tool panel.

IColumnSelectionPanelParams Copy Link

Properties available on the IColumnSelectionPanelParams interface.

boolean

To suppress updating the layout of columns as they are rearranged in the grid.

boolean

To suppress the column search.

boolean

To suppress the Select / Unselect All widget.

boolean

To suppress the Expand / Collapse All widget.

boolean

By default, column groups start expanded. Pass true to start with groups collapsed.

any

Component used to render column and column group labels. The checkbox, drag handle and expand controls remain grid managed.

any

Additional parameters passed to the columnLabelRenderer.

ColumnSelectionLabelRendererSelectorFunc

Callback to select which renderer to use for an individual column or column group label. The result can also provide renderer-specific params. Return undefined to use columnLabelRenderer.

IToolPanelColumnCompParams Copy Link

Properties available on the IToolPanelColumnCompParams interface.

boolean

Suppress Column Move

boolean

Suppress Row Groups section

boolean

Suppress Values section

boolean

Suppress Column Labels (Pivot) section

boolean

Suppress Pivot Mode selection

ColumnToolPanelAction[]

Buttons to display at the bottom of the Columns Tool Panel, in the order they should be displayed in.

'apply': Changes are deferred until the Apply button is clicked.

'cancel': Discards any deferred changes. Only has an effect when 'apply' is also included.

'reset': Immediately resets the columns to the state defined in the current column definitions, discarding any pending changes.

Only the 'apply' button enables deferred changes.

API Copy Link

Columns Tool Panel Instance Copy Link

Get the Columns Tool Panel instance from the grid API using its tool panel id, which is 'columns' by default:

const columnsToolPanel = api.getToolPanelInstance('columns');

Function

Sets a custom layout of columns and column groups for the Columns section. Every referenced column must already exist in the grid.

Function

Shows or hides the Pivot Mode section.

Function

Shows or hides the Row Groups section.

Function

Shows or hides the Values section.

Function

Shows or hides the Column Labels (pivot) section.

Getting Started

AI Features

Layout & Styling

Charting

Core Features

Advanced Features

JavaScript Data GridColumns Tool Panel - Configuration

Section Visibility Copy Link

Section Visibility API Copy Link

Hiding Columns Copy Link

Suppress Column Reordering Copy Link

Custom Column Layout Copy Link

Read Only Functions Copy Link

Parameters Copy Link

IColumnSelectionPanelParams Copy Link

IToolPanelColumnCompParams Copy Link

API Copy Link

Columns Tool Panel Instance Copy Link