blob-select
A dependency-free Javascript plugin for styling <select> elements with an emphasis on markup simplicity and performance., (*1)
Note: For projects built with the Vue.js framework, the vue-blob-select fork might be a better fit., (*2)
Table of Contents
- Features
- Requirements
-
Use
- Styling
- License
, (*3)
Features
blob-select has feature parity with the standard <select>, <option>, and <optgroup> attributes, including:, (*4)
<select multiple=multiple><select disabled=disabled><optgroup disabled=disabled><option disabled=disabled>
blob-select additionally provides support for:, (*5)
- Placeholders
- Searching
- Sorting
, (*6)
Requirements
blob-select is written in pure Javascript and does not depend on any third-party frameworks., (*7)
It is compatible with all major modern web browsers, and ~~the browser that just won't die~~ IE 11., (*8)
This plugin does make use of some ES6 markup like let and const. If your project needs to support old browsers, you will need to first transpile blobselect.min.js to ES5 with a tool like Babel, then serve that copy to visitors., (*9)
, (*10)
Use
Installation
Download dist/blobselect.min.js and add it to your project folder, and include it somewhere on the page., (*11)
<script src="/path/to/blobselect.min.js"></script>
Aside from the main script, you'll also need some CSS styles. You can either plug in the default stylesheet from dist/css/ or take a look at the source in src/scss/ to roll your own., (*12)
Configuration
blob-select includes a few choice functional enhancements to the standard select browser object, but does not attempt to introduce every feature ever dreamt of by (wo)man or beast. These settings can be defined for each element in either of three ways:, (*13)
<select data-blobselect='{"foo" : "bar", …}'></select>
<select data-blobselect-foo="bar"></select>
The following settings are available:, (*14)
| Type |
Key |
Default |
Description |
| string |
orderType |
"" |
How to compare option labels for sorting; either "string", "numeric", or empty to not sort. |
| string |
order |
"asc" |
Sort order (if orderType is specified); "asc" or "desc". |
| string |
placeholder |
"---" |
Selected text to display when a "placeholder" <option> is selected. Placeholderness is TRUE when an <option> has no label or has an attribute data-placeholder="1". |
| string |
placeholderOption |
"---" |
Same as above, except this text is used only for the dropdown listing. If omitted, the placeholder setting will supply both. |
| bool |
search |
FALSE |
Whether or not to display a simple search field in the dropdown. The search field itself is a contentEditable <div> so as not to screw up your real <form>. |
| int |
watch |
0 |
This forces blob-select to re-check for changes to its element every X milliseconds. This option is useful when other scripts might manipulate the element without firing a change event. Otherwise, leave this disabled to spare the unnecessary overhead. |
Initialization
blob-select will automatically initialize any <select> elements on DOMContentLoaded that contain a data-blobselect* attribute. Alternatively, you can manually initialize an element at any time as follows:, (*15)
// Regular ol' JS.
document.getElementById('my-select').blobSelect.init({…});
// jQuery example.
$('#my-select')[0].blobSelect.init({…});
Destruction
To restore your page to its natural state, simply run:, (*16)
document.getElementById('my-select').blobSelect.destroy();
Repaint
blob-select will automatically listen for change events, but some Javascript frameworks might write changes without firing an event. There are two workarounds for this:, (*17)
watch:, (*18)
Set the watch runtime property on the field. This will add a setInterval() trigger to the mix, rechecking the DOM every X millseconds for changes (and rebuilding as necessary)., (*19)
<!-- Will look for changes every half-second. -->
<select data-blobselect-watch="500">…</select>
element.blobSelect.buildData():, (*20)
Call the .buildData() method after such changes have landed., (*21)
// Place this after secret, non-event-firing changes have run.
document.getElementById('my-select').blobSelect.buildData();
, (*22)
Styling
blob-select aims to be as headache-free as possible. Its markup is minimal (see below) and it does not impose pesky inline styles, Javascript animations, or convoluted nested>nested>nested elements. Frontend developers are free to define everything through elegant CSS wizardry., (*23)
The HTML structure is as follows:, (*24)
The SCSS source folder includes example styles that should provide a starting point and/or inspiration. :), (*25)
, (*26)
License
Copyright © 2018 Blobfolio, LLC <hello@blobfolio.com>, (*27)
This work is free. You can redistribute it and/or modify it under the terms of the Do What The Fuck You Want To Public License, Version 2., (*28)
DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
Version 2, December 2004
Copyright (C) 2004 Sam Hocevar <sam@hocevar.net>
Everyone is permitted to copy and distribute verbatim or modified
copies of this license document, and changing it is allowed as long
as the name is changed.
DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
0. You just DO WHAT THE FUCK YOU WANT TO.
Donations
 |
If you have found this work useful and would like to contribute financially, Bitcoin tips are always welcome!
1Af56Nxauv8M1ChyQxtBe1yvdp2jtaB1GF
|
Wallogit.com
