CrestApps fork

The options and data attributes documented on this page are part of the current forward-only API. Initialize with new Selectpicker('#sel', options) or add the selectpicker class for automatic initialization. Global defaults are set with Selectpicker.setDefaults({ ... }).

Core options

---

Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-, as in data-style="" or data-selected-text-format="count".

Data attributes

For security reasons, the sanitize, sanitizeFn, and whiteList options cannot be supplied using data attributes.

Name	Type	Default	Description
actionsBox	boolean	false	When set to true, adds two buttons to the top of the dropdown menu (Select All & Deselect All).
countSelectedText	string | function	function	Sets the format for the text displayed when selectedTextFormat is count or count > #. {0} is the selected amount. {1} is total available for selection. When set to a function, the first parameter is the number of selected options, and the second is the total number of options. The function must return a string.
deselectAllText	string	'Deselect All'	The text on the button that deselects all options when actionsBox is enabled.
dropdownAlignRight	boolean | 'auto'	false	Align the menu to the right instead of the left. If set to 'auto', the menu will automatically align right if there isn't room for the menu's full width when aligned to the left.
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
iconBase	string	''	Set the base class for an icon font such as Font Awesome. If changing iconBase, you might also want to change tickIcon, in case the icon font uses a different naming scheme.
liveSearch	boolean	false	When set to true, adds a search box to the top of the selectpicker dropdown.
liveSearchNormalize	boolean	false	Setting liveSearchNormalize to true allows for accent-insensitive searching.
liveSearchPlaceholder	string	null	When set to a string, a placeholder attribute equal to the string will be added to the liveSearch input.
liveSearchStyle	string | function	'contains'	When set to 'contains', searching will reveal options that contain the searched text. For example, searching for pl with return both Apple, Plum, and Plantain. When set to 'startsWith', searching for pl will return only Plum and Plantain. If a function is used, the arguments are the option string and the searched text and it must return true if the option matches or false.
openOptions	boolean	false	When set to true, the live-search UI shows a Create action whenever the current search text does not exactly match an existing option. If options.source.create(callback, searchValue) is supplied, it will be used to resolve the created option. Otherwise the control creates a local option using the search text for both text and value.
openOptionsText	string	'Create "{0}"'	Sets the label for the open-option create action. {0} is replaced with the current search text.
maxOptions	integer | false	false	When set to an integer and in a multi-select, the number of selected options cannot exceed the given value. This option can also exist as a data-attribute for an <optgroup>, in which case it only applies to that <optgroup>.
maxOptionsText	string | array | function	function	The text that is displayed when maxOptions is enabled and the maximum number of options for the given scenario have been selected. If a function is used, it must return an array. array[0] is the text used when maxOptions is applied to the entire select element. array[1] is the text used when maxOptions is used on an optgroup. If a string is used, the same text is used for both the element and the optgroup.
multipleSeparator	string	', '	Set the character displayed in the button that separates selected options.
noneSelectedText	string	'Nothing selected'	The text that is displayed when a multiple select has no selected options.
noneResultsText	string	'No results matched {0}'	The text displayed when a search doesn't return any results.
placeholder	string | null	null	Sets the placeholder text shown in the button when nothing is selected. For backward compatibility, a single select's title attribute is also used when placeholder is not set.
selectAllText	string	'Select All'	The text on the button that selects all options when actionsBox is enabled.
selectedTextFormat	'values' | 'static' | 'count' | 'count > x' (where x is an integer)	'values'	Specifies how the selection is displayed with a multiple select. 'values' displays a list of the selected options (separated by multipleSeparator). 'static' displays the configured placeholder text. 'count > x' behaves like 'values' until the number of selected options is greater than x; after that, it displays the total number of selected options. 'count' is an alias for 'count > 1'.
selectOnTab	boolean	false	When set to true, treats the tab character like the enter or space characters within the selectpicker dropdown.
showContent	boolean	true	When set to true, display custom HTML associated with selected option(s) in the button. When set to false, the option value will be displayed instead.
showIcon	boolean	true	When set to true, display icon(s) associated with selected option(s) in the button.
showSubtext	boolean	false	When set to true, display subtext associated with a selected option in the button.
showSelectedTags	boolean	false	For live-search selects, shows the current selections as removable tags that stay visible on the control, similar to a taxonomy tags editor. The button uses a compact summary instead of repeating the selected values.
showTick	boolean	false	Shows the default checkmark indicator on single-select menus. Multiselect menus already render a selection indicator by default.
selectedItemsStyle	'tags' | 'list'	'tags'	Controls how removable selected items are rendered when showSelectedTags is enabled. Use 'list' to render them as a Bootstrap list group with a remove button aligned to the right.
selectedTagRemoveLabel	string	'Remove'	Accessible label prefix used for each removable selected item when showSelectedTags is enabled.
selectionIndicator	'checkmark' | 'checkbox'	'checkmark'	Controls how selected items are indicated in the dropdown. Use 'checkbox' to render a Bootstrap-style checkbox column on multiselects, or radio-style indicators automatically on single selects, instead of the default floating checkmark.
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. When set to an integer, the menu will show the given number of items, even if the dropdown is cut off. When set to false, the menu will always show all items.
style	string | null	'btn-light'	When set to a string, add the value to the button's style.
tickIcon	string	'bs-ok-default'	Set which icon to use to display as the "tick" next to selected options.
virtualScroll	boolean | integer	600	If enabled, the items in the dropdown will be rendered using virtualization (i.e. only the items that are within the viewport will be rendered). This drastically improves performance for selects with a large number of options. Set to an integer to only use virtualization if the select has at least that number of options.
width	'auto' | 'fit' | css-width | false	false	Controls the rendered width of the picker. Use the data-width attribute in markup or pass width in JavaScript. 'auto' expands to the widest option, 'fit' keeps the control compact to the selected option, and a CSS width such as 300px or 75% is applied inline. When set to false, the picker follows the width of its container.
sanitize	boolean	true	Enable or disable the sanitization. If activated, 'data-content' on individual options will be sanitized.
whiteList	object	Default value	Object which contains allowed attributes and tags
sanitizeFn	null | function	null	Here you can supply your own sanitize function. This can be useful if you prefer to use a dedicated library to perform sanitization.

