Combobox combobox.js

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:

$('#myCombobox').combobox();

The combobox also accepts an optional options param during initialization:

$('#myCombobox').combobox({autoResizeMenu: false});

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.

<div class="input-group input-append dropdown combobox" id="myCombobox" data-initialize="combobox">
  <input class="form-control" type="text">
  <div class="input-group-btn">
    <button class="btn btn-default dropdown-toggle" data-toggle="dropdown" type="button"><span class="caret"></span></button>
    <ul class="dropdown-menu dropdown-menu-right">
      <li data-value="1"><a href="#">One</a></li>
      ...
    </ul>
  </div>
</div>

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

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.

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

$('#myCombobox').combobox('selectByIndex', '1');

.combobox('selectByText')

Set the selected item based on its text value.

$('#myCombobox').combobox('selectByText', 'Four');

.combobox('selectBySelector')

Set the selected item based on a selector.

$('#myCombobox').combobox('selectBySelector', 'li[data-fizz=buzz]');

.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

$('#myCombobox').combobox('selectByValue', '1');

Events

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

<div class="input-group input-append dropdown combobox" id="myCombobox" data-initialize="combobox">..</div>

You would attach your event listener thusly:

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

Examples

<div class="input-group input-append dropdown combobox" id="myCombobox" data-initialize="combobox">
	<input class="form-control" type="text">
	<div class="input-group-btn">
		<button class="btn btn-default dropdown-toggle" data-toggle="dropdown" type="button"><span class="caret"></span></button>
		<ul class="dropdown-menu dropdown-menu-right">
			<li data-value="1"><a href="#">One</a></li>
			<li data-value="2"><a href="#">Two</a></li>
			<li data-value="3"><a href="#">Three</a></li>
			<li data-value="4" ><a href="#">Four</a></li>
			<li data-value="Item Five" data-foo="bar" data-fizz="buzz"><a href="#">Item Five</a></li>
		</ul>
	</div>
</div>

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.