Since the native select menu is used as a proxy for the custom select, you can watch for events on the original, native select instead of needing to go through the select menu plugin. Bind to the change event by type: change, blur, focus, keypress, click, etc.
+$( ".selector" ).bind( "change", function(event, ui) { + ... +}); +
The select menu plugin has the following custom events:
create
This event is used to find out when a custom select was created. It is not used to create a custom select. The select create event can be used like this:
+$( ".selector" ).selectmenu({ + create: function(event, ui) { ... } +}); +
The select menus are driven off native select elements, but the native selects are hidden from view and replaced with a custom-styled select button that matches the look and feel of the jQuery Mobile framework. The replacement selects are ARIA-enabled and are keyboard accessible on the desktop as well.
select
When the select button is clicked, the native select menu picker for the OS will open. When a value is selected in the menu, the custom select button is updated to match the new selection.
To add a select widget to your page, start with a standard select element populated with a set of option elements. Set the for attribute of the label to match the ID of the select so they are semantically associated. Wrap them in a div with the data-role="fieldcontain" attribute to help visually group it in a longer form.
option
for
label
div
data-role="fieldcontain"
The framework will find all select elements and automatically enhance them into the custom select menus. Here is a typical select menu grouped in a fieldc container to style the label and select together:
+<div data-role="fieldcontain"> + <label for="select-choice-1" class="select">Choose shipping method:</label> + <select name="select-choice-1" id="select-choice-1"> + <option value="standard">Standard: 7 day</option> + <option value="rush">Rush: 3 days</option> + <option value="express">Express: next day</option> + <option value="overnight">Overnight</option> + </select> +</div> +
This produces this select:
Here is an example of a select with a long list of options:
This example organizes the options with optgroup elements and has a disabled option.
Note that on some mobile platforms, the native select menus don't support multiple selection via the multiple="multiple" attribute. If this feature is required, we recommend using custom menus. + +
multiple="multiple"
The select menu plugin will auto initialize on any page that contains a select menu, no need for a data-role attribute in the markup. However, you can directly call the select menu plugin on any selector, just like any normal jQuery plugin:
data-role
+$('select').selectmenu(); +
You can optionally use custom-styled select menus instead of the native versions. This adds the ability to theme the menu to better match the look and feel of your site and provides visual consistency across platforms. In addition, it supports multiple selection, restores missing functionality on certain platforms such as optgroup support on Android, and adds an elegant way to handle placeholder values (explained below). Lastly, the custom menus will look better on desktop browsers because native menus on the desktop tend to be fairly small compared their mobile counterparts and this can look a bit odd if desktop is a priority for your project.
optgroup
Keep in mind that there is overhead involved in parsing the native select to build a custom menu. If there are a lot of selects on a page, or a select has a long list of options, this can impact the performance of the page so we recommend using custom menus sparingly.
To use custom menus on a specific select, just add the data-native-menu="false" attribute. Alternately, this can also programmatically set the select menu's nativeMenu configuration option to false in a callback bound to the mobileinit event to achieve the same effect. This will globally make all selects use the custom menu by default. The following must be included in the page after jQuery is loaded but before jQuery Mobile is loaded.
data-native-menu="false"
nativeMenu
false
mobileinit
+ + $(document).bind('mobileinit',function(){ + $.mobile.selectmenu.prototype.options.nativeMenu = false; + }); + +
+ $(document).bind('mobileinit',function(){ + $.mobile.selectmenu.prototype.options.nativeMenu = false; + }); +
If there is a small number of options that will fit on the device's screen, it will appear as a small overlay with a pop transition.
If there is a select menu with too many options to show on the device's screen, the framework will automatically create a new "page" populated with a standard list view that contains all the options. This allows us to use the native scrolling included on the device for moving through a long list. The text inside the label is used as the title for this page.
It's common for developers to include a "null" option in their select element to force a user to choose an option. If a placeholder option is present in your markup, jQuery Mobile will hide them in the overlay menu, showing only valid choices to the user, and display the placeholder text inside the menu as a header. A placeholder option is added when the framework finds:
data-placeholder="true"
You can disable this feature through the selectmenu plugin's hidePlaceholderMenuItems option, like this:
hidePlaceholderMenuItems
+ +$.mobile.selectmenu.prototype.options.hidePlaceholderMenuItems = false; + +
+$.mobile.selectmenu.prototype.options.hidePlaceholderMenuItems = false; +
Here's a demo of various placeholder options:
jQuery Mobile will automatically disable and style option tags with the disabled attribute. In the demo below, the second option "Rush: 3 days" has been set to disabled.
disabled
If a select menu contains optgroup elements, jQuery Mobile will create a divider & group items based on the label attribute's text:
If the multiple attribute is present in your markup, jQuery Mobile will enhance the element with a few extra considerations:
multiple
When a select is large enough to where the menu will open in a new page, the placeholder text is displayed in the button when no items are selected, and the label text is displayed in the menu's header. This differs from smaller overlay menus where the placeholder text is displayed in both the button and the header, and from full-page single selects where the placeholder text is not used at all.
You can specify any jQuery Mobile button data- attribute on a select element too. In this example, we're setting the theme, icon and inline properties though data- attributes.
If you manipulate a select via JavaScript, you must call the refresh method on it to update the visual styling. Here is an example:
+var myselect = $("select#foo"); +myselect[0].selectedIndex = 3; +myselect.selectmenu("refresh"); +
The select menu plugin has the following methods:
close
+$('select').selectmenu('close'); +
enable
+$('select').selectmenu('enable'); +
disable
+$('select').selectmenu('disable'); +
open
+$('select').selectmenu('open'); +
refresh
+//refresh value +$('select').selectmenu('refresh'); + +//refresh and force rebuild +$('select').selectmenu('refresh', true); +
The select menu plugin has the following options:
corners
default: "true"
Applies the rounded corner class to add the theme button border-radius to the select button if set to true. This option is also exposed as a data attribute: data-corners="false"
data-corners="false"
$('select').selectmenu({ corners: "false" });
icon
default: "arrow-down"
Sets the icon for the select element from the icon set. This option is also exposed as a data attribute: data-icon="star"
data-icon="star"
$('select').selectmenu({ icon: "star" });
iconpos
default: "right"
Position of the icon in the select button. Possible values: left, right, none, notext. The notext value will display the select as an icon-only button with no text feedback. This option is also exposed as a data attribute: data-iconpos="left"
data-iconpos="left"
$('select').selectmenu({ iconpos: "left" });
iconshadow
Applies the icon drop shadow class to add the theme shadow style to the select button if set to true. This option is also exposed as a data attribute: data-iconshadow="false"
data-iconshadow="false"
$('select').selectmenu({ iconshadow: "false" });
inline
default: "null" (false)
If set to true, this will make the select button act like an inline button so the width is determined by the feedback text inside. By default, this is null (false) so the select button is full width, regardless of the feedback content. Possible values: true, false. This option is also exposed as a data attribute: data-inline="true"
data-inline="true"
$('select').selectmenu({ inline: "true" });
When set to true, clicking the custom-styled select menu will open the native select menu which is best for performance. If set to false, the custom select menu style will be used instead of the native menu. This option is also exposed as a data attribute: data-native-menu="false"
$('select').selectmenu({ nativeMenu: "false" });
shadow
Applies the drop shadow class to add the theme shadow style to the select button if set to true. This option is also exposed as a data attribute: data-shadow="false"
data-shadow="false"
$('select').selectmenu({ shadow: "false" });
theme
default: null, inherited from parent
Sets the theme swatch color scheme for the select element. This is a single letter from a-z that maps to the swatches included in your theme. By default, a select will inherit the same swatch color as it's parent container if not explicitly set. This option is also exposed as a data attribute: data-theme="a"
data-theme="a"
$('select').selectmenu({ theme: "a" });