{"id":14972534,"url":"https://github.com/thomasdev-de/bs-select","last_synced_at":"2026-05-05T09:02:22.329Z","repository":{"id":173608924,"uuid":"650563252","full_name":"ThomasDev-de/bs-select","owner":"ThomasDev-de","description":"This jQuery plugin converts a simple select element into a bootstrap dropdown element. It offers numerous options, methods and events for further processing. It was developed on the basis of jQuery 3.6, Bootstrap 5.3 and Bootstrap icons.","archived":false,"fork":false,"pushed_at":"2024-10-24T10:13:44.000Z","size":792,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-10-24T21:30:18.614Z","etag":null,"topics":["bootstrap","bootstrap5","dropdown","jquery","plugin","select"],"latest_commit_sha":null,"homepage":"https://github.webcito.de/#bs-select","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ThomasDev-de.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-06-07T10:33:44.000Z","updated_at":"2024-10-24T10:13:17.000Z","dependencies_parsed_at":"2024-02-25T21:30:36.779Z","dependency_job_id":"95bdd013-96c2-479a-bf46-7bc55c01c02a","html_url":"https://github.com/ThomasDev-de/bs-select","commit_stats":{"total_commits":59,"total_committers":2,"mean_commits":29.5,"dds":0.2542372881355932,"last_synced_commit":"2f7f1c210ef4dfe386137091d5847b872a5b2428"},"previous_names":["thomasdev-de/bs-select"],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThomasDev-de%2Fbs-select","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThomasDev-de%2Fbs-select/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThomasDev-de%2Fbs-select/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThomasDev-de%2Fbs-select/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ThomasDev-de","download_url":"https://codeload.github.com/ThomasDev-de/bs-select/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238394323,"owners_count":19464583,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bootstrap","bootstrap5","dropdown","jquery","plugin","select"],"created_at":"2024-09-24T13:47:05.157Z","updated_at":"2026-05-05T09:02:22.291Z","avatar_url":"https://github.com/ThomasDev-de.png","language":null,"funding_links":["https://paypal.me/thomaskirsch1529"],"categories":[],"sub_categories":[],"readme":"`$.fn.bsSelect`\n\nThis jQuery plugin enhances standard `\u003cselect\u003e` elements by converting them into fully-featured Bootstrap dropdown\ncomponents. It provides a wide range of customization options, methods, and event hooks for seamless integration and\nextended functionality. The plugin is built using **jQuery 3.6**, **Bootstrap 5.3**, and **Bootstrap Icons**, ensuring\ncompatibility and modern design standards.\n\n## table of contents\n\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Options](#options)\n- [Methods](#methods)\n- [Events](#events)\n\n## Requirements\n\n- bootstrap 4 or 5\n- jQuery\n\n## Installation\n\nDownload and include the script at the end of the body tag.\n\n```html\n\n\u003c!--suppress ALL --\u003e\n\u003cscript src=\"dist/locale/de-DE.min.js\" type=\"text/javascript\"\u003e\u003c!-- optional --\u003e\n\u003cscript src=\"dist/jquery.bs-select.js\" type=\"text/javascript\"\u003e\n```\n\nor install with **composer** and include the script at the end of the body tag.\n\n```shell\ncomposer require webcito/bs-select\n```\n\n```html\n\n\u003c!--suppress ALL --\u003e\n\u003cscript src=\"/vendor/webcito/bs-select/dist/locale/de-DE.min.js\" type=\"text/javascript\"\u003e \u003c!-- optional --\u003e\n\u003cscript src=\"/vendor/webcito/bs-select/dist/jquery.bs-select.min.js\" type=\"text/javascript\"\u003e\n```\n\nor use the GitHub CDN (jsDelivr):\n\n```html\n\u003cscript src=\"https://cdn.jsdelivr.net/gh/ThomasDev-de/bs-select@2.1.35/dist/locale/de-DE.min.js\" type=\"text/javascript\"\u003e\u003c/script\u003e \u003c!-- optional --\u003e\n\u003cscript src=\"https://cdn.jsdelivr.net/gh/ThomasDev-de/bs-select@2.1.35/dist/jquery.bs-select.min.js\" type=\"text/javascript\"\u003e\u003c/script\u003e\n```\n\n## Set global defaults\n\n```js\n// multiple options\n$.bsSelect.setDefaults(options);\n// get default options\n$.bsSelect.getDefaults();\n```\n\n## Usage\n\nAll selects with the attribute `[data-bs-toggle=\"select\"]` or `[data-toggle=\"select\"]` are initialized automatically.\n\n```html\n\u003c!-- Simple selection --\u003e\n\u003c!--suppress ALL --\u003e\n\u003cselect name=\"countries\"\u003e\n    \u003coption value=\"Germany\"\u003eDeutschland\u003c/option\u003e\n    \u003coption value=\"Poland\"\u003ePolen\u003c/option\u003e\n    ...\n\u003c/select\u003e\n\n\u003c!-- Or multiSelection --\u003e\n\u003cselect name=\"cities\" multiple\u003e\n    \u003coption value=\"1\"\u003eBerlin rocks\u003c/option\u003e\n    \u003coption value=\"2\"\u003eNew York\u003c/option\u003e\n    ...\n\u003c/select\u003e\n\n\u003c!-- Or with option groups --\u003e\n\u003cselect name=\"cities2\" multiple\u003e\n    \u003coptgroup label=\"Germany\"\u003e\n        \u003coption value=\"1\"\u003eBerlin\u003c/option\u003e\n        \u003coption value=\"2\"\u003eMunich\u003c/option\u003e\n    \u003c/optgroup\u003e\n    \u003coptgroup label=\"USA\"\u003e\n        \u003coption value=\"3\"\u003eNew York\u003c/option\u003e\n        \u003coption value=\"4\"\u003eSan Francisco\u003c/option\u003e\n    \u003c/optgroup\u003e\n    \u003coptgroup label=\"Spain\"\u003e\n        \u003coption value=\"5\"\u003eBarcelona\u003c/option\u003e\n        \u003coption value=\"6\"\u003eMadrid\u003c/option\u003e\n    \u003c/optgroup\u003e\n    ...\n\u003c/select\u003e\n\u003c!-- load jQuery and Bootstrap before --\u003e\n\u003cscript src=\"dist/jquery.bs-select.js\" type=\"text/javascript\"\u003e\n    \u003cscript\u003e\n        $('select').bsSelect();\n\u003c/script\u003e\n```\n\n## option[data-attributes]\n\n| data-attribute | example                                                          | description                                                              |\n|----------------|------------------------------------------------------------------|--------------------------------------------------------------------------|\n| data-subtext   | `\u003coption data-subtext=\"Germany\" value=\"1\"\u003eBerlin\u003c/option\u003e`       | Adds a small additional text section                                     |\n| data-icon      | `\u003coption data-icon=\"fa-solid fa-city\" value=\"1\"\u003eBerlin\u003c/option\u003e` | Adds an icon in front of the option. (e.g. a class from Bootstrap Icons) |\n\n## Options\n\n| property               | data-attribute                | type             | default                             | desc                                                                                                                                                                                                                                                    |\n|------------------------|-------------------------------|------------------|-------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| 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').* |\n| 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.* |\n| search                 | [data-search]                 | `bool`           | `true`                              | *adds a search function to the menu*                                                                                                                                                                                                                    |\n| searchText             | [data-search-text]            | `string`         | `Search..`                          | \"Placeholder for search input box*                                                                                                                                                                                                                      |\n| 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`.*                                                                                                                              |\n| btnWidth               | [data-btn-width]              | `string`         | `fit-content`                       | *the css width of the dropdown button*                                                                                                                                                                                                                  |\n| btnEmptyText           | [data-btn-empty-text]         | `string`         | `Please select..`                   | *The text at no selection*                                                                                                                                                                                                                              |\n| btnSplit               | [data-btn-split]              | `string`         | `false`                             | *create a split button dropdown* [bootstrap Split button](https://getbootstrap.com/docs/5.3/components/dropdowns/#split-button)                                                                                                                         |\n| btnClass               | [data-btn-class]              | `string`         | `btn-outline-secondary`             | *The classes assigned to the dropdown button*                                                                                                                                                                                                           |\n| dropDirection          | [data-drop-direction]         | `null\\|string`   | `null`                              | *opens the DropDown in a desired direction. Possible directions are:* `dropup\\|dropend\\|dropstart\\|dropdown-center\\|dropup-center` see [bootstrap directions](https://getbootstrap.com/docs/5.3/components/dropdowns/#directions)                       |\n| dropIconClass          | [data-drop-icon-class]        | `null\\|string`   | `bi bi-chevron-down`                | *If an icon is set here, the dropdown toggle icon is replaced with it. This only works if btnSplit is false.*                                                                                                                                           |\n| menuHeaderClass        | [data-menu-header-class]      | `string`         | `text-bg-secondary text-uppercase`  | *If option groups are present, the background class of the heading is set here.*                                                                                                                                                                        |\n| menuInnerClass         | [data-menu-inner-class]       | `null\\|string`   | `null`                              | *Set classes for the content of the dropdown menu.*                                                                                                                                                                                                     |\n| menuItemClass          | [data-menu-item-class]        | `string`         | `null`                              | *The classes are added to the element `.dropdown-item`.*                                                                                                                                                                                                |\n| menuMaxHeight          | [data-menu-max-height]        | `number`         | `300`                               | *maximum Height of the dropdown list before it starts scrolling.*                                                                                                                                                                                       |\n| animatedMenu           | [data-animated-menu]          | `bool`           | `true`                              | *If true, the plugin dropdown menu opens with a small top-to-bottom animation. This uses JavaScript only and does not require additional CSS.*                                                                                                           |\n| menuPreHtml            | [data-menu-pre-html]          | `null\\|string`   | `null`                              | *shows a text in the menu before the selection*                                                                                                                                                                                                         |\n| menuAppendHtml         | [data-menu-append-html]       | `null\\|string`   | `null`                              | *shows the text in the menu after the selection*                                                                                                                                                                                                        |\n| showSubtext            | [data-show-subtext]           | `bool`           | `true`                              | *If this option is true, options have the data attribute data-subtext, the subtext will be displayed in the dropdown.*                                                                                                                                  |\n| showActionMenu         | [data-show-action-menu]       | `bool`           | `true`                              | *If it is a multiple selection and this option is true, two buttons are displayed above the selection for faster selection.*                                                                                                                            |\n| showMultipleCheckboxes | [data-show-action-menu]       | `bool`           | `false`                             | *If this option is true, a checkbox is displayed in front of each option instead of the check icon.*                                                                                                                                                    |\n| actionMenuBtnClass     | [data-action-menu-btn-class]  | `string`         | `btn-light`                         | *The classnames for the buttons in the action menu.*                                                                                                                                                                                                    |\n| showSelectionAsList    | [data-show-selection-as-list] | `bool`           | `true`                              | *If it is a multiple selection, all selections should be listed below each other. If the value is false, it will show how much was selected.*                                                                                                           |\n| showSelectedText       |                               | `function`       | `(selectedItems, totalItems) =\u003e {}` | *If it is a multiple selection and the selected elements are greater than 1, this function is called. This function is ignored if the showSelectionAsList option is true.*                                                                              |\n| formatSelectedText     |                               | `function`       | `(title, subtext) =\u003e {}`            | *If it is a multiple selection and the selected elements are greater than 1, this function is called. This function is ignored if the showSelectionAsList option is true.*                                                                              |\n| formatItem             |                               | `function`       | `($option, title, subtext) =\u003e {}`   | *With this function, all dropdown item can be formated.*                                                                                                                                                                                                |\n| deselectAllText        | [data-deselect-all-text]      | `string`         | `Deselect All`                      | *If showActionMenu is true, the language of the two buttons can be set here.*                                                                                                                                                                           |\n| selectAllText          | [data-select-all-text]        | `string`         | `Select All`                        | *If showActionMenu is true, the language of the two buttons can be set here.*                                                                                                                                                                           |\n| checkedIcon            | [data-checked-icon]           | `string`         | `bi bi-check-lg`                    | *Class used to style the select icon.*                                                                                                                                                                                                                  |\n| onBeforeChange         |                               | `null\\|function` | `($select) =\u003e { return true; }`     | *This function is called before the values are changed. If the function returns true, the change is made, otherwise nothing is changed.*                                                                                                                |\n| onKeyDown              |                               | `null\\|function` | `($select, keyEvent) =\u003e { // }`     | *Called when the pressed key is not a dropdown command (arrowUp,arrowDown,ESCAPE)*                                                                                                                                                                      |\n\n## Methods\n\nMethods are called as follows\n\n```js\n$('select').bsSelect('method', param);\n```\n\n| method               | example                                                                       | description                                                                                                               |\n|----------------------|-------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|\n| `'show'`             | `$('select').bsSelect('show');`                                               | Opens the dropdown                                                                                                        |\n| `'hide'`             | `$('select').bsSelect('hide');`                                               | Closes the dropdown                                                                                                       | \n| `'val'`              | `$('select').bsSelect('val', 1);`                                             | Changes the value of the select                                                                                           | \n| `'search'`          | `$('select').bsSelect('search', 'query');`                                    | Programmatically filters the dropdown list. If a `searchQuery` prefix is set, it will be prepended to the query.          |\n| `'selectAll'`        | `$('select').bsSelect('selectAll');`                                          | Selects all values                                                                                                        | \n| `'selectFirst'`      | `$('select').bsSelect('selectFirst');`                                        | Selects the first option element                                                                                          | \n| `'selectLast'`       | `$('select').bsSelect('selectLast');`                                         | Selects the last option element                                                                                           | \n| `'selectNone'`       | `$('select').bsSelect('selectNone');`                                         | deselects all values                                                                                                      | \n| `'clear'`            | `$('select').bsSelect('clear');`                                              | Empties the Select                                                                                                        | \n| `'updateOptions'`    | `$('select').bsSelect('updateOptions', {buttonClass: 'btn btn-danger',...});` | Changes the settings of the dropdown.                                                                                     |\n| `'setBtnClass'`      | `$('select').bsSelect('setBtnClass', 'btn btn-danger');`                      | Behaves like `updateOptions`. The btnClass option is overwritten.                                                         |\n| `'refresh'`          | `$('select').bsSelect('refresh');`                                            | Rebuild the dropdown. This is useful if the options are changed via Javascript.                                           |\n| `'getSelectedText'`  | `$('select').bsSelect('getSelectedText', (text, value) =\u003e {});`               | Retrieves the text based on the selections of the select                                                                  |\n| `'destroy'`          | `$('select').bsSelect('destroy'[, true]);`                                    | Deletes the dropdown and restores the original select. If parameter is passed true, all data is removed from the element. |\n| `'toggleDisabled'`   | `$('select').bsSelect('toggleDisabled');`                                     | Toggles the status of the dropdown button                                                                                 |\n| `'setDisabled'`      | `$('select').bsSelect('setDisabled', true);`                                  | Set the dropdown disabled (true) otherwise enabled (false)                                                                |\n| `'toggleVisibility'` | `$('select').bsSelect('toggleVisibility');`                                   | Toggles the visibility of the dropdown                                                                                    |\n| `'setVisible'`       | `$('select').bsSelect('setVisible', true);`                                   | Set the visibility of the dropdown (show: true, hide: false)                                                              |\n\n## Events\n\n| event type               | Description                                                                                                                      |\n|--------------------------|----------------------------------------------------------------------------------------------------------------------------------|\n| init.bs.select           | Fires when the plugin has been initialised.                                                                                      |\n| hide.bs.select           | Fires immediately when the hide instance method has been called. Returns whether value was changed as parameter 1 of the status. |\n| hidden.bs.select         | Fired when the dropdown has finished being hidden from the user and CSS transitions have completed.                              |\n| show.bs.select           | Fires immediately when the show instance method is called.                                                                       |\n| shown.bs.select          | Fired when the dropdown has been made visible to the user and CSS transitions have completed.                                    |\n| refresh.bs.select        | Fires when the `refresh` method has been invoked.                                                                                |\n| change.bs.select         | Fires when the values in the select have changed. Additional parameters are [valueBefore, valueAfter]                            |\n| userChange.bs.select     | Fires if the user has changed the value manually                                                                                 |\n| clear.bs.select          | Fires when the `clear` method has been called.                                                                                   |\n| acceptChange.bs.select   | If the function onBeforeChange returns true, this event is fired.                                                                |\n| cancelChange.bs.select   | If the function onBeforeChange returns false, this event is fired.                                                               |\n| update.bs.select         | Fires when the method `updateOptions` or `setBtnClass` was called.                                                               |\n| destroy.bs.select        | Fires when the `destroy` method has been activated.                                                                              |\n| selectAll.bs.select      | Fires when the select all option has been pressed.                                                                               |\n| selectNone.bs.select     | Fires when the select none option has been pressed.                                                                              |\n| selectFirst.bs.select    | Fires when the `selectFirst` method has been called. The value of the first element is passed as a parameter.                    |\n| selectLast.bs.select     | Fires when the `selectLast` method has been called. The value of the last element is passed as a parameter.                      |\n| any.bs.select            | Fires at every event.                                                                                                            |\n| keydown.bs.select        | Fires when the pressed key is not a dropdown command (arrowUp,arrowDown,ESCAPE)                                                  |\n| toggleDisabled.bs.select | Fires when the disable status changes. Returns the new status as a parameter. fn(e, (boolean)status){}                           |\n\n## Conclusion\n\nThe **bs-select** plugin is a feature-rich solution for enhancing `\u003cselect\u003e` elements to work with Bootstrap styling and\ninteractivity.\n\nFor further queries or issues, check:\n\n- [GitHub Documentation](https://github.com/ThomasDev-de/bs-select)\n- [Bootstrap Select Examples](https://getbootstrap.com/docs)\n\n## Support this project\n\nIf this project helps you, feel free to support its development:\n\n[☕ Buy me a coffee via PayPal](https://paypal.me/thomaskirsch1529)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthomasdev-de%2Fbs-select","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthomasdev-de%2Fbs-select","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthomasdev-de%2Fbs-select/lists"}