Selectmenu transforms a <select>
element into a themeable and customizable control. The widget acts as a proxy to the original <select>
; therefore the original element's state is maintained for form submission and serialization.
Selectmenu supports <optgroup>
elements and custom markup to render specific presentations like multiple lines. The <select>
and its options can be disabled by adding a disabled
attribute.
Note: Support for accesskey
on custom elements is extremely limited in browsers. As such, if there is an accesskey
attribute on the <select>
element, it will not work with the custom selectmenu. If there is an accesskey
attribute on any of the <option>
elements, using the accesskey may cause the original element and the custom element to be out of sync. However, most browsers don't support accesskey
on <option>
elements.
Keyboard interaction
When the menu is open, the following key commands are available:
-
UP
/LEFT
: Move focus to the previous item. -
DOWN
/RIGHT
: Move focus to the next item. -
END
/PAGE DOWN
: Move focus to the last item. -
HOME
/PAGE UP
: Move focus to the first item. -
ESCAPE
: Close the menu. -
ENTER
/SPACE
: Select the currently focused item and close the menu. -
ALT
/OPTION
+UP
/DOWN
: Toggle the visibility of the menu.
When the menu is closed, the following key commands are available:
-
UP
/LEFT
: Select the previous item. -
DOWN
/RIGHT
: Select the next item. -
END
/PAGE DOWN
: Select the last item. -
HOME
/PAGE UP
: Select the first item. -
ALT
/OPTION
+UP
/DOWN
: Toggle the visibility of the menu. -
SPACE
: Open the menu.
- 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.
null
null
, the parents of the <select>
are checked for a class name of ui-front
. If an element with the ui-front
class name is found, the menu is appended to that element. Regardless of the value, if no element is found, the menu is appended to the body.Code examples:
Initialize the selectmenu with the appendTo
option specified:
$( ".selector" ).selectmenu({ appendTo: "#someElem" });
Get or set the appendTo
option, after initialization:
// Getter var appendTo = $( ".selector" ).selectmenu( "option", "appendTo" ); // Setter $( ".selector" ).selectmenu( "option", "appendTo", "#someElem" );
false
true
.Code examples:
Initialize the selectmenu with the disabled
option specified:
$( ".selector" ).selectmenu({ disabled: true });
Get or set the disabled
option, after initialization:
// Getter var disabled = $( ".selector" ).selectmenu( "option", "disabled" ); // Setter $( ".selector" ).selectmenu( "option", "disabled", true );
{ button: "ui-icon-triangle-1-s" }
- button (string, default: "ui-icon-triangle-1-s")
Code examples:
Initialize the selectmenu with the icons
option specified:
$( ".selector" ).selectmenu({ icons: { button: "ui-icon-circle-triangle-s" } });
Get or set the icons
option, after initialization:
// Getter var icons = $( ".selector" ).selectmenu( "option", "icons" ); // Setter $( ".selector" ).selectmenu( "option", "icons", { button: "ui-icon-circle-triangle-s" } );
{ my: "left top", at: "left bottom", collision: "none" }
Code examples:
Initialize the selectmenu with the position
option specified:
$( ".selector" ).selectmenu({ position: { my : "left+10 center", at: "right center" } });
Get or set the position
option, after initialization:
// Getter var position = $( ".selector" ).selectmenu( "option", "position" ); // Setter $( ".selector" ).selectmenu( "option", "position", { my : "left+10 center", at: "right center" } );
null
null
, the width of the native select is used.Code examples:
Initialize the selectmenu with the width
option specified:
$( ".selector" ).selectmenu({ width: 200 });
Get or set the width
option, after initialization:
// Getter var width = $( ".selector" ).selectmenu( "option", "width" ); // Setter $( ".selector" ).selectmenu( "option", "width", 200 );
- This method does not accept any arguments.
Invoke the close method:
$( ".selector" ).selectmenu( "close" );
- This method does not accept any arguments.
Invoke the destroy method:
$( ".selector" ).selectmenu( "destroy" );
- This method does not accept any arguments.
Invoke the disable method:
$( ".selector" ).selectmenu( "disable" );
- This method does not accept any arguments.
Invoke the enable method:
$( ".selector" ).selectmenu( "enable" );
Retrieves the selectmenu'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 selectmenu plugin has loaded.
- This method does not accept any arguments.
Invoke the instance method:
$( ".selector" ).selectmenu( "instance" );
jQuery
object containing the menu element.- This method does not accept any arguments.
Invoke the menuWidget method:
$( ".selector" ).selectmenu( "menuWidget" );
- This method does not accept any arguments.
Invoke the open method:
$( ".selector" ).selectmenu( "open" );
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" ).selectmenu( "option", "disabled" );
- This signature does not accept any arguments.
Invoke the method:
var options = $( ".selector" ).selectmenu( "option" );
Sets the value of the selectmenu 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" ).selectmenu( "option", "disabled", true );
- optionsType: ObjectA map of option-value pairs to set.
Invoke the method:
$( ".selector" ).selectmenu( "option", { disabled: true } );
<option>
or <optgroup>
elements that were added, removed or disabled. - This method does not accept any arguments.
Invoke the refresh method:
$( ".selector" ).selectmenu( "refresh" );
jQuery
object containing the button element.- This method does not accept any arguments.
Invoke the widget method:
$( ".selector" ).selectmenu( "widget" );
Method that controls the creation of each option in the widget's menu. The method must create a new <li>
element, append it to the menu, and return it.
- ulType: jQueryThe
<ul>
element that the newly created<li>
element must be appended to. - itemType: Object
- elementType: jQueryThe original
<option>
element. - indexType: IntegerThe index of the
<option>
within the<select>
. - valueType: StringThe value of the
<option>
. - labelType: StringThe label of the
<option>
. - optgroupType: StringThe label for the parent
optgroup
, if any. - disabledType: BooleanWhether the
<option>
is disabled.
-
Style the menu item background colors based on the value of their corresponding option elements.
_renderItem: function( ul, item ) { var li = $( "<li>" ) .css( "background-color", item.value ); if ( item.disabled ) { li.addClass( "ui-state-disabled" ); } this._setText( li, item.label ); return li.appendTo( ul ); }
<ul>
and an array of items based on the <option>
elements in the original <select>
. Creation of the individual <li>
elements should be delegated to _renderItemData()
, which in turn delegates to the _renderItem()
extension point. - ulType: jQueryAn empty
<ul>
element to use as the widget's menu. - itemsType: ArrayAn array of items based on the
<option>
elements in the original<select>
. See the_renderItem()
extension point for details on the format of the item objects.
Add a CSS class name to the odd menu items.
_renderMenu: function( ul, items ) { var that = this; $.each( items, function( index, item ) { that._renderItemData( ul, item ); }); $( ul ).find( "li:odd" ).addClass( "odd" ); }
this.menu
.- This method does not accept any arguments.
Always display the menu as 500 pixels wide.
_resizeMenu: function() { this.menu.outerWidth( 500 ); }
selectmenuchange
select
event will fire a change
event.Initialize the selectmenu with the change callback specified:
$( ".selector" ).selectmenu({ change: function( event, ui ) {} });
Bind an event listener to the selectmenuchange event:
$( ".selector" ).on( "selectmenuchange", function( event, ui ) {} );
selectmenuclose
- eventType: Event
Note: The ui
object is empty but included for consistency with other events.
Initialize the selectmenu with the close callback specified:
$( ".selector" ).selectmenu({ close: function( event, ui ) {} });
Bind an event listener to the selectmenuclose event:
$( ".selector" ).on( "selectmenuclose", function( event, ui ) {} );
selectmenucreate
Note: The ui
object is empty but included for consistency with other events.
Initialize the selectmenu with the create callback specified:
$( ".selector" ).selectmenu({ create: function( event, ui ) {} });
Bind an event listener to the selectmenucreate event:
$( ".selector" ).on( "selectmenucreate", function( event, ui ) {} );
selectmenufocus
Initialize the selectmenu with the focus callback specified:
$( ".selector" ).selectmenu({ focus: function( event, ui ) {} });
Bind an event listener to the selectmenufocus event:
$( ".selector" ).on( "selectmenufocus", function( event, ui ) {} );
selectmenuopen
- eventType: Event
Note: The ui
object is empty but included for consistency with other events.
Initialize the selectmenu with the open callback specified:
$( ".selector" ).selectmenu({ open: function( event, ui ) {} });
Bind an event listener to the selectmenuopen event:
$( ".selector" ).on( "selectmenuopen", function( event, ui ) {} );
selectmenuselect
Initialize the selectmenu with the select callback specified:
$( ".selector" ).selectmenu({ select: function( event, ui ) {} });
Bind an event listener to the selectmenuselect event:
$( ".selector" ).on( "selectmenuselect", function( event, ui ) {} );
A simple jQuery UI Selectmenu
<!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <title>selectmenu demo</title> <link rel="stylesheet" href="//code.jquery.com/ui/1.11.4/themes/smoothness/jquery-ui.css"> <style> label { display: block; } select { 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> <label for="speed">Select a speed:</label> <select name="speed" id="speed"> <option value="Slower">Slower</option> <option value="Slow">Slow</option> <option value="Medium" selected>Medium</option> <option value="Fast">Fast</option> <option value="Faster">Faster</option> </select> <script> $( "#speed" ).selectmenu(); </script> </body> </html>
A simple jQuery UI Selectmenu with optgroups
<!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <title>selectmenu demo</title> <link rel="stylesheet" href="//code.jquery.com/ui/1.11.4/themes/smoothness/jquery-ui.css"> <style> label { display: block; } select { 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> <label for="files">Select a file:</label> <select name="files" id="files"> <optgroup label="Scripts"> <option value="jquery">jQuery.js</option> <option value="jqueryui">ui.jQuery.js</option> </optgroup> <optgroup label="Other files"> <option value="somefile">Some unknown file</option> <option value="someotherfile">Some other file</option> </optgroup> </select> <script> $( "#files" ).selectmenu(); </script> </body> </html>
A jQuery UI Selectmenu with overflow
<!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <title>selectmenu demo</title> <link rel="stylesheet" href="//code.jquery.com/ui/1.11.4/themes/smoothness/jquery-ui.css"> <style> label { display: block; } select { width: 200px; } .overflow { height: 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> <label for="number">Select a number:</label> <select name="number" id="number"> <option value="1">1</option> <option value="2" selected>2</option> <option value="3">3</option> <option value="4">4</option> <option value="5">5</option> <option value="6">6</option> <option value="7">7</option> <option value="8">8</option> <option value="9">9</option> <option value="10">10</option> <option value="11">11</option> <option value="12">12</option> <option value="13">13</option> <option value="14">14</option> <option value="15">15</option> <option value="16">16</option> <option value="17">17</option> <option value="18">18</option> <option value="19">19</option> </select> <script> $( "#number" ) .selectmenu() .selectmenu( "menuWidget" ) .addClass( "overflow" ); </script> </body> </html>
Please login to continue.