Virtuosoft Logo

Bootstrap Dual Listbox

Github project page Download

Bootstrap Dual Listbox is a responsive dual listbox widget optimized for Twitter Bootstrap. It works on all modern browsers and on touch devices.

Example with default values

The dual listbox is created from a select multiple by calling .bootstrapDualListbox(settings); on a selector. The selector can be any element, not just selects. When the method is called on a selector other than a select, then all select childrens are converted into dual list boxes. 

var demo1 = $('select[name="duallistbox_demo1[]"]').bootstrapDualListbox();

Example with custom settings

var demo2 = $('.demo2').bootstrapDualListbox({
  nonSelectedListLabel: 'Non-selected',
  selectedListLabel: 'Selected',
  preserveSelectionOnMove: 'moved',
  moveOnSelect: false,
  nonSelectedFilter: 'ion ([7-9]|[1][0-2])'
});

Dynamically add options to the selects

The options must be added to/removed from the original select.
Note that the refresh must be run on it after manipulating the options.

If there are some highlighted options in the lists, then calling the refresh method with the optional true parameter results the highlights to be removed. Example usage: demo2.bootstrapDualListbox('refresh', true);
It has meaning only when moveOnSelect setting is false. 

$("#demo2-add").click(function() {
  demo2.append('');
  demo2.bootstrapDualListbox('refresh');
});

$("#demo2-add-clear").click(function() {
  demo2.append('');
  demo2.bootstrapDualListbox('refresh', true);
});

Settings

When calling $("#element").bootstrapDualListbox() you can pass a parameters object with zero or more of the following:

Option Description
bootstrap2Compatible false: set this to true if you want graphic compatibility with Bootstrap 2.
filterTextClear 'show all': the text for the "Show All" button.
filterPlaceHolder 'Filter': the placeholder for the input element for filtering elements.
moveSelectedLabel 'Move selected': the label for the "Move Selected" button.
moveAllLabel 'Move all': the label for the "Move All" button.
removeSelectedLabel 'Remove selected': the label for the "Remove Selected" button.
removeAllLabel 'Remove all': the label for the "Remove All" button.
moveOnSelect true: determines whether to move options upon selection. This option is forced to true on the Android browser.
preserveSelectionOnMove false: can be 'all' (for selecting both moved elements and the already selected ones in the target list) or 'moved' (for selecting moved elements only)
selectedListLabel false: can be a string specifying the name of the selected list.
nonSelectedListLabel false: can be a string specifying the name of the non selected list.
helperSelectNamePostfix '_helper': The added selects will have the same name as the original one, concatenated with this string and 1 (for the non selected list, e.g. element_helper1) or 2 (for the selected list, e.g. element_helper2).
selectorMinimalHeight 100: represents the minimal height of the generated dual listbox.
showFilterInputs true: whether to show filter inputs.
nonSelectedFilter '': initializes the dual listbox with a filter for the non selected elements. This is applied only if showFilterInputs is set to true.
selectedFilter '': initializes the dual listbox with a filter for the selected elements. This is applied only if showFilterInputs is set to true.
infoText 'Showing all {0}': determines which string format to use when all options are visible. Set this to false to hide this information. Remember to insert the {0} placeholder.
infoTextFiltered '<span class="label label-warning">Filtered</span> {0} from {1}': determines which element format to use when some element is filtered. Remember to insert the {0} and {1} placeholders.
infoTextEmpty 'Empty list': determines the string to use when there are no options in the list.
filterOnValues false: set this to true to filter the options according to their values and not their HTML contents.

Methods

You can modify the behavior and aspect of the dual listbox by calling its methods, all of which accept a value and a refresh option. The value determines the new parameter value, while refresh (optional, defaults to false) tells whether to update the plugin UI or not.

To call methods on the dual listbox instance, use the following syntax:

$(selector).bootstrapDualListbox(methodName, parameter);

Note: when making multiple chained calls to the plugin, set refresh to true to the last call only, in order to make a unique UI change; alternatively, you can also call the refresh method as your last one.

Here are the available methods:

Method Description
refresh() update the plugin element UI.
destroy() restore the original select element and delete the plugin element.
getContainer() get the container element.
setBootstrap2Compatible(value, refresh) change the bootstrap2Compatible parameter.
setFilterTextClear(value, refresh) change the filterTextClear parameter.
setFilterPlaceHolder(value, refresh) change the filterPlaceHolder parameter.
setMoveSelectedLabel(value, refresh) change the moveSelectedLabel parameter.
setMoveAllLabel(value, refresh) change the moveAllLabel parameter.
setRemoveSelectedLabel(value, refresh) change the removeSelectedLabel parameter.
setRemoveAllLabel(value, refresh) change the removeAllLabel parameter.
setMoveOnSelect(value, refresh) change the moveOnSelect parameter.
setPreserveSelectionOnMove(value, refresh) change the preserveSelectionOnMove parameter.
setSelectedListLabel(value, refresh) change the selectedListLabel parameter.
setNonSelectedListLabel(value, refresh) change the nonSelectedListLabel parameter.
setHelperSelectNamePostfix(value, refresh) change the helperSelectNamePostfix parameter.
setSelectOrMinimalHeight(value, refresh) change the selectOrMinimalHeight parameter.
setShowFilterInputs(value, refresh) change the showFilterInputs parameter.
setNonSelectedFilter(value, refresh) change the nonSelectedFilter parameter.
setSelectedFilter(value, refresh) change the selectedFilter parameter.
setInfoText(value, refresh) change the infoText parameter.
setInfoTextFiltered(value, refresh) change the infoTextFiltered parameter.
setInfoTextEmpty(value, refresh) change the infoTextEmpty parameter.
setFilterOnValues(value, refresh) change the filterOnValues parameter.

Download

Download from github. Please report issues and suggestions to github's issue tracker or contact me on g+ or twitter!

Follow us to get notified about the upcoming tools!

Follow us on LinkedIn to get notified about the upcoming tools, and feel free to share your thoughts with us! We welcome any jQuery/Bootstrap plugin suggestions which can help you and the others.

Comments

Like this plugin, have a question or just want to say hello? Feel free to leave a comment below.