The combobox control combines an input and a drop-down for easy and flexible data selection. Combobox also offers many methods that allow you to programmatically manipulate it.

Usage

Via JavaScript

Call the combobox control via JavaScript:

{% highlight js %}$('#myCombobox').combobox();{% endhighlight %}

The combobox also accepts an optional options param during initialization:

{% highlight js %}$('#myCombobox').combobox({autoResizeMenu: false});{% endhighlight %}

Via data-attributes

Add data-initialize="combobox" to the .combobox element that you wish to initialize on $.ready(). Any combobox that is programmatically generated after the initial page load will initialize when the mousedown event is fired on it if it has data-initialize="combobox".

Markup

A combobox consists of an input group containing a text input with a selectlist appended to it. {% highlight html %}

{% endhighlight %}

Markup options

The following options are applicable to the li elements of the selectlist. Append the option name to data-, as in data-selected="true".

Name	type	default	description
selected	boolean	false	Indicates element should be selected by default.

Programmatic options

Should be passed in as an object (eg. {name: value}) on intialization. Javascript initialization is required (you can't initialize through data-attributes) if you would like to use this.

Name	type	default	description
autoResizeMenu	boolean	true	Resizes the drop-down menu to the width of the combobox

Methods

Once your combobox is initialized, you can execute any of the following methods on it:

.combobox('destroy'): Remove all functionality, jQuery data, and the markup from the DOM. Returns string of control markup.
.combobox('disable'): Disable the combobox
.combobox('enable'): Enable the combobox
.combobox('selectedItem'): Returns an object containing a text property with the visible text of the selected item as well as the results of a jQuery .data() call on the selected item (which will map the contents of any data-* attributes into the returned object).
.combobox('selectByIndex'): Set the selected item based on its index in the list (zero-based index). Convenience method for .selectBySelector('li:eq({index})') {% highlight js %}$('#myCombobox').combobox('selectByIndex', '1');{% endhighlight %}
.combobox('selectByText'): Set the selected item based on its text value. {% highlight js %}$('#myCombobox').combobox('selectByText', 'Four');{% endhighlight %}
.combobox('selectBySelector'): Set the selected item based on a selector. {% highlight js %}$('#myCombobox').combobox('selectBySelector', 'li[data-fizz=buzz]');{% endhighlight %}
.combobox('selectByValue'): Set the selected item based on its value. Convenience method for .selectBySelector('data-value={value}') that requires the item to include a .data-value="{value}" attribute {% highlight js %}$('#myCombobox').combobox('selectByValue', '1');{% endhighlight %}

Events

Event Type	Description
changed.fu.combobox	This event fires when the value changes (either by selecting an item from the list or updating the input value directly). Arguments include `event, data` where data represents the same object structure returned by the `selectedItem` method.

All combobox event listeners should be attached to the element containing the combobox class; given the following HTML:

{% highlight html %} {% endhighlight %}

You would attach your event listener thusly:

{% highlight js %} $('#myCombobox').on('changed.fu.combobox', function (evt, data) { // do something… }); {% endhighlight %}

Examples

{% include js/combobox-example.html %}

Alignment

The dropdown-menu-right class on the ul in the example markup causes the drop-down menu to appear directly underneath the dropdown, its right side appearing flush with the right side of the triggering element. If you wish the dropdown menu's left side to align with the left side of the triggering button's left side, exclude the dropdown-menu-right class on the ul.

Combobox combobox.js