Select Picker

Canvas bundles Bootstrap Select to turn any native <select> into a searchable, styleable dropdown with support for multiple selection, option groups, live search, and custom button styles. It is initialized automatically on any element with the .selectpicker class, so no extra script is required.

Setup

Add the plugin stylesheet in the <head> and its two scripts before </body> (they ship inside the package under css/components/ and js/components/). Then give any <select> the .selectpicker class.

<!-- In <head> -->
<link rel="stylesheet" href="css/components/bs-select.css">

<!-- Basic select -->
<label>Become This:</label>
<select class="selectpicker">
  <option>Mustard</option>
  <option>Ketchup</option>
  <option>Relish</option>
</select>

<!-- Before </body> -->
<script src="js/plugins.min.js"></script>
<script src="js/functions.bundle.js"></script>
<script src="js/components/selectsplitter.js"></script>
<script src="js/components/bs-select.js"></script>

Structure

The picker reads its configuration from data-* attributes on the <select>, <optgroup>, or <option>. The .selectpicker class is the only required part; everything else is opt in.

<!-- Multiple with live search -->
<select class="selectpicker" multiple data-live-search="true">
  <option>Mustard</option>
  <option>Ketchup</option>
  <option>Relish</option>
</select>

<!-- Search tokens, subtext and placeholder title -->
<select class="selectpicker" data-live-search="true" title="Choose...">
  <option data-tokens="ketchup mustard">Hot Dog, Fries and a Soda</option>
  <option data-tokens="mustard">Burger, Shake and a Smile</option>
</select>

<!-- Limit selections and group actions -->
<select class="selectpicker" multiple data-max-options="2" data-actions-box="true">
  <option>Mustard</option>
  <option>Ketchup</option>
  <option>Relish</option>
</select>

<!-- Custom button style and width -->
<select class="selectpicker" data-style="btn-primary" data-width="19%">
  <option>Mustard</option>
  <option>Ketchup</option>
</select>

Options

Set these as data-* attributes on the <select> unless noted:

multiple (attribute): allow selecting more than one option.
data-live-search="true": show a search box inside the dropdown.
data-max-options="2": cap the number of selections. Also valid on an <optgroup> to cap per group.
data-actions-box="true": show Select All / Deselect All buttons (multiple only).
data-header="Select a condiment": a header label at the top of the menu.
title="Choose...": placeholder text shown before a selection is made.
data-size="5": number of visible options before the menu scrolls.
data-show-subtext="true" with data-subtext on options: show secondary text.
data-style="btn-primary": apply a Canvas button style to the toggle (btn-info, btn-warning, btn-success, btn-danger, etc.).
data-width="fit", data-width="300px", or data-width="75%": control the toggle width.
data-tokens="..." (on <option>): extra keywords matched by live search.
disabled (attribute): render the whole picker disabled.

Tips

Combine .selectpicker with .form-control when placing the picker inside standard Bootstrap form layouts.
Use <optgroup label="..."> to group related options. The group label renders as a non selectable heading.

Was this page helpful?