Single & Multi-Select Listbox Plugin - jQuery Consistent Listbox

consistent-listbox is a tiny jQuery/jQuery UI plugin that creates user-friendly, cross-platform, drag-and-drop sortable single-select and multi-select listbox controls for HTML forms. 

It's designed to give you a form-ready listbox component that looks and behaves predictably regardless of the device or platform.

Features:

• Cross-platform consistency: Renders identically on mobile devices and desktop browsers.
• Dual selection modes: Supports both single-select and multi-select configurations.
• Drag-and-drop sorting: Built-in manual sorting with visual feedback. Requires jQuery UI.
• Useful API: Over 40 methods for programmatic list manipulation.
• Form integration: Works seamlessly with HTML forms and standard submission processes.
• Auto-sorting capabilities: Configurable automatic sorting by text, value, or custom properties.
• Event handling: onChange and onClick events with detailed callback data.
• Data management: Rich data binding with custom property support.

How to use it:

1. Load the necessary jQuery library and jQuery UI framework in the document.

<link rel="stylesheet" href="/path/to/cdn/jquery-ui.min.css" />
<script src="/path/to/cdn/jquery.min.js"></script>
<script src="/path/to/cdn/jquery-ui.min.js"></script>

2. Download the plugin and load the following files:

<link href="/path/to/listbox.min.css" rel="stylesheet"/>
<script src="/path/to/listbox.min.js"></script>

3. Create an empty container to hold your listbox.

<div id="example" class="sl-listbox sl-h-20"></div>

4. Initialize the listbox with your data array. Each item requires a value and text property, with an optional checked property for default selection.

$('#example').listbox({
  multiSelect: true, // defaults to false
  name: 'selected_name', // required if you have multiple listboxes
  items: [
    {val: '1', text: 'Item 1', checked: true},
    {val: '2', text: 'Item 2', checked: true},
    {val: '3', text: 'Item 3'},
    {val: '4', text: 'Item 4', checked: true},
    {val: '5', text: 'Item 5'},
  ],
  onChange: function(e, val) {
    console.log('multilistbox onChange', val.old, val.cur);
  },
  onClick: function(e, val) {
    console.log('multilistbox onClick', val);
  },
});

5. All default plugin options.

• multiSelect: (boolean) Set to true for a multi-select listbox. Defaults to false.
• name: (string) The HTML name attribute for the underlying input. This is critical when using multiple listboxes on one page.
• sortable: (boolean) Allows users to manually reorder items by dragging them. Defaults to false.
• autoSort: (boolean) Enables automatic sorting of items. Defaults to false.
• items: (array) The initial array of item objects to populate the listbox.
• quiet: (boolean) If true, it disables the onChange callback from being fired on initialization.

$('#example').listbox({
  multiSelect: false,
  name: 'lb_name',
  quiet: false,
  autoSort: false,
  sortOrder: null,
  isSortByDataProp: null,
  sortable: false,
  sortOrderStep: 10,
});

6. API methods.

// Adds a item.
add(item, [, is_quiet][, e])

// Deletes all items.
clear([, is_quiet][, e])

// Deletes the specified item.
delete(value[, is_quiet][, e])

// Gets assigned data.
getAllData([is_as_array][, is_return_text][, text_alias])

// Gets selected item assigned data.
getData()

// Gets a user-defined data property by key.
getDataVar(key)

// Gets item object by an item value.
getItem(value[, is_with_data])

// Gets item assigned data by an item value.
getItemData(value)

// Gets user-defined data property by item value and property key.
getItemDataVar(value, key)

// Gets item text by value.
getItemText(value)

// Returns sort_order property of the related data.
getSortOrder()

// Gets selected item text.
getText()

// Checks if an element with the specified value exists.
hasItem(value)

// Checks if at least one item is selected.
hasSelected()

// Inserts a item into the specified position.
insert(index, item, [, is_quiet][, e])

// Gets selected item object.
item([is_with_data])

// Gets list of selected items.
items([is_with_data])

// Returns the number of items.
length()

// Removes the selected items.
remove([is_quiet][, e])

// Deletes all items and insert specified new items.
replace(new_data[, is_quiet][, e])

// Replaces the user-defined data with a new object.
replaceData(new_data[, is_update_text][, text_alias])

// Replaces the user-defined data with a new object by item value.
replaceItemData(value, new_data[, is_update_text][, text_alias])

// Selects the specified item.
select(value[, is_quiet][, e])

// Sets a user-defined data property by key.
setDataVar(key, prop)

// Sets user-defined data property by item value and property key.
setItemDataVar(value, key, prop)

// Sets item text by value.
setItemText(value, text)

// Replaces selected item value.
setItemVal(value, new_value[, is_quiet][, e])

// Sets sort_order property of the related data.
setSortOrder(sort_order)

// Sets selected item text.
setText(text)

// Replaces selected item value.
setVal(new_value[, is_quiet][, e])

// Sorts items.
sort()

// Sorts items.
sortBy([is_sort_by_data_prop])

// Unsets a user-defined data property property by key.
unsetDataVar(key)

// Unsets a user-defined data property property by item value and property key.
unsetItemDataVar(value, key)

// Updates related user-defined data.
updateData(data[, is_update_text][, text_alias])

// Updates related user-defined data by item value.
updateItemData(value, data[, is_update_text][, text_alias])

// Returns selected item value.
val()

// Returns selected items values.
vals()

FAQs:

Q: Can I use this plugin with form submissions?
A: Yes, the plugin generates proper form inputs with the specified name attribute. Selected values are submitted normally with form data, making it compatible with standard form processing workflows.

Q: How do I handle dynamic data updates from AJAX calls?
A: Use the replace() method to completely refresh the listbox data, or combine clear() followed by multiple add() calls. Set the is_quiet parameter to true during bulk updates to prevent excessive event firing.

Q: What's the difference between sortOrder and isSortByDataProp options?
A: sortOrder specifies which data property to use for sorting, while isSortByDataProp determines whether to sort by that property (true), by item value (false), or by item text (null). This gives you fine control over sorting behavior.

Q: Can I customize the appearance beyond the included CSS?
A: Yes, the plugin uses standard CSS classes prefixed with 'sl-'. You can override these styles or create custom themes.

Q: How do I prevent the onChange event when making programmatic changes?
A: Pass true as the is_quiet parameter to methods like select(), add(), or delete(). This suppresses the onChange event while still updating the listbox state and visual appearance.

Changelog:

2025-09-17

• Remove the change event handler on destroy.

2025-08-11

• Added drag icon

About Author:

Author: Simon Litt

GitHub: https://github.com/SimonLitt

See Also:

• 10 best Dual List Box Plugins In JavaScript
• 10 best Multiple select Plugins In JavaScript

---

This awesome jQuery plugin is developed by SimonLitt. For more Advanced Usages, please check the demo page or visit the official website.