API reference for Angular CDK menu
import {CdkMenuModule} from '@angular/cdk/menu';
Services
ContextMenuTracker
Tracks the last open context menu trigger across the entire application.
Methods
update | |
---|---|
Close the previous open context menu and set the given one as being open. |
|
Parameters | |
trigger CdkContextMenuTrigger
|
The trigger for the currently open Context Menu. |
MenuStack
MenuStack allows subscribers to listen for close events (when a MenuStackItem is popped off
of the stack) in order to perform closing actions. Upon the MenuStack being empty it emits
from the empty
observable specifying the next focus action which the listener should perform
as requested by the closer.
Properties
Name | Description |
---|---|
|
Observable which emits the MenuStackItem which has been requested to close. |
|
Observable which emits when the MenuStack is empty after popping off the last element. It emits a FocusNext event which specifies the action the closer has requested the listener perform. |
|
Observable which emits whether any menu in the menu stack has focus. |
|
The ID of this menu stack. |
Methods
close | |
---|---|
Pop items off of the stack up to and including |
|
Parameters | |
lastItem MenuStackItem
|
the last item to pop off the stack. |
options? CloseOptions
|
Options that configure behavior on close. |
closeAll | |
---|---|
Pop off all MenuStackItems and emit each one on the |
|
Parameters | |
options? CloseOptions
|
Options that configure behavior on close. |
closeSubMenuOf | |
---|---|
Pop items off of the stack up to but excluding |
|
Parameters | |
lastItem MenuStackItem
|
the element which should be left on the stack |
hasInlineMenu | |
---|---|
Whether the menu stack is associated with an inline menu. |
static
inline
|
|
---|---|
Creates a menu stack that originates from an inline menu. |
|
Parameters | |
orientation "horizontal" | "vertical"
|
|
inlineMenuOrientation | |
---|---|
The orientation of the associated inline menu. |
isEmpty | |
---|---|
Return true if this stack is empty. |
length | |
---|---|
Return the length of the stack. |
peek | |
---|---|
Get the top most element on the stack. |
|
Returns | |
MenuStackItem | undefined
|
|
push | |
---|---|
Adds an item to the menu stack. |
|
Parameters | |
menu MenuStackItem
|
the MenuStackItem to put on the stack. |
setHasFocus | |
---|---|
Sets whether the menu stack contains the focused element. |
|
Parameters | |
hasFocus boolean
|
|
TargetMenuAim
TargetMenuAim predicts if a user is moving into a submenu. It calculates the trajectory of the user's mouse movement in the current menu to determine if the mouse is moving towards an open submenu.
The determination is made by calculating the slope of the users last NUM_POINTS moves where each pair of points determines if the trajectory line points into the submenu. It uses consensus approach by checking if at least NUM_POINTS / 2 pairs determine that the user is moving towards to submenu.
Methods
initialize | |
---|---|
Set the Menu and its PointerFocusTracker. |
|
Parameters | |
menu Menu
|
The menu that this menu aim service controls. |
pointerTracker PointerFocusTracker<FocusableElement & Toggler>
|
The |
toggle | |
---|---|
Calls the |
|
Parameters | |
doToggle () => void
|
the function called when the user is not moving towards the submenu. |
Directives
CdkMenuBar
extends
CdkMenuBase
Directive applied to an element which configures it as a MenuBar by setting the appropriate role, aria attributes, and accessible keyboard and mouse handling logic. The component that this directive is applied to should contain components marked with CdkMenuItem.
Selector: [cdkMenuBar]
Exported as: cdkMenuBarProperties
Name | Description |
---|---|
@Input()
|
The id of the menu's host element. |
|
Whether the menu is displayed inline (i.e. always present vs a conditional popup that the user triggers with a trigger element). |
|
All child MenuItem elements nested in this Menu. |
|
The stack of menus this menu belongs to. |
|
The menu's native DOM host element. |
|
The direction items in the menu flow. |
Methods
focusFirstItem | |
---|---|
Place focus on the first MenuItem in the menu and set the focus origin. |
|
Parameters | |
focusOrigin FocusOrigin = 'program'
|
The origin input mode of the focus event. |
focusLastItem | |
---|---|
Place focus on the last MenuItem in the menu and set the focus origin. |
|
Parameters | |
focusOrigin FocusOrigin = 'program'
|
The origin input mode of the focus event. |
CdkMenu
extends
CdkMenuBase
Directive which configures the element as a Menu which should contain child elements marked as CdkMenuItem or CdkMenuGroup. Sets the appropriate role and aria-attributes for a menu and contains accessible keyboard and mouse handling logic.
It also acts as a RadioGroup for elements marked with role menuitemradio
.
Selector: [cdkMenu]
Exported as: cdkMenuProperties
Name | Description |
---|---|
@Input()
|
The id of the menu's host element. |
@Output()
|
Event emitted when the menu is closed. |
|
Whether the menu is displayed inline (i.e. always present vs a conditional popup that the user triggers with a trigger element). |
|
All child MenuItem elements nested in this Menu. |
|
The stack of menus this menu belongs to. |
|
The menu's native DOM host element. |
|
The direction items in the menu flow. |
Methods
focusFirstItem | |
---|---|
Place focus on the first MenuItem in the menu and set the focus origin. |
|
Parameters | |
focusOrigin FocusOrigin = 'program'
|
The origin input mode of the focus event. |
focusLastItem | |
---|---|
Place focus on the last MenuItem in the menu and set the focus origin. |
|
Parameters | |
focusOrigin FocusOrigin = 'program'
|
The origin input mode of the focus event. |
CdkMenuBase
extends
CdkMenuGroup
Abstract directive that implements shared logic common to all menus. This class can be extended to create custom menu types.
Properties
Name | Description |
---|---|
@Input()
|
The id of the menu's host element. |
|
Emits when the MenuBar is destroyed. |
|
The directionality (text direction) of the current page. |
|
Whether the menu is displayed inline (i.e. always present vs a conditional popup that the user triggers with a trigger element). |
|
All child MenuItem elements nested in this Menu. |
|
Handles keyboard events for the menu. |
|
The menu aim service used by this menu. |
|
The stack of menus this menu belongs to. |
|
The menu's native DOM host element. |
|
|
|
The direction items in the menu flow. |
|
Tracks the users mouse movements over the menu. |
|
The Menu Item which triggered the open submenu. |
Methods
closeOpenMenu | |
---|---|
Close the open menu if the current active item opened the requested MenuStackItem. |
|
Parameters | |
menu MenuStackItem
|
The menu requested to be closed. |
options? { focusParentTrigger?: boolean; }
|
Options to configure the behavior on close.
|
focusFirstItem | |
---|---|
Place focus on the first MenuItem in the menu and set the focus origin. |
|
Parameters | |
focusOrigin FocusOrigin = 'program'
|
The origin input mode of the focus event. |
focusLastItem | |
---|---|
Place focus on the last MenuItem in the menu and set the focus origin. |
|
Parameters | |
focusOrigin FocusOrigin = 'program'
|
The origin input mode of the focus event. |
CdkMenuItem
Directive which provides the ability for an element to be focused and navigated to using the keyboard when residing in a CdkMenu, CdkMenuBar, or CdkMenuGroup. It performs user defined behavior when clicked.
Selector: [cdkMenuItem]
Exported as: cdkMenuItemProperties
Name | Description |
---|---|
@Input({ alias: 'cdkMenuItemDisabled', transform: booleanAttribute })
|
Whether the CdkMenuItem is disabled - defaults to false |
@Input('cdkMenuitemTypeaheadLabel')
|
The text used to locate this item during menu typeahead. If not specified,
the |
@Output('cdkMenuItemTriggered')
|
If this MenuItem is a regular MenuItem, outputs when it is triggered by a keyboard or mouse event. |
|
Whether the item should close the menu if triggered by the spacebar. |
|
Emits when the menu item is destroyed. |
|
Whether the menu item opens a menu. |
Methods
focus | |
---|---|
Place focus on the element. |
getLabel | |
---|---|
Get the label for this element which is required by the FocusableOption interface. |
|
Returns | |
string
|
|
getMenu | |
---|---|
Get a reference to the rendered Menu if the Menu is open and it is visible in the DOM. |
|
Returns | |
Menu | undefined
|
the menu if it is open, otherwise undefined. |
getMenuTrigger | |
---|---|
Get the CdkMenuTrigger associated with this element. |
|
Returns | |
CdkMenuTrigger | null
|
|
isMenuOpen | |
---|---|
Return true if this MenuItem has an attached menu and it is open. |
trigger | |
---|---|
If the menu item is not disabled and the element does not have a menu trigger attached, emit on the cdkMenuItemTriggered emitter and close all open menus. |
|
Parameters | |
options? { keepOpen: boolean; }
|
Options the configure how the item is triggered
|
CdkMenuItemCheckbox
extends
CdkMenuItemSelectable
A directive providing behavior for the "menuitemcheckbox" ARIA role, which behaves similarly to a conventional checkbox.
Selector: [cdkMenuItemCheckbox]
Exported as: cdkMenuItemCheckboxProperties
Name | Description |
---|---|
@Input({ alias: 'cdkMenuItemChecked', transform: booleanAttribute })
|
Whether the element is checked |
@Input({ alias: 'cdkMenuItemDisabled', transform: booleanAttribute })
|
Whether the CdkMenuItem is disabled - defaults to false |
@Input('cdkMenuitemTypeaheadLabel')
|
The text used to locate this item during menu typeahead. If not specified,
the |
@Output('cdkMenuItemTriggered')
|
If this MenuItem is a regular MenuItem, outputs when it is triggered by a keyboard or mouse event. |
|
Whether the menu item opens a menu. |
Methods
focus | |
---|---|
Place focus on the element. |
getLabel | |
---|---|
Get the label for this element which is required by the FocusableOption interface. |
|
Returns | |
string
|
|
getMenu | |
---|---|
Get a reference to the rendered Menu if the Menu is open and it is visible in the DOM. |
|
Returns | |
Menu | undefined
|
the menu if it is open, otherwise undefined. |
getMenuTrigger | |
---|---|
Get the CdkMenuTrigger associated with this element. |
|
Returns | |
CdkMenuTrigger | null
|
|
isMenuOpen | |
---|---|
Return true if this MenuItem has an attached menu and it is open. |
trigger | |
---|---|
Toggle the checked state of the checkbox. |
|
Parameters | |
options? { keepOpen: boolean; }
|
Options the configure how the item is triggered
|
CdkMenuItemRadio
extends
CdkMenuItemSelectable
A directive providing behavior for the "menuitemradio" ARIA role, which behaves similarly to
a conventional radio-button. Any sibling CdkMenuItemRadio
instances within the same CdkMenu
or CdkMenuGroup
comprise a radio group with unique selection enforced.
Selector: [cdkMenuItemRadio]
Exported as: cdkMenuItemRadioProperties
Name | Description |
---|---|
@Input({ alias: 'cdkMenuItemChecked', transform: booleanAttribute })
|
Whether the element is checked |
@Input({ alias: 'cdkMenuItemDisabled', transform: booleanAttribute })
|
Whether the CdkMenuItem is disabled - defaults to false |
@Input('cdkMenuitemTypeaheadLabel')
|
The text used to locate this item during menu typeahead. If not specified,
the |
@Output('cdkMenuItemTriggered')
|
If this MenuItem is a regular MenuItem, outputs when it is triggered by a keyboard or mouse event. |
|
Whether the menu item opens a menu. |
Methods
focus | |
---|---|
Place focus on the element. |
getLabel | |
---|---|
Get the label for this element which is required by the FocusableOption interface. |
|
Returns | |
string
|
|
getMenu | |
---|---|
Get a reference to the rendered Menu if the Menu is open and it is visible in the DOM. |
|
Returns | |
Menu | undefined
|
the menu if it is open, otherwise undefined. |
getMenuTrigger | |
---|---|
Get the CdkMenuTrigger associated with this element. |
|
Returns | |
CdkMenuTrigger | null
|
|
isMenuOpen | |
---|---|
Return true if this MenuItem has an attached menu and it is open. |
trigger | |
---|---|
Toggles the checked state of the radio-button. |
|
Parameters | |
options? { keepOpen: boolean; }
|
Options the configure how the item is triggered
|
CdkMenuTrigger
extends
CdkMenuTriggerBase
A directive that turns its host element into a trigger for a popup menu. It can be combined with cdkMenuItem to create sub-menus. If the element is in a top level MenuBar it will open the menu on click, or if a sibling is already opened it will open on hover. If it is inside of a Menu it will open the attached Submenu on hover regardless of its sibling state.
Selector: [cdkMenuTriggerFor]
Exported as: cdkMenuTriggerForProperties
Name | Description |
---|---|
@Input(cdkMenuTriggerData)
|
Context data to be passed along to the menu template |
@Input(cdkMenuPosition)
|
A list of preferred menu positions to be used when constructing the
|
@Input(cdkMenuTriggerFor)
|
Template reference variable to the menu this trigger opens |
@Output( cdkMenuClosed)
|
Emits when the attached menu is requested to close |
@Output( cdkMenuOpened)
|
Emits when the attached menu is requested to open |
|
The DI injector for this component. |
Methods
close | |
---|---|
Close the opened menu. |
getMenu | |
---|---|
Get a reference to the rendered Menu if the Menu is open and rendered in the DOM. |
|
Returns | |
Menu | undefined
|
|
isOpen | |
---|---|
Whether the attached menu is open. |
open | |
---|---|
Open the attached menu. |
registerChildMenu | |
---|---|
Registers a child menu as having been opened by this trigger. |
|
Parameters | |
child Menu
|
|
toggle | |
---|---|
Toggle the attached menu. |
CdkMenuGroup
A grouping container for CdkMenuItemRadio
instances, similar to a role="radiogroup"
element.
Selector: [cdkMenuGroup]
Exported as: cdkMenuGroup
CdkMenuItemSelectable
extends
CdkMenuItem
Base class providing checked state for selectable MenuItems.
Properties
Name | Description |
---|---|
@Input({ alias: 'cdkMenuItemChecked', transform: booleanAttribute })
|
Whether the element is checked |
@Input({ alias: 'cdkMenuItemDisabled', transform: booleanAttribute })
|
Whether the CdkMenuItem is disabled - defaults to false |
@Input('cdkMenuitemTypeaheadLabel')
|
The text used to locate this item during menu typeahead. If not specified,
the |
@Output('cdkMenuItemTriggered')
|
If this MenuItem is a regular MenuItem, outputs when it is triggered by a keyboard or mouse event. |
|
Whether the item should close the menu if triggered by the spacebar. |
|
Whether the menu item opens a menu. |
Methods
focus | |
---|---|
Place focus on the element. |
getLabel | |
---|---|
Get the label for this element which is required by the FocusableOption interface. |
|
Returns | |
string
|
|
getMenu | |
---|---|
Get a reference to the rendered Menu if the Menu is open and it is visible in the DOM. |
|
Returns | |
Menu | undefined
|
the menu if it is open, otherwise undefined. |
getMenuTrigger | |
---|---|
Get the CdkMenuTrigger associated with this element. |
|
Returns | |
CdkMenuTrigger | null
|
|
isMenuOpen | |
---|---|
Return true if this MenuItem has an attached menu and it is open. |
trigger | |
---|---|
If the menu item is not disabled and the element does not have a menu trigger attached, emit on the cdkMenuItemTriggered emitter and close all open menus. |
|
Parameters | |
options? { keepOpen: boolean; }
|
Options the configure how the item is triggered
|
CdkContextMenuTrigger
extends
CdkMenuTriggerBase
A directive that opens a menu when a user right-clicks within its host element. It is aware of nested context menus and will trigger only the lowest level non-disabled context menu.
Selector: [cdkContextMenuTriggerFor]
Exported as: cdkContextMenuTriggerForProperties
Name | Description |
---|---|
@Input({ alias: 'cdkContextMenuDisabled', transform: booleanAttribute })
|
Whether the context menu is disabled. |
@Input(cdkContextMenuTriggerData)
|
Context data to be passed along to the menu template |
@Input(cdkContextMenuPosition)
|
A list of preferred menu positions to be used when constructing the
|
@Input(cdkContextMenuTriggerFor)
|
Template reference variable to the menu this trigger opens |
@Output( cdkContextMenuClosed)
|
Emits when the attached menu is requested to close |
@Output( cdkContextMenuOpened)
|
Emits when the attached menu is requested to open |
|
The DI injector for this component. |
Methods
close | |
---|---|
Close the currently opened context menu. |
isOpen | |
---|---|
Whether the attached menu is open. |
open | |
---|---|
Open the attached menu at the specified location. |
|
Parameters | |
coordinates ContextMenuCoordinates
|
where to open the context menu |
registerChildMenu | |
---|---|
Registers a child menu as having been opened by this trigger. |
|
Parameters | |
child Menu
|
|
CdkMenuTriggerBase
Abstract directive that implements shared logic common to all menu triggers. This class can be extended to create custom menu trigger types.
Properties
Name | Description |
---|---|
|
The child menu opened by this trigger. |
|
Emits when the attached menu is requested to close |
|
Emits when this trigger is destroyed. |
|
The DI injector for this component. |
|
Context data to be passed along to the menu template |
|
A list of preferred menu positions to be used when constructing the
|
|
Function used to configure the scroll strategy for the menu. |
|
The menu stack in which this menu resides. |
|
Template reference variable to the menu this trigger opens |
|
Emits when the attached menu is requested to open |
|
A reference to the overlay which manages the triggered menu |
|
Emits when the outside pointer events listener on the overlay should be stopped. |
|
The view container ref for this component |
Methods
getMenuContentPortal | |
---|---|
Get the portal to be attached to the overlay which contains the menu. Allows for the menu content to change dynamically and be reflected in the application. |
isElementInsideMenuStack | |
---|---|
Whether the given element is inside the scope of this trigger's menu stack. |
|
Parameters | |
element Element
|
The element to check. |
isOpen | |
---|---|
Whether the attached menu is open. |
registerChildMenu | |
---|---|
Registers a child menu as having been opened by this trigger. |
|
Parameters | |
child Menu
|
|
CdkTargetMenuAim
CdkTargetMenuAim is a provider for the TargetMenuAim service. It can be added to an
element with either the cdkMenu
or cdkMenuBar
directive and child menu items.
Selector: [cdkTargetMenuAim]
Exported as: cdkTargetMenuAim
Classes
PointerFocusTracker
PointerFocusTracker keeps track of the currently active item under mouse focus. It also has observables which emit when the users mouse enters and leaves a tracked element.
Properties
Name | Description |
---|---|
|
The element currently under mouse focus. |
|
Emits when an element is moused into. |
|
Emits when an element is moused out. |
|
The element previously under mouse focus. |
Methods
destroy | |
---|---|
Stop the managers listeners. |
Interfaces
FocusableElement
Item to track for mouse focus events.
MenuStackItem
A single item (menu) in the menu stack.
Properties
Name | Description |
---|---|
|
A reference to the menu stack this menu stack item belongs to. |
CloseOptions
Options that can be provided to the close or closeAll methods.
Properties
Name | Description |
---|---|
|
The element to focus next if the close operation causes the menu stack to become empty. |
|
Whether to focus the parent trigger after closing the menu. |
MenuStackCloseEvent
Event dispatched when a menu is closed.
Properties
Name | Description |
---|---|
|
Whether to focus the parent trigger after closing the menu. |
|
The menu being closed. |
Menu
Interface which specifies Menu operations and used to break circular dependency issues
Properties
Name | Description |
---|---|
|
The id of the menu's host element. |
|
The menu's native DOM host element. |
|
The direction items in the menu flow. |
Methods
focusFirstItem | |
---|---|
Place focus on the first MenuItem in the menu. |
|
Parameters | |
focusOrigin FocusOrigin
|
|
focusLastItem | |
---|---|
Place focus on the last MenuItem in the menu. |
|
Parameters | |
focusOrigin FocusOrigin
|
|
MenuAim
MenuAim is responsible for determining if a sibling menuitem's menu should be closed when a Toggler item is hovered into. It is up to the hovered in item to call the MenuAim service in order to determine if it may perform its close actions.
Methods
initialize | |
---|---|
Set the Menu and its PointerFocusTracker. |
|
Parameters | |
menu Menu
|
The menu that this menu aim service controls. |
pointerTracker PointerFocusTracker<FocusableElement & Toggler>
|
The |
toggle | |
---|---|
Calls the |
|
Parameters | |
doToggle () => void
|
the function called when the user is not moving towards the submenu. |
Toggler
An element which when hovered over may open or close a menu.
Methods
getMenu | |
---|---|
Gets the open menu, or undefined if no menu is open. |
|
Returns | |
Menu | undefined
|
|
Type aliases
ContextMenuCoordinates
The coordinates where the context menu should open.
type ContextMenuCoordinates = {
x: number;
y: number;
};
Constants
MENU_TRIGGER
Injection token used for an implementation of MenuStack.
const MENU_TRIGGER: InjectionToken<CdkMenuTriggerBase>;
MENU_SCROLL_STRATEGY
Injection token used to configure the behavior of the menu when the page is scrolled.
const MENU_SCROLL_STRATEGY: InjectionToken<() => ScrollStrategy>;
MENU_STACK
Injection token used for an implementation of MenuStack.
const MENU_STACK: InjectionToken<MenuStack>;
PARENT_OR_NEW_MENU_STACK_PROVIDER
Provider that provides the parent menu stack, or a new menu stack if there is no parent one.
const PARENT_OR_NEW_MENU_STACK_PROVIDER: { provide: InjectionToken<MenuStack>; deps: Optional[][]; useFactory: (parentMenuStack?: MenuStack) => MenuStack; };
PARENT_OR_NEW_INLINE_MENU_STACK_PROVIDER
Provider that provides the parent menu stack, or a new inline menu stack if there is no parent one.
const PARENT_OR_NEW_INLINE_MENU_STACK_PROVIDER: (orientation: "horizontal" | "vertical") => { provide: InjectionToken<MenuStack>; deps: Optional[][]; useFactory: (parentMenuStack?: MenuStack) => MenuStack; };
CDK_MENU
Injection token used to return classes implementing the Menu interface
const CDK_MENU: InjectionToken<Menu>;
MENU_AIM
Injection token used for an implementation of MenuAim.
const MENU_AIM: InjectionToken<MenuAim>;