The column menu is launched from the grid header, and displays a list of menu items, along with the ability to select columns and display filters.
AG Grid Community does not have a menu, but can launch Column Filters if enabled (see Launching Filters for configuration details).
The following example shows the column menu:
- The Athlete column does not have filtering enabled, and only shows the main menu.
- The Age column has filtering enabled, and shows an additional filter icon. Open and apply a filter to see the behaviour.
- The Country column has filtering enabled with the floating filter. Open and apply a filter to see the behaviour.
- Right-clicking on the column headers will also display the column menu.
- Right-clicking in the empty space to the right of the column headers will display the column menu with options to choose/reset the columns.
Customising the Column Menu
How the column menu is launched from the header can be configured via the following column definition properties.
Set to true if no menu button should be shown for this column header. |
Set to true to not display the filter button in the column header.
Doesn't apply when columnMenu = 'legacy' . |
Set to true to not display the column menu when the column header is right-clicked.
Doesn't apply when columnMenu = 'legacy' . |
The column menu button can be hidden until moused over by the grid option suppressMenuHide
.
When true , the column menu button will always be shown.
When `false, the column menu button will only show when the mouse is over the column header.
If columnMenu = 'legacy' , this will default to false instead of true . |
The following example demonstrates different ways of customising the column menu:
- The Athlete column has a filter and the menu button suppressed, but still available via right-click.
- The Age column has a floating filter and the menu suppressed, but still available via right-click.
- The Country column has a filter and the header filter button suppressed.
- The Year column has a floating filter and the header filter button suppressed.
- The Sport column has no filter and the menu suppressed on right-click.
- The Gold column has no filter and the menu button suppressed, but still available via right-click
- The Silver column has a filter (with the header filter button suppressed), and the menu button suppressed but still available via right-click.
- The Bronze column has a floating filter and the menu button suppressed, but still available via right-click.
- The Total column has the menu button, header filter button and right-click menu suppressed.
Customising the Menu Items
The main menu list, by default, will show a set of items. You can adjust which of these items get displayed, or you can start from scratch and provide your own items. There are two ways to customise the menu items:
- Set
colDef.mainMenuItems
. This can either be a list of menu items, or a callback which is passed the list of default menu items. - Set the grid option
getMainMenuItems()
. This callback will be passed the list of default menu items as well as the column.
Note that colDef.mainMenuItems
will take priority over getMainMenuItems()
.
The menu item list should be a list with each item either a) a string or b) a MenuItemDef
description. Use 'string' to pick from built-in menu items (listed below) and use MenuItemDef
descriptions for your own menu items.
Customise the list of menu items available in the column menu. |
For customising the main 'column header' menu. |
Built-In Menu Items
The following is a list of all the default built-in menu items with the rules about when they are shown.
sortAscending
: Sort the column in ascending order. Not shown whencolumnMenu = 'legacy'
or the column is already sorted in ascending order.sortDescending
: Sort the column in descending order. Not shown whencolumnMenu = 'legacy'
or the column is already sorted in descending order.sortUnSort
: Clear the sort on the column. Not shown whencolumnMenu = 'legacy'
or the column is not sorted.columnFilter
: Show the column filter. Not shown whencolumnMenu = 'legacy'
, a filter is not enabled, or the header filter button or floating filter button are displayed.columnChooser
: Show the column chooser. Not shown whencolumnMenu = 'legacy'
.pinSubMenu
: Sub-menu for pinning. Always shown.pinSubMenu
: Sub-menu for pinning. Always shown.valueAggSubMenu
: Sub-menu for value aggregation. Always shown.autoSizeThis
: Auto-size the current column. Always shown.autoSizeAll
: Auto-size all columns. Always shown.rowGroup
: Group by this column. Only shown if column is not grouped. Note this will appear once there is row grouping.rowUnGroup
: Un-group by this column. Only shown if column is grouped. Note this will appear once there is row grouping.resetColumns
: Reset column details. Always shown.expandAll
: Expand all groups. Only shown if grouping by at least one column.contractAll
: Collapse all groups. Only shown if grouping by at least one column.
The defaultItems
list will change on different calls, depending on, for example, which columns are currently used for grouping.
If you do not override the list of menu items, then the items displayed will be based on the rules above.
Menu Item Separators
Menu items can be grouped together by adding separators between groups. Separators are defined by the string value 'separator'
. For example, you could add menu item separators as follows:
menuItems.push('separator')
Custom Menu Item Components
In addition to the provided menu items, it is also possible to create custom menu item components.
For more details, refer to the section: Custom Menu Item Components.
Example: Customising the Menu Items
The following example demonstrates the colDef.mainMenuItems
property:
- The Athlete column shows the list of built-in items.
- The Age column appends custom items to the list of built-in items.
- The Country column provides custom items and adds one built-in default item.
- The Year column trims down the default items by removing values.
Customising the Column Chooser
The behaviour and appearance of the Columns Menu tab can be customised by supplying ColumnChooserParams
to the column definition: colDef.columnChooserParams
. Note that all of the properties are initially set to false
.
Properties available on the ColumnChooserParams
interface.
To suppress updating the layout of columns as they are rearranged in the grid |
To suppress Column Filter section |
To suppress Select / Un-select all widget |
To suppress Expand / Collapse all widget |
By default, column groups start expanded. Pass true to default to contracted groups |
Custom Columns Panel layout |
The following example demonstrates all of the above column chooser properties except columnLayout which will be covered later on. Note the following:
- Launch the column chooser by selecing
Choose Columns
from any of the column menus. - The column chooser when launched from any column has been configured to ignore column moves in the grid by setting
suppressSyncLayoutWithGrid=true
on the default column definition. - The Name column chooser doesn't show the top filter section as
suppressColumnFilter
,suppressColumnSelectAll
andsuppressColumnExpandAll
are all set totrue
. - The Age column chooser shows the group columns in a collapsed state as
contractColumnSelection
is set totrue
.
Custom Column Layout
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 with the grid when columns are moved.
However, a custom column layout can be provided using the columnLayout property in the colDef.columnChooserParams
.
// original column definitions supplied to the grid
const [columnDefs, setColumnDefs] = useState([
{
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' }
]);
<AgGridReact columnDefs={columnDefs} />
When providing a custom columns layout by setting the columnLayout property, the suppressSyncLayoutWithGrid
property will automatically set to true. This means that reordering the columns in the grid will not reorder the columns in the list shown in columns menu tab.
The following example demonstrates providing custom column layouts in the column chooser via the columnLayout property. Note the following:
- Open the column chooser for the Name column and note it shows the custom column order as specified in its
columnLayout
. - Open the column chooser for the Age column and note it shows the actual column order shown in the grid.
- Reorder columns in the grid - drag the Age column and drop it on the left of the Name column.
- Open the column chooser for the Age column and note that the column layout now shows the Age column before the Name column.
- Open the column chooser for the Name column and note that the column layout still shows the Name column followed by the Age column (custom column layout is not synchronized with the grid column order).
Column Menu API / Events
The gridApi
has the following methods that can be used to interact with the column menu:
Show the column chooser. |
Show the filter for the provided column. |
Show the column menu for the provided column. |
Hides any visible context menu or column menu. |
Hide the column chooser if visible. |
The following column menu event is emitted by the grid:
The column menu visibility has changed. Fires twice if switching between tabs - once with the old tab and once with the new tab. |
The following example demonstrates the column menu API and events (by clicking the buttons outside the grid):
Menu Popup
The column menu is displayed inside a popup, which can be further configured.
Repositioning the Popup
If not happy with the position of the popup, you can override its position using the postProcessPopup(params)
callback. This gives you the popup HTML element so you can change its position should you wish to.
Allows user to process popups after they are created. Applications can use this if they want to, for example, reposition the popup. |
The following example demonstrates using postProcessPopup()
to move the Age column menu down by 25 pixels.
Popup Parent
Under most scenarios, the menu will fit inside the grid. However if the grid is small and / or the menu is very large, then the menu will not fit inside the grid and it will be clipped. This will lead to a bad user experience.
To fix this, you should set the Popup Parent property.
Legacy Tabbed Column Menu
The menu can also be displayed in the legacy tabbed format with three panels by setting the grid option columnMenu = 'legacy'
. If you want to change the order in which panels are shown, or hide them, you can specify the property menuTabs
in the colDef
.
The property menuTabs
is an array of strings. The valid values are: 'filterMenuTab'
, 'generalMenuTab'
and 'columnsMenuTab'
.
generalMenuTab
: Include to show the main panel.filterMenuTab
: Include to show the filter panel.columnsMenuTab
: Include to show the column chooser panel.
The order of the menu tabs shown in the menu will match the order you specify in this array.
If you don't specify a menuTabs
for a colDef
the default is: ['generalMenuTab', 'filterMenuTab', 'columnsMenuTab']
The following example demonstrates the default tabbed menu:
- The Athlete column shows the default tabs.
- The Age column changes the order of the tabs to
['filterMenuTab', 'generalMenuTab', 'columnsMenuTab']
- The Country column changes the order of the tabs to
['filterMenuTab', 'columnsMenuTab']
. Note that the'generalMenuTab'
is suppressed. - The Year column changes the tabs to
['generalMenuTab']
. Note that the'filterMenuTab'
and'columnsMenuTab'
are suppressed. - The Sport column hides the menu by suppressing all the menuTabs that can be shown:
[]
.