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>
):
<ul id="menu"> <li>Item 1</li> <li>Item 2</li> <li>Item 3 <ul> <li>Item 3-1</li> <li>Item 3-2</li> <li>Item 3-3</li> <li>Item 3-4</li> <li>Item 3-5</li> </ul> </li> <li>Item 4</li> <li>Item 5</li> </ul>
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:
<ul id="menu"> <li><span class="ui-icon ui-icon-disk"></span>Save</li> </ul>
Menu automatically adds the necessary padding to items without icons.
Dividers
Divider elements can be created by including unlinked menu items that contain only spaces and/or dashes:
<ul id="menu"> <li>Item 1</li> <li>-</li> <li>Item 2</li> </ul>
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:
-
ui-menu
: The outer container of the menu. This element will additionally have aui-menu-icons
class if the menu contains icons.-
ui-menu-item
: The container for individual menu items.-
ui-menu-icon
: The submenu icons set via theicons
option.
-
-
ui-menu-divider
: Divider elements between menu items.
-
Dependencies
- UI Core
- Widget Factory
- Position
- 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.
false
true
.Code examples:
Initialize the menu with the disabled
option specified:
$( ".selector" ).menu({ disabled: true });
Get or set the disabled
option, after initialization:
// Getter var disabled = $( ".selector" ).menu( "option", "disabled" ); // Setter $( ".selector" ).menu( "option", "disabled", true );
{ submenu: "ui-icon-carat-1-e" }
- submenu (string, default: "ui-icon-carat-1-e")
Code examples:
Initialize the menu with the icons
option specified:
$( ".selector" ).menu({ icons: { submenu: "ui-icon-circle-triangle-e" } });
Get or set the icons
option, after initialization:
// Getter var icons = $( ".selector" ).menu( "option", "icons" ); // Setter $( ".selector" ).menu( "option", "icons", { submenu: "ui-icon-circle-triangle-e" } );
"> *"
Selector for the elements that serve as the menu items.
items
option should not be changed after initialization.Code examples:
Initialize the menu with the items
option specified:
$( ".selector" ).menu({ items: ".custom-item" });
Get the items
option, after initialization:
// Getter var items = $( ".selector" ).menu( "option", "items" );
"ul"
Selector for the elements that serve as the menu container, including sub-menus.
menus
option should not be changed after initialization. Existing submenus will not be updated.Code examples:
Initialize the menu with the menus
option specified:
$( ".selector" ).menu({ menus: "div" });
Get the menus
option, after initialization:
// Getter var menus = $( ".selector" ).menu( "option", "menus" );
{ 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.Code examples:
Initialize the menu with the position
option specified:
$( ".selector" ).menu({ position: { my: "left top", at: "right-5 top+5" } });
Get or set the position
option, after initialization:
// Getter var position = $( ".selector" ).menu( "option", "position" ); // Setter $( ".selector" ).menu( "option", "position", { my: "left top", at: "right-5 top+5" } );
"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.Code examples:
Initialize the menu with the role
option specified:
$( ".selector" ).menu({ role: null });
Get the role
option, after initialization:
// Getter var role = $( ".selector" ).menu( "option", "role" );
blur
event. - eventType: EventWhat triggered the menu to blur.
Invoke the blur method:
$( ".selector" ).menu( "blur" );
- eventType: EventWhat triggered the menu to collapse.
Invoke the collapse method:
$( ".selector" ).menu( "collapse" );
- 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:
$( ".selector" ).menu( "collapseAll", null, true );
- This method does not accept any arguments.
Invoke the destroy method:
$( ".selector" ).menu( "destroy" );
- This method does not accept any arguments.
Invoke the disable method:
$( ".selector" ).menu( "disable" );
- This method does not accept any arguments.
Invoke the enable method:
$( ".selector" ).menu( "enable" );
- eventType: EventWhat triggered the menu to expand.
Invoke the expand method:
$( ".selector" ).menu( "expand" );
focus
event. - eventType: EventWhat triggered the menu item to gain focus.
- itemType: jQueryThe menu item to focus/activate.
Invoke the focus method:
$( ".selector" ).menu( "focus", null, menu.find( ".ui-menu-item:last" ) );
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:
$( ".selector" ).menu( "instance" );
- This method does not accept any arguments.
Invoke the isFirstItem method:
var firstItem = $( ".selector" ).menu( "isFirstItem" );
- This method does not accept any arguments.
Invoke the isLastItem method:
var lastItem = $( ".selector" ).menu( "isLastItem" );
- eventType: EventWhat triggered the focus to move.
Invoke the next method:
$( ".selector" ).menu( "next" );
- eventType: EventWhat triggered the focus to move.
Invoke the nextPage method:
$( ".selector" ).menu( "nextPage" );
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:
var isDisabled = $( ".selector" ).menu( "option", "disabled" );
- This signature does not accept any arguments.
Invoke the method:
var options = $( ".selector" ).menu( "option" );
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:
$( ".selector" ).menu( "option", "disabled", true );
- optionsType: ObjectA map of option-value pairs to set.
Invoke the method:
$( ".selector" ).menu( "option", { disabled: true } );
- eventType: EventWhat triggered the focus to move.
Invoke the previous method:
$( ".selector" ).menu( "previous" );
- eventType: EventWhat triggered the focus to move.
Invoke the previousPage method:
$( ".selector" ).menu( "previousPage" );
refresh()
method. - This method does not accept any arguments.
Invoke the refresh method:
$( ".selector" ).menu( "refresh" );
select
event. - eventType: EventWhat triggered the selection.
Invoke the select method:
$( ".selector" ).menu( "select" );
jQuery
object containing the menu. - This method does not accept any arguments.
Invoke the widget method:
var widget = $( ".selector" ).menu( "widget" );
- eventType: Event
Never close menus on document click.
_closeOnDocumentClick: function( event ) { return false; }
- itemType: jQuery
Treat all items as menu items with no dividers.
_isDivider: function( item ) { return false; }
menublur
Initialize the menu with the blur callback specified:
$( ".selector" ).menu({ blur: function( event, ui ) {} });
Bind an event listener to the menublur event:
$( ".selector" ).on( "menublur", function( event, ui ) {} );
menucreate
Note: The ui
object is empty but included for consistency with other events.
Initialize the menu with the create callback specified:
$( ".selector" ).menu({ create: function( event, ui ) {} });
Bind an event listener to the menucreate event:
$( ".selector" ).on( "menucreate", function( event, ui ) {} );
menufocus
Initialize the menu with the focus callback specified:
$( ".selector" ).menu({ focus: function( event, ui ) {} });
Bind an event listener to the menufocus event:
$( ".selector" ).on( "menufocus", function( event, ui ) {} );
menuselect
Initialize the menu with the select callback specified:
$( ".selector" ).menu({ select: function( event, ui ) {} });
Bind an event listener to the menuselect event:
$( ".selector" ).on( "menuselect", function( event, ui ) {} );
A simple jQuery UI Menu
<!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <title>menu demo</title> <link rel="stylesheet" href="//code.jquery.com/ui/1.11.4/themes/smoothness/jquery-ui.css"> <style> .ui-menu { width: 200px; } </style> <script src="//code.jquery.com/jquery-1.10.2.js"></script> <script src="//code.jquery.com/ui/1.11.4/jquery-ui.js"></script> </head> <body> <ul id="menu"> <li>Item 1</li> <li>Item 2</li> <li>Item 3 <ul> <li>Item 3-1</li> <li>Item 3-2</li> <li>Item 3-3</li> <li>Item 3-4</li> <li>Item 3-5</li> </ul> </li> <li>Item 4</li> <li>Item 5</li> </ul> <script> $( "#menu" ).menu(); </script> </body> </html>
Please login to continue.