Bootstrap 5 runtime defaults

This Bootstrap 5 build no longer supports the legacy container, mobile, styleBase, or windowPadding options. When width is not set, the picker follows normal Bootstrap sizing and fills its container by default.

Tags-style live search and open options

The showSelectedTags and openOptions settings are intended for taxonomy-style editors where authors need to keep selected values visible while continuing to search.

When both are enabled on a multiple select:

1. Selected values stay visible as removable tags on the control while the search UI stays available.
2. Typing a value that does not exactly match an existing option shows a create action.
3. Choosing that action creates and selects the option immediately.

Use data attributes when local in-browser creation is enough:

<select
  class="selectpicker"
  multiple
  data-live-search="true"
  data-show-selected-tags="true"
  data-open-options="true"
  placeholder="Search or create tags">
  <option selected>Orchard Core</option>
  <option>Vue</option>
  <option>Taxonomy</option>
</select>

Use JavaScript when the picker is backed by a remote source and new terms must be saved first:

new Selectpicker('#tag-editor', {
  liveSearch: true,
  showSelectedTags: true,
  openOptions: true,
  openOptionsText: 'Create tag "{0}"',
  selectedTagRemoveLabel: 'Remove tag',
  selectionIndicator: 'checkbox',
  source: {
    data: function (callback) {
      callback(existingTags);
    },
    search: function (callback, page, searchValue) {
      callback(findMatchingTags(searchValue));
    },
    create: function (callback, searchValue) {
      createTag(searchValue).then(function (tag) {
        callback({
          text: tag.displayText,
          value: tag.id
        });
      });
    }
  }
});

source.create can return the created option synchronously, invoke the provided callback later, or resolve a Promise. In each case, the picker adds the returned option and selects it automatically.

Default settings

---

You can change the default settings for bootstrap-select by modifying its DEFAULTS object (or by calling Selectpicker.setDefaults({ … })):

Selectpicker.DEFAULTS.multipleSeparator = ' | ';

Events

---

bootstrap-select emits native CustomEvents on the original <select> element. See the dedicated Events page for the full event reference, event payload details, and examples for changed.bs.select, show.bs.select, and the rest of the public event surface.

Sanitizer

---

HTML added via the data-content attribute on individual options is sanitized using our built-in sanitizer.

The default whiteList value is the following:

var ARIA_ATTRIBUTE_PATTERN = /^aria-[\w-]*$/i;
var DefaultWhitelist = {
  // Global attributes allowed on any supplied element below.
  '*': ['class', 'dir', 'id', 'lang', 'role', 'tabindex', 'style', ARIA_ATTRIBUTE_PATTERN],
  a: ['target', 'href', 'title', 'rel'],
  area: [],
  b: [],
  br: [],
  col: [],
  code: [],
  div: [],
  em: [],
  hr: [],
  h1: [],
  h2: [],
  h3: [],
  h4: [],
  h5: [],
  h6: [],
  i: [],
  img: ['src', 'alt', 'title', 'width', 'height'],
  li: [],
  ol: [],
  p: [],
  pre: [],
  s: [],
  small: [],
  span: [],
  sub: [],
  sup: [],
  strong: [],
  u: [],
  ul: []
}

If you want to add new values to this default whiteList you can do the following:

var myDefaultWhiteList = Selectpicker.DEFAULTS.whiteList;

// To allow table elements
myDefaultWhiteList.table = [];

// To allow td elements and data-option attributes on td elements
myDefaultWhiteList.td = ['data-option'];

// You can push your custom regex to validate your attributes.
// Be careful about your regular expressions being too lax
var myCustomRegex = /^data-my-app-[\w-]+/;
myDefaultWhiteList['*'].push(myCustomRegex);

If you want to bypass our sanitizer because you prefer to use a dedicated library, you should do the following:

new Selectpicker('#yourSelect', {
  sanitizeFn: function (domNodes) {
    return DOMPurify.sanitize(domNodes)
  }
});

For performance reasons, our built-in sanitizer accepts an array of DOM nodes as its first argument, rather than an HTML string. Keep that in mind if deciding to use your own sanitizeFn.