Automatically turn your select elements into bootstrap list groups or turn your bootstrap list groups into selectable lists.
This plugin continues where Bootstrap ends and provides dynamic behavior for their list groups. Beyond that, it provides the means to turn an HTML select element into a styled list group with corresponding select behavior and with the select element as hidden data source such that form posts are retained.
Listgroup.js only depends on jQuery (which must be included before listgroup.js). This means no other Bootstrap plugin is required.
All the examples on this page is live - try them out by clicking on different elements in each list.
The most basic example is simply an unordered list with list items, and the proper classes as provided by Bootstrap. When you drop in the listgroup.js plugin all lists with the list-group class will automatically be augmented with selectable behavior leveraging the active class.
<ul class="list-group">
<li class="list-group-item active">Cras justo odio</li>
<li class="list-group-item">Dapibus ac facilisis in</li>
<li class="list-group-item">Morbi leo risus</li>
<li class="list-group-item">Porta ac consectetur ac</li>
<li class="list-group-item">Vestibulum at eros</li>
</ul>The basic example of a <select> element is to simply add the list-group class. This will generate a list group with the select element as data source.
The actual select element below is only visible here for you to see that it updates when you click the list items and vice versa. Normally it is hidden but still there if you need it.
<select class="list-group">
<option>Cras justo odio</option>
<option>Dapibus ac facilisis in</option>
<option>Morbi leo risus</option>
<option>Porta ac consectetur ac</option>
<option>Vestibulum at eros</option>
</select>You can use all Bootstrap plugins purely through the markup API without writing a single line of JavaScript. Like in Bootstrap this is the first-class API and should be your first choice.
As with Bootstrap plugins you can also use listgroup.js through the JavaScript API. All public APIs are built using jQuery plugin conventions and style, which means you have chainable methods which returns the collection it acted on.
List groups are a powerful Bootstrap component and is fully supported by listgroup.js (hence the name). Read the documentation for Bootstrap list groups for detailed descriptions over its features such as badges, disabled items, contextual classes, and more.
Listgroup.js tries to mimic the behavior of select elements as well as conventions in other Bootstrap plugins. Thus single selection of list groups is the default.
<div class="list-group">
<a href="#" class="list-group-item active">Cras justo odio</a>
<a href="#" class="list-group-item">Dapibus ac facilisis in</a>
<a href="#" class="list-group-item active">Morbi leo risus</a>
<a href="#" class="list-group-item">Porta ac consectetur ac</a>
<a href="#" class="list-group-item">Vestibulum at eros</a>
</div>Add data-toggle="items" to a list group to activate the ability to select more than one item as well as checkbox style toggling .
Compare with toggling in the Button plugin
<div class="list-group" data-toggle="items">
<a href="#" class="list-group-item active">Cras justo odio</a>
<a href="#" class="list-group-item">Dapibus ac facilisis in</a>
<a href="#" class="list-group-item active">Morbi leo risus</a>
<a href="#" class="list-group-item">Porta ac consectetur ac</a>
<a href="#" class="list-group-item">Vestibulum at eros</a>
</div>Bootstrap supports disabled list group items with the disabled class. Listgroup.js also support this by ignoring clicks on disabled items.
<div class="list-group">
<a href="#" class="list-group-item">Cras justo odio</a>
<a href="#" class="list-group-item disabled">Dapibus ac facilisis in</a>
<a href="#" class="list-group-item">Morbi leo risus</a>
<a href="#" class="list-group-item">Porta ac consectetur ac</a>
<a href="#" class="list-group-item">Vestibulum at eros</a>
</div>The HTML <select> element represents a list of options. Listgroup.js support this by automatically generating a list group with a list group item for each option.
An option can have different state or attributes including selected, disabled, and hidden. The state is translated to a similar concept in Bootstrap list groups. If an option has a value it is copied to the data-value attribute.
By default only one option can be selected at a time. Add multiple attribute to a <select> element to indicate that multiple options can be selected in the list. With listgroup.js this also activates checkbox style toggling of items (instead of using Ctrl+click).
<select class="list-group" multiple>
<option selected="selected">Cras justo odio</option>
<option>Dapibus ac facilisis in</option>
<option selected="selected">Morbi leo risus</option>
<option>Porta ac consectetur ac</option>
<option>Vestibulum at eros</option>
</select>Add disabled attribute to an option to make it not checkable and it won’t receive any browsing event, like mouse clicks or focus-related ones. This translates to the disabled class in Bootstrap.
<select class="list-group" multiple>
<option>Cras justo odio</option>
<option disabled>Dapibus ac facilisis in</option>
<option>Morbi leo risus</option>
<option disabled>Porta ac consectetur ac</option>
<option>Vestibulum at eros</option>
</select>Option elements which have the style display:none either directly or via a class are generated as hidden list group items using the hidden class.
Right-click the list group to Inspect element with your browser developer tools. You'll find the hidden elements there.
<select class="list-group" multiple>
<option>Cras justo odio</option>
<option style="display:none">Dapibus ac facilisis in</option>
<option>Morbi leo risus</option>
<option class="hidden">Porta ac consectetur ac</option>
<option>Vestibulum at eros</option>
</select>Because this project just got off the ground not everything have been documented fully. Examples of functions that exist but which will be described here incrementally are
Check out the status of the project and upcomming features on Github