Options Reference

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".

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

Core Options

Name	Type	Default	Description
`actionsBox`	boolean	`false`	When `true`, adds Select All & Deselect All buttons to the top of the dropdown.
`container`	string \| false	`false`	Appends the select to a specific element, e.g., `container: 'body'`. Useful for menus inside elements with `overflow: hidden`.
`countSelectedText`	string \| function	`function`	The text format for `selectedTextFormat: 'count'`. `{0}` is the selected amount, `{1}` is the total.
`deselectAllText`	string	`'Deselect All'`	The text for the Deselect All button.
`dropdownAlignRight`	boolean \| `'auto'`	`false`	Aligns the menu to the right. If `'auto'`, it aligns right automatically if there's not enough space on the left.
`dropupAuto`	boolean	`true`	Automatically opens the menu upwards if there is more space above than below.
`header`	string	`false`	Adds a header to the top of the menu.
`hideDisabled`	boolean	`false`	Removes disabled options and optgroups from the menu.
`iconBase`	string	`'glyphicon'`	The base class for icons (e.g., `'fa'` for FontAwesome).
`liveSearch`	boolean	`false`	When `true`, adds a search box to the top of the dropdown.
`liveSearchNormalize`	boolean	`false`	Enables accent-insensitive searching.
`liveSearchPlaceholder`	string	`null`	Sets the placeholder text for the search input.
`liveSearchStyle`	string \| function	`'contains'`	Search style. `'contains'` matches anywhere; `'startsWith'` matches from the beginning. A custom function can also be provided.
`maxOptions`	integer \| false	`false`	Limits the number of selections in a multi-select. Can also be a `data-` attribute on an `<optgroup>`.
`maxOptionsText`	string \| array \| function	`function`	The text displayed when the selection limit is reached.
`mobile`	boolean	`false`	When `true`, enables the device's native menu for select elements.
`multipleSeparator`	string	`', '`	The character that separates selected options in the button text.
`noneSelectedText`	string	`'Nothing selected'`	The text displayed when no options are selected.
`noneResultsText`	string	`'No results matched {0}'`	The text displayed when a search returns no results.
`selectAllText`	string	`'Select All'`	The text for the Select All button.
`selectedTextFormat`	string	`'values'`	Specifies how the selection is displayed: `'values'`, `'static'`, `'count'`, or `'count > x'`.
`selectOnTab`	boolean	`false`	When `true`, the Tab key will select the currently highlighted option.
`showContent`	boolean	`true`	When `true`, displays custom HTML from `data-content` in the button.
`showIcon`	boolean	`true`	When `true`, displays icons from `data-icon` in the button.
`showSubtext`	boolean	`false`	When `true`, displays subtext from `data-subtext` in the button.
`showTick`	boolean	`false`	Shows a checkmark on the selected option in a standard (non-multiple) select.
`size`	`'auto'` \| integer \| false	`'auto'`	Sets the maximum number of items to display in the menu.
`style`	string \| null	`'btn-light'` (BS4/5), `'btn-default'` (BS3)	Adds classes to the button's style.
`styleBase`	string \| null	`'btn'`	The base class applied to the button.
`tickIcon`	string	`'glyphicon-ok'`	The class for the checkmark icon.
`title`	string \| null	`null`	The default placeholder title for the select.
`virtualScroll`	boolean \| integer	`600`	Enables virtual scrolling for performance with large lists. Set to an integer to apply only if items exceed that number.
`width`	`'auto'` \| `'fit'` \| css-width \| false	`false`	Sets the width of the selectpicker.
`windowPadding`	integer \| array	`0`	Adds padding around the window to prevent the menu from covering fixed elements. Can be an integer or an array `[top, right, bottom, left]`.
`sanitize`	boolean	`true`	Enables or disables sanitization of `data-content`.
`whiteList`	object	Default value	An object of allowed HTML tags and attributes for the sanitizer.
`sanitizeFn`	null \| function	`null`	A custom function to use for sanitization.

Events

Bootstrap-select triggers several events you can hook into.

Event Type	Description
`show.bs.select`	Fires immediately when the `show` method is called.
`shown.bs.select`	Fired when the dropdown is visible to the user.
`hide.bs.select`	Fires immediately when the `hide` method is called.
`hidden.bs.select`	Fired when the dropdown has finished being hidden.
`loaded.bs.select`	Fires after the select has been initialized.
`rendered.bs.select`	Fires after the `render` method has been called.
`refreshed.bs.select`	Fires after the `refresh` method has been called.
`changed.bs.select`	Fires after the select's value has been changed. Passes `event`, `clickedIndex`, `isSelected`, and `previousValue`.

Example

$('#mySelect').on('changed.bs.select', function (e, clickedIndex, isSelected, previousValue) {
  // do something...
});