Vue Data GridColumn Chooser

Version 36.2.0

Enterprise

The Column Chooser is a dialog that displays the grid's columns, allowing users to show, hide and reorder them. When column definitions contain groups, these are displayed as expandable rows containing their child columns.

Open the Column Chooser by selecting Choose Columns from the Column Menu or by calling api.showColumnChooser(). The same column selection panel is also available docked to the side of the grid as part of the Columns Tool Panel.

Customising the Column Chooser Copy Link

The behaviour and appearance of the Column Chooser can be customised with ColumnChooserParams. Set colDef.columnChooserParams to configure the chooser opened from that column, or set defaultColDef.columnChooserParams to apply the same configuration to every column. When opening the chooser through the Grid API, the same options can instead be passed to api.showColumnChooser(params). These options are unset by default.

ColumnChooserParams extends the shared IColumnSelectionPanelParams interface, so the same column selection options apply to the Columns Tool Panel, where they are set through toolPanelParams instead.

Properties available on the ColumnChooserParams interface.

(ColDef | ColGroupDef)[]

Custom Columns Panel layout

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 following example demonstrates the suppression and contractColumnSelection options above; the column label renderer options and columnLayout are covered in the sections below. Note the following:

Launch the Column Chooser by selecting Choose Columns from any column menu.
The Column Chooser opened from any column ignores column moves in the grid because suppressSyncLayoutWithGrid=true is set on the default column definition.
The Name column's chooser does not show the column search, Select / Unselect All or Expand / Collapse All controls because suppressColumnFilter, suppressColumnSelectAll and suppressColumnExpandAll are all set to true.
The Age column's chooser starts with column groups collapsed because contractColumnSelection=true.

main.ts

import {
  createApp,
  defineComponent,
  onBeforeMount,
  ref,
  shallowRef,
} from "vue";
import { AgGridVue } from "ag-grid-vue3";
import {
  ClientSideRowModelModule,
  ColDef,
  ColGroupDef,
  GridApi,
  GridOptions,
  GridReadyEvent,
  ModuleRegistry,
  enableDevValidations,
} from "ag-grid-community";
import {
  ColumnMenuModule,
  ColumnsToolPanelModule,
  ContextMenuModule,
} 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,
]);

const VueExample = defineComponent({
  template: `
        <div style="height: 100%">
                <ag-grid-vue
      style="width: 100%; height: 100%;"
      @grid-ready="onGridReady"
      :columnDefs="columnDefs"
      :defaultColDef="defaultColDef"
      :rowData="rowData"></ag-grid-vue>
        </div>
    `,
  components: {
    "ag-grid-vue": AgGridVue,
  },
  setup(props) {
    const gridApi = shallowRef<GridApi<IOlympicData> | null>(null);
    const columnDefs = ref<(ColDef | ColGroupDef)[]>([
      {
        groupId: "athleteGroupId",
        headerName: "Athlete",
        children: [
          {
            headerName: "Name",
            field: "athlete",
            minWidth: 200,
            columnChooserParams: {
              // hides the Column Filter section
              suppressColumnFilter: true,
              // hides the Select / Un-select all widget
              suppressColumnSelectAll: true,
              // hides the Expand / Collapse all widget
              suppressColumnExpandAll: true,
            },
          },
          {
            field: "age",
            minWidth: 200,
            columnChooserParams: {
              // contracts all column groups
              contractColumnSelection: true,
            },
          },
        ],
      },
      {
        groupId: "medalsGroupId",
        headerName: "Medals",
        children: [{ field: "gold" }, { field: "silver" }, { field: "bronze" }],
      },
    ]);
    const defaultColDef = ref<ColDef>({
      flex: 1,
      columnChooserParams: {
        // suppresses updating the layout of columns as they are rearranged in the grid
        suppressSyncLayoutWithGrid: true,
      },
    });
    const rowData = ref<IOlympicData[]>(null);

    const onGridReady = (params: GridReadyEvent) => {
      gridApi.value = params.api;

      const updateData = (data) => (rowData.value = data);

      fetch("https://www.ag-grid.com/example-assets/olympic-winners.json")
        .then((resp) => resp.json())
        .then((data) => updateData(data));
    };

    return {
      gridApi,
      columnDefs,
      defaultColDef,
      rowData,
      onGridReady,
    };
  },
});

const app = createApp(VueExample);
app.mount("#app");

Custom Column Labels Copy Link

