View on GitHub

Bootstrap-select

A custom select for @twitter bootstrap using button dropdown.

Download this project as a .zip file Download this project as a tar.gz file

bootstrap-select

A custom select for @twitter Bootstrap using button dropdown.

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
  });

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>
(Note that you should give your selectpicker a name that ends with array syntax (example: <select name="named[]" class="selectpicker" multiple>) such that all items can be processed with php,... This is the same for <select>s without bootstrap-select.)

You can limit the number of elements you are allowed to select via the data-max-option attribute. It also works for option groups.

  <select class="selectpicker" multiple data-max-options="2">
    <option>Mustard</option>
    <option>Ketchup</option>
    <option>Relish</option>
  </select>

  <select class="selectpicker" multiple  data-max-options="2">
    <optgroup label="Condiments" data-max-options="2">
      <option>Mustard</option>
      <option>Ketchup</option>
      <option>Relish</option>
    </optgroup>
    <optgroup label="Breads" data-max-options="2">
      <option>Plain</option>
      <option>Steamed</option>
      <option>Toasted</option>
    </optgroup>
  </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 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 selected
  • count > x Where X is the number of items selected when the display format changes from values to count
  <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 behaves 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:

With 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>
  <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="overflow:hidden;">
  <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>

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
mobile boolean false enables the device's native menu for select menus
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 'auto', the menu always opens up to show as many items as the window will allow without being cut off

set to false to always show all items

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

auto automatically adjusts the width of the select to accommodate its widest option

set the width of the select manually, e.g. 300px or 50%

maxOptions integer | false (where # is an integer) false

When set and in a multi

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');

destroy()

To programmatically destroy (remove) the bootstrap-select use the destroy method to destroy it.

   $('.selectpicker').selectpicker('destroy');