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 and each menu item has an anchor. The most commonly used element is the unordered list (<ul>
):
<ul id="menu"> <li><a href="#">Item 1</a></li> <li><a href="#">Item 2</a></li> <li><a href="#">Item 3</a> <ul> <li><a href="#">Item 3-1</a></li> <li><a href="#">Item 3-2</a></li> <li><a href="#">Item 3-3</a></li> <li><a href="#">Item 3-4</a></li> <li><a href="#">Item 3-5</a></li> </ul> </li> <li><a href="#">Item 4</a></li> <li><a href="#">Item 5</a></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.
To add icons to the menu, include them in the markup:
<ul id="menu"> <li><a href="#"><span class="ui-icon ui-icon-disk"></span>Save</a></li> </ul>
Menu automatically adds the necessary padding to items without icons.
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.
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
disabledType: Boolean
false
true
.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 ); |
iconsType: Object
{ submenu: "ui-icon-carat-1-e" }
- submenu (string, default: "ui-icon-carat-1-e")
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" } ); |
positionType: Object
{ 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:
$( ".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" } ); |
roleType: String
"menu"
"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.Initialize the menu with the role option specified:
$( ".selector" ).menu({ role: null }); |
Get or set the role option, after initialization:
// getter var role = $( ".selector" ).menu( "option" , "role" ); // setter $( ".selector" ).menu( "option" , "role" , null ); |
Methods
collapse( [event ] )
-
eventType: EventWhat triggered the menu to collapse.
Invoke the collapse method:
$( ".selector" ).menu( "collapse" ); |
collapseAll( [event ] [, all ] )
-
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 ); |
destroy()
- This method does not accept any arguments.
Invoke the destroy method:
$( ".selector" ).menu( "destroy" ); |
disable()
- This method does not accept any arguments.
Invoke the disable method:
$( ".selector" ).menu( "disable" ); |
enable()
- This method does not accept any arguments.
Invoke the enable method:
$( ".selector" ).menu( "enable" ); |
expand( [event ] )
-
eventType: EventWhat triggered the menu to expand.
Invoke the expand method:
$( ".selector" ).menu( "expand" ); |
focus( [event ], item )
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" ) ); |
isFirstItem()
- This method does not accept any arguments.
Invoke the isFirstItem method:
var firstItem = $( ".selector" ).menu( "isFirstItem" ); |
isLastItem()
- This method does not accept any arguments.
Invoke the isLastItem method:
var lastItem = $( ".selector" ).menu( "isLastItem" ); |
next( [event ] )
-
eventType: EventWhat triggered the focus to move.
Invoke the next method:
$( ".selector" ).menu( "next" ); |
nextPage( [event ] )
-
eventType: EventWhat triggered the focus to move.
Invoke the nextPage method:
$( ".selector" ).menu( "nextPage" ); |
option( optionName )Returns: Object
optionName
.-
optionNameType: StringThe name of the option to get.
Invoke the method:
var isDisabled = $( ".selector" ).menu( "option" , "disabled" ); |
option()Returns: PlainObject
- This method does not accept any arguments.
Invoke the method:
var options = $( ".selector" ).menu( "option" ); |
option( optionName, value )
optionName
.-
optionNameType: StringThe name of the option to set.
-
valueType: ObjectA value to set for the option.
Invoke the method:
$( ".selector" ).menu( "option" , "disabled" , true ); |
option( options )
-
optionsType: ObjectA map of option-value pairs to set.
Invoke the method:
$( ".selector" ).menu( "option" , { disabled: true } ); |
previous( [event ] )
-
eventType: EventWhat triggered the focus to move.
Invoke the previous method:
$( ".selector" ).menu( "previous" ); |
previousPage( [event ] )
-
eventType: EventWhat triggered the focus to move.
Invoke the previousPage method:
$( ".selector" ).menu( "previousPage" ); |
refresh()
refresh()
method.
- This method does not accept any arguments.
Invoke the refresh method:
$( ".selector" ).menu( "refresh" ); |
widget()Returns: jQuery
jQuery
object containing the menu.
- This method does not accept any arguments.
Invoke the widget method:
var widget = $( ".selector" ).menu( "widget" ); |
Events
blur( event, ui )Type: 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 ) {} ); |
create( event, ui )Type: menucreate
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 ) {} ); |
focus( event, ui )Type: 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 ) {} ); |
select( event, ui )Type: 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 ) {} ); |
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 | <!doctype html> < html lang = "en" > < head > < meta charset = "utf-8" > < title >menu demo</ title > < style > .ui-menu { width: 200px; } </ style > </ head > < body > < ul id = "menu" > < li >< a href = "#" >Item 1</ a ></ li > < li >< a href = "#" >Item 2</ a ></ li > < li >< a href = "#" >Item 3</ a > < ul > < li >< a href = "#" >Item 3-1</ a ></ li > < li >< a href = "#" >Item 3-2</ a ></ li > < li >< a href = "#" >Item 3-3</ a ></ li > < li >< a href = "#" >Item 3-4</ a ></ li > < li >< a href = "#" >Item 3-5</ a ></ li > </ ul > </ li > < li >< a href = "#" >Item 4</ a ></ li > < li >< a href = "#" >Item 5</ a ></ li > </ ul > < script > $( "#menu" ).menu(); </ script > </ body > </ html > |