bs-select

$.fn.bsSelect

This jQuery plugin enhances standard <select> elements by converting them into fully-featured Bootstrap dropdown components. It provides a wide range of customization options, methods, and event hooks for seamless integration and extended functionality. The plugin is built using jQuery 3.6, Bootstrap 5.3, and Bootstrap Icons, ensuring compatibility and modern design standards.

table of contents

• Requirements
• Installation
• Usage
• Locales
• Options
• Methods
• Events

Requirements

• bootstrap 4 or 5
• jQuery

Installation

Download and include the script at the end of the body tag.

<!--suppress ALL -->
<script src="dist/locale/de-DE.min.js" type="text/javascript"><!-- optional -->
<script src="dist/jquery.bs-select.js" type="text/javascript">

or install with composer and include the script at the end of the body tag.

composer require webcito/bs-select

<!--suppress ALL -->
<script src="/vendor/webcito/bs-select/dist/locale/de-DE.min.js" type="text/javascript"> <!-- optional -->
<script src="/vendor/webcito/bs-select/dist/jquery.bs-select.min.js" type="text/javascript">

or use the GitHub CDN (jsDelivr):

<script src="https://cdn.jsdelivr.net/gh/ThomasDev-de/bs-select@2.1.38/dist/locale/de-DE.min.js" type="text/javascript"></script> <!-- optional -->
<script src="https://cdn.jsdelivr.net/gh/ThomasDev-de/bs-select@2.1.38/dist/jquery.bs-select.min.js" type="text/javascript"></script>

Set global defaults

// multiple options
$.bsSelect.setDefaults(options);
// get default options
$.bsSelect.getDefaults();

Usage

All selects with the attribute [data-bs-toggle="select"] or [data-toggle="select"] are initialized automatically.

<!-- Simple selection -->
<!--suppress ALL -->
<select name="countries">
    <option value="Germany">Deutschland</option>
    <option value="Poland">Polen</option>
    ...
</select>

<!-- Or multiSelection -->
<select name="cities" multiple>
    <option value="1">Berlin rocks</option>
    <option value="2">New York</option>
    ...
</select>

<!-- Or with option groups -->
<select name="cities2" multiple>
    <optgroup label="Germany">
        <option value="1">Berlin</option>
        <option value="2">Munich</option>
    </optgroup>
    <optgroup label="USA">
        <option value="3">New York</option>
        <option value="4">San Francisco</option>
    </optgroup>
    <optgroup label="Spain">
        <option value="5">Barcelona</option>
        <option value="6">Madrid</option>
    </optgroup>
    ...
</select>
<!-- load jQuery and Bootstrap before -->
<script src="dist/jquery.bs-select.js" type="text/javascript">
    <script>
        $('select').bsSelect();
</script>

Locales

Locale files are optional and set the global window.bsSelectTranslations object. Include one locale file before jquery.bs-select.js.

Available locale files:

cs-CZ, da-DK, de-DE, el-GR, en-GB, en-US, es-ES, fi-FI, fr-FR, hu-HU, it-IT, nb-NO, nl-NL, pl-PL, pt-PT, ro-RO, sk-SK, sv-SE.

option[data-attributes]

data-attribute	example	description
data-subtext	<option data-subtext="Germany" value="1">Berlin</option>	Adds a small additional text section
data-icon	<option data-icon="fa-solid fa-city" value="1">Berlin</option>	Adds an icon in front of the option. (e.g. a class from Bootstrap Icons)

Options

property	data-attribute	type	default	desc
value	[data-value]	mixed	undefined	If a value is passed here, this value (if available) will be preselected during initialization. Otherwise the value of the native select is adopted.The value is only taken into account during the initial initialization (not for 'updateOptions').
selectAllOnInit	[data-select-all-on-init]	bool	false	If true and the select is multiple, all options are selected during initialization. If value is also set, selectAllOnInit takes precedence.
nullable	[data-nullable]	bool	true	Only relevant for single selects. If false, the select always keeps a selected option and cannot be cleared to empty.
search	[data-search]	bool	true	adds a search function to the menu. Search matches option text, option data-subtext, and optgroup labels (group label match reveals all options in that group).
searchText	[data-search-text]	string	Search..	"Placeholder for search input box*
searchQuery	[data-search-query]	string	null	predefined search prefix fixed as input-group-text in the search field. The search query becomes prefix + user input.
btnWidth	[data-btn-width]	string	fit-content	the css width of the dropdown button
btnEmptyText	[data-btn-empty-text]	string	Please select..	Text shown when there is no selected value. For single-selects this only applies when nullable is true.
btnSplit	[data-btn-split]