Selectmenu Widget | jQuery UI 1.13 Documentation

Selectmenu Widgetversion added: 1.11

Description: Duplicates and extends the functionality of a native HTML select element to overcome the limitations of the native control.

QuickNavExamples

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.

Theming

The selectmenu widget uses the jQuery UI CSS framework to style its look and feel. If selectmenu specific styling is needed, the following CSS class names can be used for overrides or as keys for the classes option:

ui-selectmenu-button: The button-like element replacing the native selectmenu on the page. Has the ui-selectmenu-button-closed class when closed, the ui-selectmenu-button-open class when open.
- ui-selectmenu-text: The span representing the text portion of the button element.
- ui-selectmenu-icon: The icon within the selectmenu button.
ui-selectmenu-menu: The wrapper element around the menu used to display options to the user (not the menu itself). When the menu is open, the ui-selectmenu-open class is added.
- ui-selectmenu-optgroup: One of the elements that replicates <optgroup> elements from native selects.

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

appendTo

Type: Selector

Default: null

Which element to append the menu to. When the value is 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" );

classes

Type: Object

Default:

	
					{
  "ui-selectmenu-button-closed": "ui-corner-all",
  "ui-selectmenu-button-open": "ui-corner-top",
}

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.

Code examples:

Initialize the selectmenu with the classes option specified, changing the theming for the ui-selectmenu-menu class:

	
					$( ".selector" ).selectmenu({
  classes: {
    "ui-selectmenu-menu": "highlight"
  }
});

Get or set a property of the classes option, after initialization, here reading and changing the theming for the ui-selectmenu-menu class:

	
					// Getter
var themeClass = $( ".selector" ).selectmenu( "option", "classes.ui-selectmenu-menu" );
 
// Setter
$( ".selector" ).selectmenu( "option", "classes.ui-selectmenu-menu", "highlight" );

disabled

Type: Boolean

Default: false

Disables the selectmenu if set to 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 );

icons

Type: Object

Default: { button: "ui-icon-triangle-1-s" }

Icons to use for the button, matching an icon defined by the jQuery UI CSS Framework.

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" } );

position

Type: Object

Default: { my: "left top", at: "left bottom", collision: "none" }

Identifies the position of the menu in relation to the associated button element. You can refer to the jQuery UI Position utility for more details about the various options.

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" } );

width

Type: Number or Boolean

Default: false

The width of the menu, in pixels. When the value is null, the width of the native select is used. When the value is false, no inline style will be set for the width, allowing the width to be set in a stylesheet.

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 );

Methods

close()Returns: jQuery (plugin only)

Closes the menu.

This method does not accept any arguments.

Code examples:

Invoke the close method:

	
					$( ".selector" ).selectmenu( "close" );

destroy()Returns: jQuery (plugin only)

Removes the selectmenu functionality completely. This will return the element back to its pre-init state.

This method does not accept any arguments.

Code examples:

Invoke the destroy method:

	
					$( ".selector" ).selectmenu( "destroy" );

disable()Returns: jQuery (plugin only)

Disables the selectmenu.

This method does not accept any arguments.

Code examples:

Invoke the disable method:

	
					$( ".selector" ).selectmenu( "disable" );

enable()Returns: jQuery (plugin only)

Enables the selectmenu.

This method does not accept any arguments.

Code examples:

Invoke the enable method:

	
					$( ".selector" ).selectmenu( "enable" );

instance()Returns: Object

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.

Code examples:

Invoke the instance method:

	
					$( ".selector" ).selectmenu( "instance" );

menuWidget()Returns: jQuery (plugin only)

Returns a jQuery object containing the menu element.

This method does not accept any arguments.

Code examples:

Invoke the menuWidget method:

	
					$( ".selector" ).selectmenu( "menuWidget" );

open()Returns: jQuery (plugin only)

Opens the menu.

This method does not accept any arguments.

Code examples:

Invoke the open method:

	
					$( ".selector" ).selectmenu( "open" );

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.

optionName

Type: String

