Menu Widgetversion added: 1.9
Description: Themeable menu with mouse and keyboard interactions for navigation.
A menu can be created from any valid markup as long as the elements have a strict parent/child relationship. The most commonly used element is the unordered list (<ul>
). Additionally, the contents of each menu item must be wrapped with a block-level DOM element. In the example below <div>
elements are used as wrappers:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
|
|
If you use a structure other than <ul>
/<li>
, including using the same element for the menu and the menu items, use the menus
option to specify a way to differentiate the two elements, e.g., menus: "div.menuElement"
.
Any menu item can be disabled by adding the ui-state-disabled
class to that element.
Icons
To add icons to the menu, include them in the markup:
1
2
3
4
5
|
|
Menu automatically adds the necessary padding to items without icons.
Dividers
Divider elements can be created by including menu items that contain only spaces and/or dashes:
1
2
3
4
5
6
7
8
9
|
|
Keyboard interaction
-
ENTER
/SPACE
: Invoke the focused menu item's action, which may be opening a submenu. -
UP
: Move focus to the previous menu item. -
DOWN
: Move focus to the next menu item. -
RIGHT
: Open the submenu, if available. -
LEFT
: Close the current submenu and move focus to the parent menu item. If not in a submenu, do nothing. -
ESCAPE
: Close the current submenu and move focus to the parent menu item. If not in a submenu, do nothing.
Typing a letter moves focus to the first item whose title starts with that character. Repeating the same character cycles through matching items. Typing more characters within the one second timer matches those characters.
Disabled items can receive keyboard focus, but do not allow any other interaction.
Theming
The menu widget uses the jQuery UI CSS framework to style its look and feel. If menu specific styling is needed, the following CSS class names can be used for overrides or as keys for the classes
option:
-
ui-menu
: The outer container of the menu, as well as any nested submenu. This top-level element will additionally have aui-menu-icons
class if the menu contains icons.-
ui-menu-item
: The container for individual menu items. This contains the element for the item's text itself as well as the element for submenus.-
ui-menu-item-wrapper
: The wrapper element inside each individual menu item, containting the text content and the icon indicating submenus.-
ui-menu-icon
: The submenu icons set via theicons
option.
-
-
-
ui-menu-divider
: Divider elements between menu items.
-
Dependencies
Additional Notes:
- This widget requires some functional CSS, otherwise it won't work. If you build a custom theme, use the widget's specific CSS file as a starting point.
Options
classes
{}
Specify additional classes to add to the widget's elements. Any of classes specified in the Theming section can be used as keys to override their value. To learn more about this option, check out the learn article about the classes
option.
Initialize the menu with the classes
option specified, changing the theming for the ui-menu
class:
1
2
3
4
5
|
|
Get or set a property of the classes
option, after initialization, here reading and changing the theming for the ui-menu
class:
1
2
3
4
5
|
|
disabled
false
true
.Initialize the menu with the disabled
option specified:
1
2
3
|
|
Get or set the disabled
option, after initialization:
1
2
3
4
5
|
|
icons
|
Initialize the menu with the icons
option specified:
1
2
3
|
|
Get or set the icons
option, after initialization:
1
2
3
4
5
|
|
items
"> *"
Selector for the elements that serve as the menu items.
items
option should not be changed after initialization.Initialize the menu with the items
option specified:
1
2
3
|
|
Get the items
option, after initialization:
1
2
|
|
position
{ my: "left top", at: "right top" }
of
option defaults to the parent menu item, but you can specify another element to position against. You can refer to the jQuery UI Position utility for more details about the various options.Initialize the menu with the position
option specified:
1
2
3
|
|
Get or set the position
option, after initialization:
1
2
3
4
5
|
|
role
"menu"
Customize the ARIA roles used for the menu and menu items. The default uses "menuitem"
for items. Setting the role
option to "listbox"
will use "option"
for items. If set to null
, no roles will be set, which is useful if the menu is being controlled by another element that is maintaining focus.
role
option should not be changed after initialization. Existing (sub)menus and menu items will not be updated.Initialize the menu with the role
option specified:
1
2
3
|
|
Get the role
option, after initialization:
1
2
|
|
Methods
blur( [event ] )Returns: jQuery (plugin only)
blur
event.
-
eventType: EventWhat triggered the menu to blur.
Invoke the blur method:
1
|
|
collapse( [event ] )Returns: jQuery (plugin only)
-
eventType: EventWhat triggered the menu to collapse.
Invoke the collapse method:
1
|
|
collapseAll( [event ] [, all ] )Returns: jQuery (plugin only)
-
eventType: EventWhat triggered the menu to collapse.
-
allType: BooleanIndicates whether all sub-menus should be closed or only sub-menus below and including the menu that is or contains the target of the triggering event.
Invoke the collapseAll method:
1
|
|
destroy()Returns: jQuery (plugin only)
- This method does not accept any arguments.
Invoke the destroy method:
1
|
|
disable()Returns: jQuery (plugin only)
- This method does not accept any arguments.
Invoke the disable method:
1
|
|
enable()Returns: jQuery (plugin only)
- This method does not accept any arguments.
Invoke the enable method:
1
|
|
expand( [event ] )Returns: jQuery (plugin only)
-
eventType: EventWhat triggered the menu to expand.
Invoke the expand method:
1
|
|
focus( [event ], item )Returns: jQuery (plugin only)
focus
event. Opens the menu item's sub-menu, if one exists.
-
eventType: EventWhat triggered the menu item to gain focus.
-
itemType: jQueryThe menu item to focus/activate.
Invoke the focus method:
1
|
|
instance()Returns: Object
Retrieves the menu's instance object. If the element does not have an associated instance, undefined
is returned.
Unlike other widget methods, instance()
is safe to call on any element after the menu plugin has loaded.
- This method does not accept any arguments.
Invoke the instance method:
1
|
|
isFirstItem()Returns: jQuery (plugin only)
- This method does not accept any arguments.
Invoke the isFirstItem method:
1
|
|
isLastItem()Returns: jQuery (plugin only)
- This method does not accept any arguments.
Invoke the isLastItem method:
1
|
|
next( [event ] )Returns: jQuery (plugin only)
-
eventType: EventWhat triggered the focus to move.
Invoke the next method:
1
|
|
nextPage( [event ] )Returns: jQuery (plugin only)
-
eventType: EventWhat triggered the focus to move.
Invoke the nextPage method:
1
|
|
option( optionName )Returns: Object
Gets the value currently associated with the specified optionName
.
Note: For options that have objects as their value, you can get the value of a specific key by using dot notation. For example, "foo.bar"
would get the value of the bar
property on the foo
option.
-
optionNameType: StringThe name of the option to get.
Invoke the method:
1
|
|
option()Returns: PlainObject
- This signature does not accept any arguments.
Invoke the method:
1
|
|
option( optionName, value )Returns: jQuery (plugin only)
Sets the value of the menu option associated with the specified optionName
.
Note: For options that have objects as their value, you can set the value of just one property by using dot notation for optionName
. For example, "foo.bar"
would update only the bar
property of the foo
option.
-
optionNameType: StringThe name of the option to set.
-
valueType: ObjectA value to set for the option.
Invoke the method:
1
|
|
option( options )Returns: jQuery (plugin only)
-
optionsType: ObjectA map of option-value pairs to set.
Invoke the method:
1
|
|
previous( [event ] )Returns: jQuery (plugin only)
-
eventType: EventWhat triggered the focus to move.
Invoke the previous method:
1
|
|
previousPage( [event ] )Returns: jQuery (plugin only)
-
eventType: EventWhat triggered the focus to move.
Invoke the previousPage method:
1
|
|
refresh()Returns: jQuery (plugin only)
refresh()
method.
- This method does not accept any arguments.
Invoke the refresh method:
1
|
|
select( [event ] )Returns: jQuery (plugin only)
select
event.
-
eventType: EventWhat triggered the selection.
Invoke the select method:
1
|
|
widget()Returns: jQuery
jQuery
object containing the menu.
- This method does not accept any arguments.
Invoke the widget method:
1
|
|
Extension Points
The menu widget is built with the widget factory and can be extended. When extending widgets, you have the ability to override or add to the behavior of existing methods. The following methods are provided as extension points with the same API stability as the plugin methods listed above. For more information on widget extensions, see Extending Widgets with the Widget Factory.
_closeOnDocumentClick( event )Returns: Boolean
-
eventType: Event
Never close menus on document click.
1
2
3
|
|
_isDivider( item )Returns: Boolean
-
itemType: jQuery
Treat all items as menu items with no dividers.
1
2
3
|
|
Events
blur( event, ui )Type: menublur
Initialize the menu with the blur callback specified:
1
2
3
|
|
Bind an event listener to the menublur event:
1
|
|
create( event, ui )Type: menucreate
Note: The ui
object is empty but included for consistency with other events.
Initialize the menu with the create callback specified:
1
2
3
|
|
Bind an event listener to the menucreate event:
1
|
|
focus( event, ui )Type: menufocus
Initialize the menu with the focus callback specified:
1
2
3
|
|
Bind an event listener to the menufocus event:
1
|
|
select( event, ui )Type: menuselect
Initialize the menu with the select callback specified:
1
2
3
|
|
Bind an event listener to the menuselect event:
1
|
|
Example:
A simple jQuery UI Menu
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
|
|