Skip to content

Re-add support for title and data-width #11

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
MikeAlhayek merged 1 commit into from
Jun 15, 2026
Merged

Re-add support for title and data-width #11

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,11 @@
# v1.1.2 (CrestApps fork)

### Fixes

- Restored support for legacy `title="..."` placeholder text on single selects.
- Restored support for `data-width="fit"` and `width: 'fit'` so compact picker layouts continue to work.
- Documented the native `*.bs.select` events, including `maxReached`, `maxReachedGrp`, and `fetched`, and clarified the `event.detail` payloads.

# v1.1.0 (CrestApps fork)

### Highlights
Expand Down
21 changes: 18 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,11 +74,11 @@ jsDelivr. Prefer pinning an explicit package version in production:
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.8/dist/js/bootstrap.bundle.min.js"></script>

<!-- @crestapps/bootstrap-select from jsDelivr -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@crestapps/bootstrap-select@1.1.1/dist/css/bootstrap-select.min.css">
<script src="https://cdn.jsdelivr.net/npm/@crestapps/bootstrap-select@1.1.1/dist/js/bootstrap-select.min.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@crestapps/bootstrap-select@1.1.2/dist/css/bootstrap-select.min.css">
<script src="https://cdn.jsdelivr.net/npm/@crestapps/bootstrap-select@1.1.2/dist/js/bootstrap-select.min.js"></script>
```

You can replace `@1.1.1` with the version you want to consume. During
You can replace `@1.1.2` with the version you want to consume. During
development, `@latest` also works, but a fixed version is safer for production
deployments.

Expand All @@ -104,6 +104,16 @@ automatically initialized once the DOM is ready — no JavaScript required.
</select>
```

Existing bootstrap-select markup that uses `title="..."` placeholders or
`data-width="fit"` is also supported:

```html
<select class="selectpicker" title="Content Type" data-width="fit">
<option>Article</option>
<option>Blog Post</option>
</select>
```

### Via JavaScript

Initialize an instance with the `Selectpicker` class. You can pass an element or
Expand Down Expand Up @@ -157,6 +167,11 @@ select.addEventListener('changed.bs.select', function (e) {
console.log('value changed', e.detail);
});

select.addEventListener('show.bs.select', function (e) {
// e.detail.bsEvent is the original Bootstrap dropdown event
console.log('opening from', e.detail.bsEvent.relatedTarget);
});

select.addEventListener('loaded.bs.select', function () { /* ... */ });
```

Expand Down
92 changes: 92 additions & 0 deletions docs/content/examples.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -412,6 +412,24 @@ Use the `placeholder` attribute to set the default placeholder text when nothing
</select>
```

Legacy bootstrap-select markup that uses the select element's `title` attribute for placeholder text is also supported on single selects:

<LiveExample
html={String.raw` <select class="selectpicker" title="Choose a content type">
<option>Article</option>
<option>Blog Post</option>
<option>Landing Page</option>
</select>`}
/>

```html
<select class="selectpicker" title="Choose a content type">
<option>Article</option>
<option>Blog Post</option>
<option>Landing Page</option>
</select>
```

## Selected text

