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.
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>
);
};
In previous versions of the grid, custom components were declared in an imperative way. See Migrating to Use reactiveCustomComponents for details on how to migrate to the current format.
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).
The active status of the item (is it currently hovered with the mouse, or navigated to via the keyboard). |
If the item is a sub menu, whether it is currently opened or closed. |
Callback that should be called every time the active status is updated (if providing custom behaviour). |
Level within the menu tree (starts at 0). |
Returns true if another sub menu is open. |
Open the sub menu for this item.
activateFirstItem If true, activate the first item in the sub menu.
|
Close the sub menu for this item. |
Close the entire menu. |
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}.
|
If this item is a sub menu, contains a list of menu item definitions |
Provide a custom menu item component. See Menu Item Component for framework specific implementation details.
|
Parameters to be passed to the custom menu item component specified in menuItem.
|
Name of the menu item. |
Set to true to display the menu item as disabled. |
Shortcut text displayed inside menu item. Setting this doesn’t actually create a keyboard shortcut binding.
|
Function that gets executed when item is chosen. |
Set to true to provide a check beside the option. |
The icon to display, either a DOM element or HTML string. |
CSS classes to apply to the menu item. |
Tooltip text to be displayed for the menu item. |
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.
|
The grid api. |
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.
Called when the item is selected, e.g. clicked or Enter is pressed. |
Configure the default grid behaviour for this item, including styling, and mouse and keyboard interactions.
Returns: true to use all default behaviour, false to use no default behaviour (equivalent to configureDefaults not being defined), or IMenuConfigParams to choose what default behaviour to use.
|
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:
Suppress the grid-provided tooltip on hover.
|
Suppress handling of click events. If true, the component will need to implement its own click event handler. The grid will no longer handle performing the action and opening the sub menu (if appropriate).
|
Suppress handling of mouse down events. |
Suppress handling of mouseenter and mouseleave events, If true, The grid will no longer update the active status of the menu item or open sub menus.
|
Suppress handling of keyboard events to select the current item. If true, the grid will not select the menu item on Enter or Space.
|
Suppress setting tabindex on the root element. If true, will need to set tabindex elsewhere for keyboard navigation to work.
|
Suppress setting Aria properties on the root element.
|
Suppress setting CSS classes on the root element. If true and mixing custom menu item components with grid-provided ones, will need to style with table display rules, as well as adding active and disabled styling.
|
Suppress focusing the root element when made active. If true, will need to handle keyboard navigation.
|
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.