Skip to content

Selectmenu

Jump to bottom Edit New page
fnagel edited this page Apr 16, 2011 · 52 revisions

jQuery UI Selectmenu Widget

This is an improved version of the jQuery UI selectmenu widget originally developed by Scott (filament group):
http://filamentgroup.com/lab/jquery_ui_selectmenu_an_aria_accessible_plugin_for_styling_a_html_select/

Please use GitHub issues for bug tracking:
http://github.com/fnagel/jquery-ui/issues/labels/_selectmenu

There a many issues to fix a the moment and I’m looking for help. Even this guide is incomplete. To help me to add something here, please visit the issues.

Parts of this wiki are taken from the original description.

Demos & Download

Latest version could be downloaded here: http://github.com/fnagel/jquery-ui/zipball/selectmenu (zip)
A stable release (v1.1) is about to be released in early 2011.

Demos: http://jsfiddle.net/fnagel/hsn95/embedded/result/

Features

  • Keyboard accessibility The keyboard events match the native select implementation of popular browsers, including support for arrow keys, enter, space, tab, home, end, page up, and page down. The menu is keyboard accessible while closed as well!
    There are currently some issues with the
  • ARIA support ARIA attributes are added to the component, making this plugin an accessible replacement for a native select element (for users with modern screen readers).
  • Different menu types Popup or dropdown
  • jQuery UI Widget-factory-driven Built using the standard jQuery UI widget pattern for creating widget instances.
  • ThemeRoller-Ready Full theming support using jQuery UI ThemeRoller
  • Form label association If there’s an associated form label on the page, clicking it will focus the selectmenu widget, and its “for” attribute will properly associate with the selectmenu widget for accessibility purposes.
  • Option Text Formatting The format option allows you to customize the text of every option, creating complex formatting not possible in native select elements.
  • Optgroup support select elements with optgroups are translated into embedded HTML lists with a content-text label matching the optgroup’s label.
  • Disable elements Disable the complete selectmenu, single options or even optgroups
  • Quick Type-ahead Like a native select menu, you can quickly access options by typing their letters. Optional: access options by typing their first letter, repeating a letter will iterate through the options beginning with that letter.
  • Callback events The selectmenu plugin provides callbacks for open, close, select, and change events, allowing you to execute scripting based on those events. The change event even triggers a change event on the original select element, allowing you to reliably track form change events.

Tested Browsers

Firefox 3.6.x – 4.x
IE 6-9
Chrome 9.x
Safari 3.x
Opera

(latest test: 15.02.11)

Known problems

There are some problem in IE6, but the widget is still usable. Please see: https://github.com/fnagel/jquery-ui/issues

Options and Configuration

The following options are available in this widget:

  • transferClasses: true, transfer classes from select
  • style: ‘popup’, also available: ‘dropdown’
  • width: null, defaults to select width, accepts a number
  • menuWidth: null, sets menu body separately. accepts a number
  • handleWidth: 26, width that the icon arrow block will hang off the edge in a ‘popup’ style menu
  • maxHeight: null, the maximum height of the menu (with support for scrolling overflow).
  • icons: null, an array of objects with “find” and “icon” properties. “find” is a jQuery selector, “icon” is a jQuery UI framework icon class (“ui-icon-script”). This allows you to append span elements to options for use as icons.
  • format: null, Accepts a function with a single argument that can be manipulated and returned with any level of manipulation you’d like
  • typeAhead set to false will disable sequential typeahead. Default: “sequential”
  • bgImage: null, Accepts a function with the current option as parameter. Return a string which could be used as “background-image” CSS style.
  • wrapperElement: "", Wraps all added elements into a HTML tag. $.wrap parameters accepted.

Usage

Using the plugin is as simple as addressing a select element on your page and calling “selectmenu()” method on it. Like this:

$('select').selectmenu();

Beyond that, you can utilize the options mentioned above using the same conventions followed by all other jQuery UI plugins.

Methods

This guide is incomplete. To help me to add something here, please visit the issues.

value

Retrieves or selects the value of the current option.

// read
$('select#speedA').selectmenu("value")
// write
$('select#speedA').selectmenu("value", "VALUE")

index

Retrieves or selects the index of the current option.

// read
$('select#speedA').selectmenu("index")
// write
$('select#speedA').selectmenu("index", 4)

disable / enable

Disable or enable the whole selectmenu, single options or even optgroups:

// enable / disable complete selectmenu
$('select#speedA').selectmenu('enable');
$('select#speedA').selectmenu('disable');
// enable / disable option, parameter is index of the option
$('select#speedA').selectmenu('enable', 2);
$('select#speedA').selectmenu('disable', 2);
// enable / disable optgroup, parameter is index of the optgroup and keyword "optgroup"
$('select#speedA').selectmenu('enable', 2, "optgroup");
$('select#speedA').selectmenu('disable', 2, "optgroup");

Callbacks / Events

Available callbacks:

  • open
  • close
  • change (fires when new option is selected)
  • select (fires even when the same option is selected)

Every callback returns a object which looks like this:

  • index (zero-based index of the selected option)
  • option (option element itself)
  • value: (value of the option, string)
$('select').selectmenu({
    change: function(e, object){
        alert(object.value);
    }
});

FAQ

Using Selectmenu within Tabs or Lightboxes

The problem is that the selectmenu is placed within a hidden element. Solution: Include jQuery Peek https://github.com/revsystems/jQuery-Peek) and init like this:
$(“div.tabs”).tabs();
$(“select”).peek(“selectmenu”, { options if you want… });

See this issue for more information: https://github.com/fnagel/jquery-ui/issues#issue/58

Licence

Dual licensed under the MIT and GPL licenses.

Support

Feel free to contact me at the issues bugtracking system (here at GitHub). However, please to be patient with the response. I have only a certain amount of time to support this effort and will allocate it the best I can. It is possible to sponsor development or a fix for your specific problem by placing a donation.

Donate

Please consider a donation if you like this work: http://www.felixnagel.com/donate/

Add a custom footer
Add a custom sidebar

Clone this wiki locally