multi-list

A jQuery plugin to turn an unordered list into a multiple selectable list. Written by Albert Gonzalez and released under the Unlicense.

See it in action!

Install

Download the .js and .css files or install them using npm:

npm install multi-list

Starting

You'll need and <ul> with some entries and a unique value for each item:

<ul>
  <li value='eur'>Europe</li>
  <li value='oce'>Oceania</li>
  <li value='afr'>Africa</li>
  <li value='asi'>Asia</li>
  <li value='nam'>North Americ</li>
  <li value='sam'>South America</li>
  <li value='mea'>Middle East</li>
</ul>

Then, to create the multi-list:

$("#list").multiList();

Now you're ready!

Methods

Select or unselect all the elements:

$('#list').multiList('selectAll');
$('#list').multiList('unselectAll');

Select a single element (using the list value):

$('#list').multiList('select', 'asi');

Hide or show elements from the list. The current selected state for a hidden element doesn't change. Also, the select method won't select a hidden element, but a selectAll method will do it (same with the unselect related methods):

$('#list').multiList('hide', 'oce');
$('#list').multiList('show', ['nam', 'sam']); // array of values also accepted
$('#list').multiList('hideAll');
$('#list').multiList('showAll');

Disable or enable an element (won't be able to be selected when clicking, but you can still using the select methods):

$('#list').multiList('disable', 'afr');
$('#list').multiList('enable', 'afr');

Change the name for an existing element:

$('#list').multiList('setName', 'mea', 'Middle-Earth');

Get the selected or unselected elements:

var selected_elements = $('#list').multiList('getSelected'); // returns an array of values: ['sam', 'nam', 'asi']
var selected_elements_full = $('#list').multiList('getSelectedFull'); // returns an array of pair values-name: [['sam', 'South America'], ['nam', 'North America'], ['asi','Asia']]
var unselected_elements_full = $('#list').multiList('getUnselectedFull');

Events

The events are triggered when selecting or unselecting an element:

$('#list').on('multiList.elementChecked', function(event, value, text) {
  console.log('Checked the element ' + value + ' with text ' + text);
});

$('#list').on('multiList.elementUnchecked', function(event, value, text) {
  console.log('Unchecked the element ' + value + ' with text ' + text);
});