The name of the option to get.

Code examples:

Invoke the method:

	
					var isDisabled = $( ".selector" ).selectmenu( "option", "disabled" );

option()Returns: PlainObject

Gets an object containing key/value pairs representing the current selectmenu options hash.

This signature does not accept any arguments.

Code examples:

Invoke the method:

	
					var options = $( ".selector" ).selectmenu( "option" );

option( optionName, value )Returns: jQuery (plugin only)

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.

optionName

Type: String

The name of the option to set.
value

Type: Object

A value to set for the option.

Code examples:

Invoke the method:

	
					$( ".selector" ).selectmenu( "option", "disabled", true );

option( options )Returns: jQuery (plugin only)

Sets one or more options for the selectmenu.

options

Type: Object

A map of option-value pairs to set.

Code examples:

Invoke the method:

	
					$( ".selector" ).selectmenu( "option", { disabled: true } );

refresh()Returns: jQuery (plugin only)

Parses the original element and re-renders the menu. Processes any <option> or <optgroup> elements that were added, removed or disabled.

This method does not accept any arguments.

Code examples:

Invoke the refresh method:

	
					$( ".selector" ).selectmenu( "refresh" );

Extension Points

The selectmenu 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.

_renderButtonItem( item )Returns: jQuery

Method that controls the creation of the generated button content. The method must create and return a new element.

item

Type: Object
- disabled
  
  Type: Boolean
  
  Whether the item is disabled.
- element
  
  Type: jQuery
  
  A reference to the item's original <option> element.
- index
  
  Type: Number
  
  The numeric index of the item.
- label
  
  Type: String
  
  The string to display for the item.
- optgroup
  
  Type: String
  
  If the item is within an <optgroup>, this is set to that <optgroup>'s label.
- value
  
  Type: String
  
  The value attribute of the item's original <option>.

Code examples:

Style the button background color based on the value of the selected option.

	
					_renderButtonItem: function( item ) {
  var buttonItem = $( "<span>", {
    "class": "ui-selectmenu-text"
  })
  this._setText( buttonItem, item.label );
 
  buttonItem.css( "background-color", item.value )
 
  return buttonItem;
}

_renderItem( ul, item )Returns: jQuery

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. See the Menu documentation for more details about the markup.

ul

Type: jQuery

The <ul> element that the newly created <li> element must be appended to.
item

Type: Object
- element
  
  Type: jQuery
  
  The original <option> element.
- index
  
  Type: Integer
  
  The index of the <option> within the <select>.
- value
  
  Type: String
  
  The value of the <option>.
- label
  
  Type: String
  
  The label of the <option>.
- optgroup
  
  Type: String
  
  The label for the parent optgroup, if any.
- disabled
  
  Type: Boolean
  
  Whether the <option> is disabled.

Code examples:

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 );
}

_renderMenu( ul, items )Returns: jQuery (plugin only)

Method that controls building the widget's menu. The method is passed an empty <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.

ul

Type: jQuery

An empty <ul> element to use as the widget's menu.
items

Type: Array

An 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.

Code examples:

Add a CSS class name to the odd menu items.

Note: For simplicity, this example does not support optgroups or disabled menu items.

	
					_renderMenu: function( ul, items ) {
  var that = this;
  $.each( items, function( index, item ) {
    that._renderItemData( ul, item );
  });
  $( ul ).find( "li" ).odd().addClass( "odd" );
}

_resizeMenu()Returns: jQuery (plugin only)

Method responsible for sizing the menu before it is displayed. The menu element is available at this.menu.

This method does not accept any arguments.

Code examples:

Always display the menu as 500 pixels wide.

	
					_resizeMenu: function() {
  this.menu.outerWidth( 500 );
}

Events

change( event, ui )Type: `selectmenuchange`

Triggered when the selected item has changed. Not every select event will fire a change event.

event

Type: Event
ui

Type: Object
- item
  
  Type: jQuery
  
  The active item.

Code examples:

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 ) {} );

close( event )Type: `selectmenuclose`