Use columnLabelRenderer in ColumnChooserParams to replace the text shown for columns and column groups. The checkbox, drag handle and group expand controls remain grid managed. Additional properties can be supplied through columnLabelRendererParams.

Use columnLabelRendererSelector to select different renderers for individual columns or column groups. The selector can also provide renderer-specific params; returning undefined falls back to columnLabelRenderer.

<ag-grid-vue
    :components="components"
    :defaultColDef="defaultColDef"
    /* other grid options ... */>
</ag-grid-vue>

this.components = {
    customColumnLabel: CustomColumnLabel,
};
this.defaultColDef = {
    columnChooserParams: {
        columnLabelRenderer: 'customColumnLabel',
        columnLabelRendererParams: {
            columnIcon: '●',
            columnGroupIcon: '◆',
        },
    },
};

For each label in the Column Chooser, the renderer receives the resolved displayName and either column or columnGroup, depending on the item being rendered. The source is always 'columnChooser'. Setting these options on defaultColDef.columnChooserParams applies them to the chooser regardless of which column it is opened from. They can also be supplied when calling api.showColumnChooser(params).

The Column Chooser does not automatically inherit a renderer configured for the Columns Tool Panel. To use the same presentation in both places, register the component once and reference its name from both configurations. Both ColumnChooserParams and IToolPanelColumnCompParams extend the shared IColumnSelectionPanelParams interface.

Column search and accessibility announcements continue to use displayName, rather than text extracted from the renderer. Column selection rows have a fixed height, so renderer content should remain inline and fit within the configured list item height.

main.ts

import {
  createApp,
  defineComponent,
  onBeforeMount,
  ref,
  shallowRef,
} from "vue";
import { AgGridVue } from "ag-grid-vue3";
import "./styles.css";
import {
  ClientSideRowModelModule,
  ColDef,
  ColGroupDef,
  Components,
  GridApi,
  GridOptions,
  GridReadyEvent,
  ModuleRegistry,
  enableDevValidations,
} from "ag-grid-community";
import { ColumnMenuModule, ColumnsToolPanelModule } from "ag-grid-enterprise";
import CustomColumnLabel from "./customColumnLabelVue";

if (process.env.NODE_ENV !== "production") {
  enableDevValidations();
}

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

const VueExample = defineComponent({
  template: `
        <div style="height: 100%">
                <div class="example-wrapper">
      <ag-grid-vue
        style="width: 100%; height: 100%;"
        @grid-ready="onGridReady"
        :columnDefs="columnDefs"
        :rowData="rowData"
        :defaultColDef="defaultColDef"></ag-grid-vue>
      </div>
        </div>
    `,
  components: {
    "ag-grid-vue": AgGridVue,
    customColumnLabel: CustomColumnLabel,
    CustomColumnLabel,
  },
  setup(props) {
    const gridApi = shallowRef<GridApi | null>(null);
    const columnDefs = ref<(ColDef | ColGroupDef)[]>([
      {
        headerName: "Athlete Details",
        groupId: "athleteDetails",
        children: [
          { field: "athlete" },
          { field: "country" },
          { field: "sport" },
        ],
      },
      {
        headerName: "Results",
        groupId: "results",
        children: [{ field: "gold" }, { field: "silver" }, { field: "bronze" }],
      },
    ]);
    const rowData = ref<any[] | null>([
      {
        athlete: "Michael Phelps",
        country: "United States",
        sport: "Swimming",
        gold: 8,
        silver: 0,
        bronze: 0,
      },
    ]);
    const defaultColDef = ref<ColDef>({
      flex: 1,
      minWidth: 120,
      columnChooserParams: {
        columnLabelRenderer: "customColumnLabel",
        columnLabelRendererParams: {
          columnIcon: "●",
          columnGroupIcon: "◆",
        },
      },
    });

    const onGridReady = (params: GridReadyEvent) => {
      gridApi.value = params.api;
    };

    return {
      gridApi,
      columnDefs,
      rowData,
      defaultColDef,
      onGridReady,
    };
  },
});

const app = createApp(VueExample);
app.mount("#app");

styles.css

.example-wrapper {
    display: flex;
    flex-direction: column;
    height: 100%;
}

#myGrid {
    flex: 1 1 0px;
    width: 100%;
}

.custom-column-label {
    display: inline-flex;
    min-width: 0;
    align-items: center;
    gap: 6px;
}

