Menu Item Components allow you to customise the menu items shown in the Column Menu and Context Menu. Use these when the provided menu items do not meet your requirements.
The following example demonstrates a custom menu item component in both the column menu and context menu.
To configure custom menu items, first enable the grid option reactiveCustomComponents.
export default ({ name, icon, shortcut, subMenu }) => {
useGridMenuItem(() => {
configureDefaults: () => true;
});
return (
<div>
<span className="ag-menu-option-part ag-menu-option-icon">{icon}</span>
<span className="ag-menu-option-part ag-menu-option-text">{name}</span>
<span className="ag-menu-option-part ag-menu-option-shortcut">{shortcut}</span>
<span className="ag-menu-option-part ag-menu-option-popup-pointer">{subMenu ? '>': ''}</span>
</div>
);
};
Enabling reactiveCustomComponents affects all custom components. If you have custom components built in an imperative way instead of setting the reactiveCustomComponents option, they may need to be rebuilt to take advantage of the new features that reactiveCustomComponents offers. Using custom components built in an imperative way is now deprecated, and in AG Grid v32 the reactiveCustomComponents option will be true by default. See Migrating to Use reactiveCustomComponents. For the legacy imperative documentation, see Imperative Menu Item Component.
To enable the default menu item behaviour, pass the callback configureDefaults to the useGridMenuItem hook and return true (see Providing Custom Behaviour).
Custom Menu Item Parameters
Menu Item Props
The following props are passed to the custom menu item components (CustomMenuItemProps interface).
active | The active status of the item (is it currently hovered with the mouse, or navigated to via the keyboard). |
expanded | If the item is a sub menu, whether it is currently opened or closed. |
on | Callback that should be called every time the active status is updated (if providing custom behaviour). |
level | Level within the menu tree (starts at 0). |
is | Returns true if another sub menu is open. |
open | Open the sub menu for this item.
activateFirstItem If true, activate the first item in the sub menu.
|
close | Close the sub menu for this item. |
close | Close the entire menu. |
update | Updates the grid-provided tooltip this component.
tooltip The value to be displayed by the tooltip
shouldDisplayTooltip A function returning a boolean that allows the tooltip to be displayed conditionally. This option does not work when enableBrowserTooltips={true}.
|
sub | If this item is a sub menu, contains a list of menu item definitions |
menu | Provide a custom menu item component. See Menu Item Component for framework specific implementation details.
|
menu | Parameters to be passed to the custom menu item component specified in menuItem.
|
name | Name of the menu item. |
disabled | Set to true to display the menu item as disabled. |
shortcut | Shortcut text displayed inside menu item. Setting this doesn’t actually create a keyboard shortcut binding.
|
action | Function that gets executed when item is chosen. |
checked | Set to true to provide a check beside the option. |
icon | The icon to display, either a DOM element or HTML string. |
css | CSS classes to apply to the menu item. |
tooltip | Tooltip text to be displayed for the menu item. |
suppress | If true, will keep the menu open when the item is selected. Note that if this item has a sub menu, it will always remain open regardless of this property.
|
api | The grid api. |
context | Application context as set on gridOptions.context. |
Menu Item Callbacks
The following callbacks can be passed to the useGridMenuItem hook (CustomMenuItemCallbacks interface). All the callbacks are optional, and the hook only needs to be used if callbacks are provided.
Default Styling
In order for the menu to size dynamically, the default styling is provided via display: table. This means that if custom menu item components are used alongside grid-provided menu items, then they must adhere to a certain structure, or the grid styles must be overridden.
The default structure consists of a parent element with display: table-row, and four children with display: table-cell. This can be seen in the example above. If using configureDefaults and not suppressing root styling, the grid will automatically add the correct styling to the parent element.
This format can be overridden by Styling the Menu, notably ag-menu-list, ag-menu-option, ag-menu-option-part, ag-menu-separator and ag-menu-separator-part. This is demonstrated in the Providing Custom Behaviour example below.
Providing Custom Behaviour
As described above, the easiest way to configure the behaviour of a custom menu item is returning true from configureDefaults.
If this is not done, then the custom menu item will need to implement all of the required behaviour itself.
It is also possible to disable certain parts of the behaviour by returning an object of type IMenuConfigParams from configureDefaults:
The following example demonstrates providing custom behaviour (in the column menu only) by including a filter as a menu item. To allow for a full-width custom menu item alongside grid-provided ones, the default menu styling is overridden (see Default Styling).
Note this shows a column filter in the custom menu item as an example for how complex items can be added. It is not meant to be used as a complete solution.