Triggered when the menu is hidden.

event

Type: Event

Note: The ui object is empty but included for consistency with other events.

Code examples:

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 ) {} );

create( event, ui )Type: `selectmenucreate`

Triggered when the selectmenu is created.

event

Type: Event
ui

Type: Object

Note: The ui object is empty but included for consistency with other events.

Code examples:

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 ) {} );

focus( event, ui )Type: `selectmenufocus`

Triggered when an items gains focus.

event

Type: Event
ui

Type: Object
- item
  
  Type: jQuery
  
  The focused item.

Code examples:

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 ) {} );

open( event )Type: `selectmenuopen`

Triggered when the menu is opened.

event

Type: Event

Note: The ui object is empty but included for consistency with other events.

Code examples:

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 ) {} );

select( event, ui )Type: `selectmenuselect`

Triggered when a menu item is selected.

event

Type: Event
ui

Type: Object
- item
  
  Type: jQuery
  
  The selected item.

Code examples:

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 ) {} );

Examples:

A simple jQuery UI Selectmenu

	
		
				
				
				
				
					<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>selectmenu demo</title>
  <link rel="stylesheet" href="https://code.jquery.com/ui/1.13.3/themes/smoothness/jquery-ui.css">
  <style>
  label { display: block; }
  select { width: 200px; }
  </style>
  <script src="https://code.jquery.com/jquery-3.7.1.js"></script>
  <script src="https://code.jquery.com/ui/1.13.3/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>

				
			

	

Demo:

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="https://code.jquery.com/ui/1.13.3/themes/smoothness/jquery-ui.css">
  <style>
  label { display: block; }
  select { width: 200px; }
  </style>
  <script src="https://code.jquery.com/jquery-3.7.1.js"></script>
  <script src="https://code.jquery.com/ui/1.13.3/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>

				
			

	

Demo:

A jQuery UI Selectmenu with overflow

	
		
				
				
				
				
					<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>selectmenu demo</title>
  <link rel="stylesheet" href="https://code.jquery.com/ui/1.13.3/themes/smoothness/jquery-ui.css">
  <style>
  label { display: block; }
  select { width: 200px; }
  .overflow { height: 200px; }
  </style>
  <script src="https://code.jquery.com/jquery-3.7.1.js"></script>
  <script src="https://code.jquery.com/ui/1.13.3/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>

				
			

	

jQuery UI 1.13 Documentation

Selectmenu Widgetversion added: 1.11

Options

Methods

Extension Points

Events

Keyboard interaction

Theming

Dependencies

Additional Notes:

appendTo

classes

disabled

icons

position

width

close()Returns: jQuery (plugin only)

destroy()Returns: jQuery (plugin only)

disable()Returns: jQuery (plugin only)

enable()Returns: jQuery (plugin only)

instance()Returns: Object

menuWidget()Returns: jQuery (plugin only)

open()Returns: jQuery (plugin only)

option( optionName )Returns: Object

option()Returns: PlainObject

option( optionName, value )Returns: jQuery (plugin only)

option( options )Returns: jQuery (plugin only)

refresh()Returns: jQuery (plugin only)

widget()Returns: jQuery (plugin only)

_renderButtonItem( item )Returns: jQuery

_renderItem( ul, item )Returns: jQuery

_renderMenu( ul, items )Returns: jQuery (plugin only)

_resizeMenu()Returns: jQuery (plugin only)

change( event, ui )Type: selectmenuchange

close( event )Type: selectmenuclose

create( event, ui )Type: selectmenucreate

focus( event, ui )Type: selectmenufocus

open( event )Type: selectmenuopen

select( event, ui )Type: selectmenuselect

Demo:

Demo:

Demo:

change( event, ui )Type: `selectmenuchange`

close( event )Type: `selectmenuclose`

create( event, ui )Type: `selectmenucreate`

focus( event, ui )Type: `selectmenufocus`

open( event )Type: `selectmenuopen`

select( event, ui )Type: `selectmenuselect`