<p id="title"></p>
Expand Down Expand Up @@ -710,6 +728,80 @@ Wrap selects in grid columns, or any custom parent element, to easily enforce de
</div>
```

<div id="data-width"></div>

Alternatively, use the `data-width` attribute to set the width of the select. Set `data-width` to `'auto'` to automatically adjust the width of the select to its widest option. `'fit'` automatically adjusts the width of the select to the width of its currently selected option. An exact value can also be specified, e.g., `300px` or `50%`.

<LiveExample
html={String.raw` <div class="row">
<div class="col-sm-12">
<div class="form-group">
<label><code>width: 'auto'</code></label>
<select class="selectpicker form-control" data-width="auto">
<option>Mustard</option>
<option>Ketchup</option>
<option>Relish</option>
<option>All of the above (and much, much more!)</option>
</select>
</div>
</div>
</div>
<div class="row">
<div class="col-sm-12">
<div class="form-group">
<label><code>width: 'fit'</code></label>
<select class="selectpicker form-control" data-width="fit">
<option>Mustard</option>
<option>Ketchup</option>
<option>Relish</option>
<option>All of the above (and much, much more!)</option>
</select>
</div>
</div>
</div>
<div class="row">
<div class="col-sm-12">
<div class="form-group">
<label><code>width: '150px'</code></label>
<select class="selectpicker form-control" data-width="150px">
<option>Mustard</option>
<option>Ketchup</option>
<option>Relish</option>
<option>All of the above (and much, much more!)</option>
</select>
</div>
</div>
</div>
<div class="row">
<div class="col-sm-12">
<div class="form-group">
<label><code>width: '75%'</code></label>
<select class="selectpicker form-control" data-width="75%">
<option>Mustard</option>
<option>Ketchup</option>
<option>Relish</option>
<option>All of the above (and much, much more!)</option>
</select>
</div>
</div>
</div>`}
/>

```html
<select class="selectpicker" data-width="auto">
...
</select>
<select class="selectpicker" data-width="fit">
...
</select>
<select class="selectpicker" data-width="100px">
...
</select>
<select class="selectpicker" data-width="75%">
...
</select>
```

# Customize options

---
Expand Down
16 changes: 13 additions & 3 deletions docs/content/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,11 +47,11 @@ Prefer pinning an explicit package version in production:
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.8/dist/js/bootstrap.bundle.min.js"></script>

<!-- @crestapps/bootstrap-select from jsDelivr -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@crestapps/bootstrap-select@1.1.1/dist/css/bootstrap-select.min.css">
<script src="https://cdn.jsdelivr.net/npm/@crestapps/bootstrap-select@1.1.1/dist/js/bootstrap-select.min.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@crestapps/bootstrap-select@1.1.2/dist/css/bootstrap-select.min.css">
<script src="https://cdn.jsdelivr.net/npm/@crestapps/bootstrap-select@1.1.2/dist/js/bootstrap-select.min.js"></script>
```

You can replace `@1.1.1` with the version you want to consume. During development,
You can replace `@1.1.2` with the version you want to consume. During development,
`@latest` also works, but a fixed version is safer for production deployments.

When loaded via a `<script>` tag, the plugin exposes a global `Selectpicker` class.
Expand All @@ -76,6 +76,16 @@ once the DOM is ready.
</select>
```

Existing bootstrap-select markup that uses `title="..."` placeholders or
`data-width="fit"` is also supported:

```html
<select class="selectpicker" title="Content Type" data-width="fit">
<option>Article</option>
<option>Blog Post</option>
</select>
```

### Via JavaScript
```js
// Initialize one select (accepts an element or a selector string)
Expand Down
50 changes: 43 additions & 7 deletions docs/content/options.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -191,6 +191,15 @@ For security reasons, the `sanitize`, `sanitizeFn`, and `whiteList` options cann
<p>The text displayed when a search doesn't return any results.</p>
</td>
</tr>
<tr>
<td>placeholder</td>
<td>string | null</td>
<td><code>null</code></td>
<td>
<p>Sets the placeholder text shown in the button when nothing is selected.</p>
<p>For backward compatibility, a single select's <code>title</code> attribute is also used when <code>placeholder</code> is not set.</p>
</td>
</tr>
<tr>
<td>selectAllText</td>
<td>string</td>
Expand Down Expand Up @@ -325,6 +334,16 @@ For security reasons, the `sanitize`, `sanitizeFn`, and `whiteList` options cann
<p>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.</p>
</td>
</tr>
<tr>
<td>width</td>
<td><code>'auto'</code> | <code>'fit'</code> | css-width | false</td>
<td><code>false</code></td>
<td>
<p>Controls the rendered width of the picker. Use the <code>data-width</code> attribute in markup or pass <code>width</code> in JavaScript.</p>
<p><code>'auto'</code> expands to the widest option, <code>'fit'</code> keeps the control compact to the selected option, and a CSS width such as <code>300px</code> or <code>75%</code> is applied inline.</p>
<p>When set to <code>false</code>, the picker follows the width of its container.</p>
</td>
</tr>
<tr>
<td>sanitize</td>
<td>boolean</td>
Expand Down Expand Up @@ -354,7 +373,7 @@ For security reasons, the `sanitize`, `sanitizeFn`, and `whiteList` options cann
/>