.custom-column-label-icon {
    color: var(--ag-accent-color);
}

.custom-column-label-text {
    overflow: hidden;
    text-overflow: ellipsis;
    white-space: nowrap;
}

customColumnLabelVue.ts

export default {
    template: `
        <span class="custom-column-label">
            <span class="custom-column-label-icon">
                {{ params.columnGroup ? params.columnGroupIcon : params.columnIcon }}
            </span>
            <span class="custom-column-label-text">{{ params.displayName }}</span>
        </span>
    `,
};

Renderer Parameters Copy Link

Properties available on the IColumnSelectionLabelRendererParams<TData = any, TContext = any> interface.

string | null

The text value resolved from the column or column group definition.

Column | null

The column being rendered, or null when rendering a column group.

ProvidedColumnGroup | null

The column group being rendered, or null when rendering a column.

ColumnSelectionPanelSource

The panel in which the label is rendered.

GridApi

The grid api.

TContext

Application context as set on gridOptions.context.

Custom Column Layout Copy Link

By default, the order of columns in the Column Chooser is derived from the columnDefs supplied in the grid options and is kept in sync when columns are moved in the grid.

A custom layout can instead be provided through colDef.columnChooserParams.columnLayout.

<ag-grid-vue
    :columnDefs="columnDefs"
    /* other grid options ... */>
</ag-grid-vue>

// original column definitions supplied to the grid
this.columnDefs = [
    {
        columnChooserParams: {
            columnLayout: [{
                headerName: 'Group 1', // group doesn't appear in grid
                children: [
                    { field: 'c' }, // custom column order with column "b" omitted
                    { field: 'a' }
                ]
            }]
        }
    },
    { field: 'b' },
    { field: 'c' }
];

Providing columnLayout automatically enables suppressSyncLayoutWithGrid. Reordering columns in the grid therefore does not reorder the custom layout displayed in the Column Chooser.

The following example demonstrates custom Column Chooser layouts. Note the following:

Open the Column Chooser for the Name column and note that it uses the order specified by columnLayout.
Open the Column Chooser for the Age column and note that it uses the current column order from the grid.
Drag the Age column to the left of the Name column in the grid.
Open the Column Chooser for the Age column and note that Age now appears before Name.
Open the Column Chooser for the Name column and note that its custom layout remains unchanged.

main.ts

import {
  createApp,
  defineComponent,
  onBeforeMount,
  ref,
  shallowRef,
} from "vue";
import { AgGridVue } from "ag-grid-vue3";
import {
  ClientSideRowModelModule,
  ColDef,
  ColGroupDef,
  GridApi,
  GridOptions,
  GridReadyEvent,
  ModuleRegistry,
  enableDevValidations,
} from "ag-grid-community";
import {
  ColumnMenuModule,
  ColumnsToolPanelModule,
  ContextMenuModule,
} 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,
]);

const VueExample = defineComponent({
  template: `
        <div style="height: 100%">
                <ag-grid-vue
      style="width: 100%; height: 100%;"
      @grid-ready="onGridReady"
      :columnDefs="columnDefs"
      :defaultColDef="defaultColDef"
      :rowData="rowData"></ag-grid-vue>
        </div>
    `,
  components: {
    "ag-grid-vue": AgGridVue,
  },
  setup(props) {
    const gridApi = shallowRef<GridApi<IOlympicData> | null>(null);
    const columnDefs = ref<(ColDef | ColGroupDef)[]>([
      {
        groupId: "athleteGroupId",
        headerName: "Athlete",
        children: [
          {
            headerName: "Name",
            field: "athlete",
            minWidth: 150,
            columnChooserParams: {
              columnLayout: [
                {
                  headerName: "Group 1", // Athlete group renamed to "Group 1"
                  children: [
                    // custom column order with columns "gold", "silver", "bronze" omitted
                    { field: "sport" },
                    { field: "athlete" },
                    { field: "age" },
                  ],
                },
              ],
            },
          },
          {
            field: "age",
            minWidth: 120,
          },
          {
            field: "sport",
            minWidth: 150,
            columnChooserParams: {
              // contracts all column groups
              contractColumnSelection: true,
            },
          },
        ],
      },
      {
        groupId: "medalsGroupId",
        headerName: "Medals",
        children: [{ field: "gold" }, { field: "silver" }, { field: "bronze" }],
      },
    ]);
    const defaultColDef = ref<ColDef>({
      flex: 1,
    });
    const rowData = ref<IOlympicData[]>(null);

    const onGridReady = (params: GridReadyEvent) => {
      gridApi.value = params.api;

      const updateData = (data) => (rowData.value = data);

      fetch("https://www.ag-grid.com/example-assets/olympic-winners.json")
        .then((resp) => resp.json())
        .then((data) => updateData(data));
    };

    return {
      gridApi,
      columnDefs,
      defaultColDef,
      rowData,
      onGridReady,
    };
  },
});

