Jay Taylor's notes
back to listing indexBootstrap-select
[web search]bootstrap-select
A custom select for @twitter Bootstrap using button dropdown.
Example
Make this:
Become this:
- <select class="selectpicker">
- <option>Mustard</option>
- <option>Ketchup</option>
- <option>Relish</option>
- </select>
It also works with option groups:
- <select class="selectpicker">
- <optgroup label="Picnic">
- <option>Mustard</option>
- <option>Ketchup</option>
- <option>Relish</option>
- </optgroup>
- <optgroup label="Camping">
- <option>Tent</option>
- <option>Flashlight</option>
- <option>Toilet Paper</option>
- </optgroup>
- </select>
And with multiple selects:
- <select class="selectpicker" multiple>
- <option>Mustard</option>
- <option>Ketchup</option>
- <option>Relish</option>
- </select>
You can set different Bootstrap classes via the data-style
attribute:
- <select class="selectpicker" data-style="btn-primary">
- </select>
- <select class="selectpicker" data-style="btn-info">
- </select>
- <select class="selectpicker" data-style="btn-success">
- </select>
- <select class="selectpicker" data-style="btn-warning">
- </select>
- <select class="selectpicker" data-style="btn-danger">
- </select>
- <select class="selectpicker" data-style="btn-inverse">
- </select>
You can add a search input by passing data-live-search="true"
attribute:
You can also use the title
attribute as an alternative to display when the option is selected:
Using the title
attribute on a multiple select
will show the default prompt text when nothing is selected (note: this will not work on single select
elements as they must have a selected value):
- <select class="selectpicker" multiple title='Choose one of the following...'>
- <option>Mustard</option>
- <option>Ketchup</option>
- <option>Relish</option>
- </select>
Using the data-selected-text-format
attribute on a multiple select
you can specify how the selection is displayed.
The supported values are:
values
A comma delimted list of selected values. (default)count
If one item is selected, then the value is shown, if more than one is selected then the number of selected items is displayed, eg 2 of 6 selectedcount > x
Where X is the number of items selected when the display format changes fromvalues
tocount
- <select class="selectpicker" multiple data-selected-text-format="count">
- <option>Mustard</option>
- <option>Ketchup</option>
- <option>Relish</option>
- </select>
- <select class="selectpicker" multiple data-selected-text-format="count>3">
- <option>Mustard</option>
- <option>Ketchup</option>
- <option>Relish</option>
- <option>Onions</option>
- </select>
You can also show the tick icon on single select
with the show-tick
class:
- <select class="selectpicker show-tick">
- <option>Mustard</option>
- <option>Ketchup</option>
- <option>Relish</option>
- </select>
The bootstrap menu arrow can be added with the show-menu-arrow
class:
- <select class="selectpicker show-menu-arrow">
- <option>Mustard</option>
- <option>Ketchup</option>
- <option>Relish</option>
- </select>
Classes added to the options are transferred to the select:
- <select class="selectpicker">
- <option>Mustard</option>
- <option class="special">Ketchup</option>
- <option>Relish</option>
- </select>
- .special {
- font-style: italic;
- font-weight: bold !important;
- color:#bc0000 !important;
- background:#000;
Apply .span*
class to the selects to set the width.
- <div class="row-fluid">
- <select class="selectpicker span2">
- </select>
- </div>
Alternatively, use the data-width
attribute to set the width of the select. Set data-width
to 'auto'
to automatically adjust the width of the select to its widest option. An exact value can also be specified, e.g., 300px
or 50%
.
- <div class="row-fluid">
- <select class="selectpicker" data-width="auto">
- </select>
- <select class="selectpicker" data-width="100px">
- </select>
- <select class="selectpicker" data-width="75%">
- </select>
- </div>
Add the disabled
attribute to the select to apply the disabled
class.
- <select class="selectpicker" disabled>
- <option>Mustard</option>
- <option>Ketchup</option>
- <option>Relish</option>
- </select>
Adding disabled="disabled"
to an option transfers to the menu.
- <select class="selectpicker" disabled>
- <option>Mustard</option>
- <option disabled="disabled">Ketchup</option>
- <option>Relish</option>
- </select>
Adding disabled="disabled"
to an option group cascades to the children.
- <select class="selectpicker">
- <optgroup label="Picnic" disabled>
- <option>Mustard</option>
- <option>Ketchup</option>
- <option>Relish</option>
- </optgroup>
- <optgroup label="Camping">
- <option>Tent</option>
- <option>Flashlight</option>
- <option>Toilet Paper</option>
- </optgroup>
- </select>
The size
option is set to 'auto'
by default. When size
is set to 'auto'
, the menu always opens up to show as many items as the window will allow without being cut off. Set size
to false
to always show all items. The size of the menu can also be specifed using the data-size
attribute.
- <select class="selectpicker">
- </select>
- Note: this is the same as:
- <select class="selectpicker" data-size="auto">
- </select>
Specify a number for data-size
to choose the maximum number of items to show in the menu.
- <select class="selectpicker" data-size="5">
- </select>
You can use the plugin scrollYou cross-browser native scroll. The example below behave like mountain lion.
- <select class="selectpicker" data-size="5">
- </select>
Add data-divider="true"
to an option to turn it into a divider.
- <select class="selectpicker">
- <option data-divider="true"></option>
- </select>
Add subtext to an option or optgroup with the data-subtext
attribute:
showSubtext
set to true.
- <select class="selectpicker">
- <option data-subtext="Heinz">Ketchup</option>
- </select>
Add an icon to an option or optgroup with the data-icon
attribute:
- <select class="selectpicker">
- <option data-icon="icon-heart">Ketchup</option>
- </select>
Insert custom HTML into the option with the data-content
attribute:
- <select class="selectpicker">
- <option data-content="<span class='label label-success'>Relish</span>">Relish</option>
- </select>
Add a header to the dropdown menu, e.g. header: 'Select a condiment'
or data-header="Select a condiment"
- <select class="selectpicker" data-header="Select a condiment">
- </select>
Append the select to a specific element, e.g. container: 'body'
or data-container=".main-content"
- <div style=";">
- <select class="selectpicker">
- </select>
- <select class="selectpicker" data-container="body">
- </select>
- <div>
dropupAuto
is set to true by default, which automatically determines whether or not the select should be a dropup. If dropupAuto
is set to false, manually make the select a dropup menu by adding the .dropup
class to the select.
- <select class="selectpicker dropup">
- </select>
Usage
Create your <select>
with the .selectpicker
class.
- <select class="selectpicker">
- <option>Mustard</option>
- <option>Ketchup</option>
- <option>Relish</option>
- </select>
Enable Bootstrap-Select via JavaScript:
- $('.selectpicker').selectpicker();
Options can be passed via data attributes or JavaScript.
- $('.selectpicker').selectpicker({
- style: 'btn-info',
- size: 4
Options
Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-
, as in data-style=""
.
Name | type | default | description |
---|---|---|---|
container | string | false | false | appends the select to a specific element or selector, e.g., container: 'body' | '.main-body' |
countSelectedText | string | '{0} of {1} selected' | sets the format for the text displayed when selectedTextFormat is count or count > # . {0} is the selected amount. {1} is total available for selection. |
dropupAuto | boolean | true | checks to see which has more room, above or below. If the dropup has enough room to fully open normally, but there is more room above, the dropup still opens normally. Otherwise, it becomes a dropup. If dropupAuto is set to false, dropups must be called manually. |
header | string | false | adds a header to the top of the menu; includes a close button by default |
hideDisabled | boolean | false | removes disabled options and optgroups from the menu data-hide-disabled: true |
selectedTextFormat | 'values' | 'count' | 'count > #' (where # is an integer) | null | specifies how the selection is displayed with a multiple select (see here |
size | 'auto' | integer | false | 'auto' | when set to set to |
showSubtext | boolean | false | subtext associated with a selected option will be displayed in the button data-show-subtext: true |
showIcon | boolean | true | Display icon(s) associated with selected option(s) in the button. If false, icons will not be displayed in the button. |
showContent | boolean | true | Display custom HTML associated with selected option(s) in the button. If false, the option value will be displayed instead. |
style | string | null | null | apply a class to the button, see bootstrap buttons styles |
title | string | null | null | Set the default text for bootstrap-select |
width | 'auto' | '#px' | '#%' | null (where # is an integer) | null |
set the width of the select manually, e.g. |
Methods
val()
You can set the selected value by calling the val
method on the element.
- $('.selectpicker').selectpicker('val', 'Mustard');
- $('.selectpicker').selectpicker('val', ['Mustard','Relish']);
This is different to calling val()
directly on the select
element. If you call val()
on the element directly
the bootstrap-select ui will not refresh (as the change event only fires from user interaction). If you use val()
directly, you will need to manually re-render the ui
- $('.selectpicker').val('Mustard');
- $('.selectpicker').selectpicker('render');
- //this is the equivalent of the above
- $('.selectpicker').selectpicker('val', 'Mustard');
selectAll()
This will select all items in a multiple
select.
- $('.selectpicker').selectpicker('selectAll');
deselectAll()
This will deselect all items in a multiple
select.
- $('.selectpicker').selectpicker('deselectAll');
render()
You can force a re-render of the bootstrap-select ui with the render
method. This is useful if you programatically change any underlying values that affect the layout of the element.
- $('.selectpicker').selectpicker('render');
mobile()
Enable mobile scrolling by calling $('.selectpicker').selectpicker('mobile')
. The method for detecting the browser is left up to the user. This enables the device's native menu for select menus.
- if( /Android|webOS|iPhone|iPad|iPod|BlackBerry/i.test(navigator.userAgent) ) {
- $('.selectpicker').selectpicker('mobile');
setStyle()
Modify the class(es) associated with either the button itself or its container.
If changing the class on the container:
- $('.selectpicker').addClass('span12').selectpicker('setStyle');
If changing the class(es) on the button (altering data-style):
- // Replace Class
- $('.selectpicker').selectpicker('setStyle', 'btn-danger');
- // Add Class
- $('.selectpicker').selectpicker('setStyle', 'btn-large', 'add');
- // Remove Class
- $('.selectpicker').selectpicker('setStyle', 'btn-large', 'remove');
refresh()
To programmatically update a select with JavaScript, first manipulate the select, then use the refresh
method to update the UI to match the new state. This is necessary when removing or adding options, or when disabling/enabling a select via JavaScript.
- $('.selectpicker').selectpicker('refresh');
- <select class="selectpicker remove-example">
- <option value="Mustard">Mustard</option>
- <option value="Ketchup">Ketchup</option>
- <option value="Relish">Relish</option>
- </select>
- <button class="btn btn-warning rm-mustard">Remove Mustard</button>
- <button class="btn btn-danger rm-ketchup">Remove Ketchup</button>
- <button class="btn btn-success rm-relish">Remove Relish</button>
- $('.rm-mustard').click(function() {
- $('.remove-example').find('[value=Mustard]').remove();
- $('.remove-example').selectpicker('refresh');
- $('.ex-disable').click(function() {
- $('.disable-example').prop('disabled',true);
- $('.disable-example').selectpicker('refresh');
- $('.ex-enable').click(function() {
- $('.disable-example').prop('disabled',false);
- $('.disable-example').selectpicker('refresh');
hide()
To programmatically hide the bootstrap-select use the hide
method to hide it.
- $('.selectpicker').selectpicker('hide');
show()
To programmatically show the bootstrap-select use the show
method to show it.
- $('.selectpicker').selectpicker('show');