:::info Bootstrap 5 runtime defaults
This Bootstrap 5 build no longer supports the legacy `container`, `mobile`, `styleBase`, `width`, or `windowPadding` options. Layout should follow normal Bootstrap sizing and grid utilities, and the picker now fills its container by default.
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
Expand Down Expand Up @@ -428,9 +447,9 @@ Selectpicker.DEFAULTS.multipleSeparator = ' | ';

---

Bootstrap-select exposes a few events for hooking into select functionality.
bootstrap-select emits native `CustomEvent`s on the original `<select>` element.

hide.bs.select, hidden.bs.select, show.bs.select, and shown.bs.select all have a `relatedTarget` property, whose value is the toggling anchor element.
For `show.bs.select`, `shown.bs.select`, `hide.bs.select`, and `hidden.bs.select`, the original Bootstrap dropdown event is exposed as `event.detail.bsEvent`. Its `relatedTarget` property is the toggling button element.

<RawHtml
html={String.raw`<table class="table table-bordered table-striped">
Expand All @@ -443,19 +462,19 @@ hide.bs.select, hidden.bs.select, show.bs.select, and shown.bs.select all have a
<tbody>
<tr>
<td>show.bs.select</td>
<td>This event fires immediately when the show instance method is called.</td>
<td>This event fires immediately when the menu starts opening.</td>
</tr>
<tr>
<td>shown.bs.select</td>
<td>This event is fired when the dropdown has been made visible to the user (will wait for CSS transitions, to complete).</td>
<td>This event is fired when the menu has been made visible to the user (after CSS transitions complete).</td>
</tr>
<tr>
<td>hide.bs.select</td>
<td>This event is fired immediately when the hide instance method has been called.</td>
<td>This event is fired immediately when the menu starts closing.</td>
</tr>
<tr>
<td>hidden.bs.select</td>
<td>This event is fired when the dropdown has finished being hidden from the user (will wait for CSS transitions, to complete).</td>
<td>This event is fired when the menu has finished being hidden from the user (after CSS transitions complete).</td>
</tr>
<tr>
<td>loaded.bs.select</td>
Expand All @@ -476,6 +495,18 @@ hide.bs.select, hidden.bs.select, show.bs.select, and shown.bs.select all have a
<p><code>previousValue</code> is the value of the select prior to being changed. If the select's value has been changed either via the <code>val()</code>, <code>selectAll()</code>, or <code>deselectAll()</code> methods, clickedIndex and isSelected will be <code>null</code>.</p>
</td>
</tr>
<tr>
<td>maxReached.bs.select</td>
<td>This event fires when a multi-select tries to exceed the configured <code>maxOptions</code> limit on the select.</td>
</tr>
<tr>
<td>maxReachedGrp.bs.select</td>
<td>This event fires when a multi-select tries to exceed the configured <code>data-max-options</code> limit on an <code>&lt;optgroup&gt;</code>.</td>
</tr>
<tr>
<td>fetched.bs.select</td>
<td>This event fires after async or callback-backed source data has been fetched and applied to the picker.</td>
</tr>
</tbody>
</table>`}
/>
Expand All @@ -485,6 +516,11 @@ document.querySelector('#mySelect').addEventListener('changed.bs.select', functi
const { clickedIndex, isSelected, previousValue } = e.detail;
// do something...
});

document.querySelector('#mySelect').addEventListener('show.bs.select', function (e) {
const bootstrapEvent = e.detail.bsEvent;
const button = bootstrapEvent.relatedTarget;
});
```

## Sanitizer
Expand Down
Loading