const app = createApp(VueExample);
app.mount("#app");

Column Chooser API Copy Link

The Column Chooser can be opened and closed through the Grid API.

Function

Show the column chooser.

ColumnMenuModule

Function

Hide the column chooser if visible.

ColumnMenuModule

The following example demonstrates opening and closing the Column Chooser through the Grid API.

main.ts

import {
  createApp,
  defineComponent,
  onBeforeMount,
  ref,
  shallowRef,
} from "vue";
import { AgGridVue } from "ag-grid-vue3";
import "./styles.css";
import {
  ClientSideRowModelModule,
  ColDef,
  ColGroupDef,
  GridApi,
  GridOptions,
  GridReadyEvent,
  ModuleRegistry,
  enableDevValidations,
} from "ag-grid-community";
import { ColumnMenuModule } from "ag-grid-enterprise";
import { IOlympicData } from "./interfaces";

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

ModuleRegistry.registerModules([ClientSideRowModelModule, ColumnMenuModule]);

const VueExample = defineComponent({
  template: `
        <div style="height: 100%">
                <div class="example-wrapper">
      <div class="button-group">
        <button v-on:click="showColumnChooser()">Show Column Chooser</button>
        <button v-on:click="hideColumnChooser()">Hide Column Chooser</button>
      </div>
      <ag-grid-vue
        style="width: 100%; height: 100%;"
        @grid-ready="onGridReady"
        :columnDefs="columnDefs"
        :defaultColDef="defaultColDef"
        :rowData="rowData"></ag-grid-vue>
      </div>
        </div>
    `,
  components: {
    "ag-grid-vue": AgGridVue,
  },
  setup(props) {
    const gridApi = shallowRef<GridApi<IOlympicData> | null>(null);
    const columnDefs = ref<ColDef[]>([
      { field: "athlete", minWidth: 200 },
      { field: "age" },
      { field: "country", minWidth: 200 },
      { field: "year" },
      { field: "sport", minWidth: 200 },
      { field: "gold" },
      { field: "silver" },
      { field: "bronze" },
      { field: "total" },
    ]);
    const defaultColDef = ref<ColDef>({
      flex: 1,
      minWidth: 100,
    });
    const rowData = ref<IOlympicData[]>(null);

    function showColumnChooser() {
      gridApi.value.showColumnChooser();
    }
    function hideColumnChooser() {
      gridApi.value.hideColumnChooser();
    }
    const onGridReady = (params: GridReadyEvent) => {
      gridApi.value = params.api;

      const updateData = (data) => (rowData.value = data);

      fetch("https://www.ag-grid.com/example-assets/olympic-winners.json")
        .then((resp) => resp.json())
        .then((data) => updateData(data));
    };

    return {
      gridApi,
      columnDefs,
      defaultColDef,
      rowData,
      onGridReady,
      showColumnChooser,
      hideColumnChooser,
    };
  },
});

const app = createApp(VueExample);
app.mount("#app");

styles.css

.example-wrapper {
    display: flex;
    flex-direction: column;
    height: 100%;
}

#myGrid {
    flex: 1 1 0px;
    width: 100%;
}

.button-group {
    padding-bottom: 4px;
    display: inline-block;
    font-family: Verdana, Geneva, Tahoma, sans-serif;
    font-size: 13px;
}

With the Legacy Tabbed Column Menu, a column selection panel is displayed within the columnsMenuTab instead of a separate dialog. It supports the same customisation options through columnChooserParams, but columns cannot be dragged to reorder them or to move them between sections.

Getting Started

AI Features

Layout & Styling

Charting

Core Features

Advanced Features

Vue Data GridColumn Chooser

Customising the Column Chooser Copy Link

Custom Column Labels Copy Link

Renderer Parameters Copy Link

Custom Column Layout Copy Link

Column Chooser API Copy Link

Legacy Tabbed Column Menu Copy Link