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.
Implement this interface to provide a custom menu item.
interface IMenuItem {
// optional methods
// Configure the default grid behaviour for this item, including styling,
// and mouse and keyboard interactions.
// Return `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.
configureDefaults(): boolean | IMenuConfigParams;
// Called when the item is activated/deactivated, either via mouseover or keyboard navigation.
setActive(active: boolean): void;
// If the item has a sub menu, called when the sub menu is opened/closed.
setExpanded(expanded: boolean): void;
// Called when the item is selected, e.g. clicked or Enter is pressed.
select(): void;
}
To enable the default menu item behaviour, implement the configureDefaults method and return true (see Providing Custom Behaviour).
When a menu item is instantiated, the following will be made available on this.params:
Properties available on the IMenuItemParams<TData = any, TContext = any> interface.
Callback to let the menu know that the current item has become active. Required if updating the active status within the menu item.
|
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. |
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.