https://github.com/crsten/choose-bumps
A dropdown so simple it will give you choose-bumps! Written in pure vanillajs
https://github.com/crsten/choose-bumps
Last synced: 12 months ago
JSON representation
A dropdown so simple it will give you choose-bumps! Written in pure vanillajs
- Host: GitHub
- URL: https://github.com/crsten/choose-bumps
- Owner: crsten
- License: mit
- Created: 2016-03-05T11:58:55.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2018-02-16T09:50:59.000Z (over 8 years ago)
- Last Synced: 2025-07-09T10:19:33.587Z (about 1 year ago)
- Language: JavaScript
- Homepage: http://crsten.github.io/choose-bumps/
- Size: 388 KB
- Stars: 8
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# choose-bumps
[](https://travis-ci.org/crsten/choose-bumps)
[](https://www.npmjs.com/package/choosebumps)
[]()
[](https://www.npmjs.com/package/choosebumps)
[]()
A dropdown so simple it will give you choose-bumps! Written in pure vanillajs
## Inspiration
Have you ever wanted a simple dropdown library that doesn't depend on bloated frameworks? Well i did! Have fun :)
## Demo
You can find a small [demo here](http://crsten.github.io/choose-bumps/).
## Installation
You can get it on npm.
```shell
npm install choosebumps --save
```
Or bower, too.
```shell
bower install choosebumps --save
```
If you're not using either package manager, you can use `choosebumps` by downloading the [files in the `dist` folder](dist).
#### Including the JavaScript
Place `choosebumps` in the end of ``.
#### Including the CSS
Place [`dist/choosebumps.css`](dist/choosebumps.css) or [`dist/choosebumps.min.css`](dist/choosebumps.min.css) in your document.
# Usage
Choosebumps provides the easiest possible API to make dropdowns breeze in your applications.
## `ChooseBumps(element,options?)`
`element` can either be a string (selector) or an `HTMLElement` (not a jQuery element)
You can provide `options` to customize `choosebumps`. Here's an **overview of the default values**.
```js
ChooseBumps(element,{
placeholder: 'Choose',
items: [],
minlength: 0,
search: false,
searchfields: '',
noresults: '',
multiple: false,
template: '{{data}}',
tagtemplate: null, //inherits from template if null
selectedtemplate: null, //inherits from template if null
onselect: null,
onremove: null,
onadd: null,
categorize: null
});
```
The following functions are supported on the returned instance
```js
cb.select(item);
cb.remove(item);
cb.reset();
```
The options/functions are detailed below. **All the options can be set at initialization or anytime later when you feel for it(even if `choosebumps` is open or whatever)**
#### `options.items`
By default `choosebumps` has no items. You can add items either by sending them in to the options at initialization:
```js
var cb = ChooseBumps('#cb',{
items: [1,2,3,4]
});
```
or anytime later by setting `items` for the returned `choosebumps` instance:
```js
var cb = ChooseBumps('#cb');
//Some lines later...
cb.items = [5,6,7];
```
You can also send in a string(URL) which will be fetched either dynamically when searching or when the property is being set.
If you want search dynamically with `choosebumps` replace the part that should be changed in the URL with `{{query}}`. It will then make a new call everytime the searchphrase changes.
```js
items = 'https://www.yourawsomepage.com/api/user?q={{query}}' //will fetch this url and replace {{query}} with the users input
```
It is also possible to send in a function which will be called dynamically. The function recieves 2 arguments: `function(query, callback)`. Simply call the callback function with your result when you are done.
```js
items = function(query, cb) {
//Do some fetching or whatever here...
//Query is the users input (if search = true else null)
cb(RESULTARRAY) //call the callback function with the result as parameter when you are done!
}
```
*`options.items` accepts an array, string(url) or function as input and ignores all other types.*
#### `options.processing`
If you need to preprocess the fetched data before passing it to `choosebumps` you can do it with the `options.processing` property. You can set it at initialization:
```js
var cb = ChooseBumps('#cb',{
processing: function(fetched_data) {
//Do some stuff with your data here and pass it on...
return fetched_data.map(function(enrty) {
return {
firstname: entry.firstname,
lastname: entry.lastname
};
});
}
});
```
or anytime later by setting `processing` for the returned `choosebumps` instance:
```js
var cb = ChooseBumps('#cb');
//Some lines later...
cb.processing = function Your_function(){};
```
*`options.processing` accepts a function as input and ignores all other types.*
#### `options.placeholder`
By default `choosebumps` has `"Choose"` as the placeholder text. You can change the placeholder text either by sending them in to the options at initialization:
```js
var cb = ChooseBumps('#cb',{
placeholder: 'Choose your force now!'
});
```
or anytime later by setting `placeholder` for the returned `choosebumps` instance:
```js
var cb = ChooseBumps('#cb');
//Some lines later...
cb.placeholder = 'Have you choosen already?';
```
*`options.placeholder` accepts a string as input and ignores all other types.*
#### `options.noresults`
If you are using the `options.search` property, you can show a "no results" text if the current query doesn't return any results.
By default `options.noresults` is not set. You can change the noresults text either by sending them in to the options at initialization:
```js
var cb = ChooseBumps('#cb',{
noresults: 'Did not find any results for {{query}}'
});
```
or anytime later by setting `noresults` for the returned `choosebumps` instance:
```js
var cb = ChooseBumps('#cb');
//Some lines later...
cb.noresults = 'Did not find any results for {{query}}';
```
*Hint* `{{query}}` gets replaced with the current search term.
*`options.noresults` accepts a string as input and ignores all other types.*
#### `options.search`
By default `choosebumps` has disabled `search`. You can activate it either by sending it to the options at initialization:
```js
var cb = ChooseBumps('#cb',{
search: true
});
```
or anytime later by setting `search` for the returned `choosebumps` instance:
```js
var cb = ChooseBumps('#cb');
//Some lines later...
cb.search = false;
```
When searching, `choosebumps` will look through each property of each item in `items`. (If item is an object)
If you want to define what `choosebumps` should look for remember to set `options.searchfields`.
*`options.search` accepts anything as input and checks the input for its thruthiness.*
#### `options.minlength`
By default `choosebumps` has minlength of 0 which means it will start searching if the length of the input is longer than 0. You can change it either by sending it to the options at initialization:
```js
var cb = ChooseBumps('#cb',{
minlength: 2
});
```
or anytime later by setting `minlength` for the returned `choosebumps` instance:
```js
var cb = ChooseBumps('#cb');
//Some lines later...
cb.minlength = 5;
```
*`options.minlength` accepts a number as input and sets the value to 0 for all other types.*
#### `options.searchfields` (only relevant if `items` are objects)
By default `choosebumps` searches through each property in all `items`. You can define wich fields should be searched by sending a string in to the options at initialization:
```js
var cb = ChooseBumps('#cb',{
searchfields: 'firstname lastname adress' //Space separated string
});
```
or anytime later by setting `searchfields` for the returned `choosebumps` instance:
```js
var cb = ChooseBumps('#cb');
//Some lines later...
cb.searchfields = 'firstname lastname' //Space separated string
```
*`options.searchfields` accepts a string as input and splits its content by space. All other types are ignored*
#### `options.multiple`
With `options.multiple` you can allow selection of multiple items.
By default `choosebumps` has disabled `multiple` selection. You can activate it either by sending it in to the options at initialization:
```js
var cb = ChooseBumps('#cb',{
multiple: true
});
```
or anytime later by setting `multiple` for the returned `choosebumps` instance:
```js
var cb = ChooseBumps('#cb');
//Some lines later...
cb.multiple = false;
```
*`options.multiple` accepts anything as input and checks the input for its thruthiness.*
#### `options.template`
The templating in `choosebumps` is inspired by the moustache library. All variables can be rendered into view by putting the key of the object between `{{` and `}}`. This does also work for nested object. **Be aware that all variables must be prefixed with `data.`**
```js
var obj = {
name: {
first: 'Boba',
last: 'Fett'
}
};
'{{data.name.first}} {{data.name.last}}' --- renders ---> 'Boba Fett'
```
By default `choosebumps` has `{{data}}` as the template (Works for array of string or numbers). You can change it either by sending it in to the options at initialization:
```js
var cb = ChooseBumps('#cb',{
template: '{{data.name}}'
});
```
or anytime later by setting `multiple` for the returned `choosebumps` instance:
```js
var cb = ChooseBumps('#cb');
//Some lines later...
cb.template = '{{data.name.last}}';
```
*`options.template` accepts a string as input and ignores all other values.*
#### `options.tagtemplate` (only if `options.multiple` is true)
`options.tagtemplate` can be used to set a custom template for the selected item rendering when multiple item selection is enabled.
It works the same way as `options.template` --> see documentation further up.
If `options.tagtemplate` is not set, it will inherit the template from `options.template`.
#### `options.selectedtemplate`
`options.selectedtemplate` can be used to set a custom template for the selected item rendering.
It works the same way as `options.template` --> see documentation further up.
If `options.selectedtemplate` is not set, it will inherit the template from `options.template`.
#### `options.categorize`
With `options.categorize` you can categorize the items by string.
If i want to categorize by lastname with the following `options.items` set.
```js
[
{
name: {
last: 'Doe',
first: 'John'
}
}
]
```
You would set `options.categorize` = `'name.last'`.
You can activate it either by sending it in to the options at initialization:
```js
var cb = ChooseBumps('#cb',{
categorize: 'name.last'
});
```
or anytime later by setting `categorize` for the returned `choosebumps` instance:
```js
var cb = ChooseBumps('#cb');
//Some lines later...
cb.categorize = null;
```
*`options.categorize` accepts a string or null as input and ignores all other types.*
#### `options.onselect` (Callback)
With `options.onselect` you can attach a callback to the select event.
The callback function will get 1 parameter with the selected item.
You can activate it either by sending it in to the options at initialization:
```js
var cb = ChooseBumps('#cb',{
onselect: function(item){
//Woho, item here...
}
});
```
or anytime later by setting `onselect` for the returned `choosebumps` instance:
```js
var cb = ChooseBumps('#cb');
//Some lines later...
cb.onselect = null;
```
*`options.onselect` accepts a function or null as input and ignores all other types.*
#### `options.onremove` (Callback)
With `options.onremove` you can attach a callback to the remove event.
The callback function will get 1 parameter with the selected item.
You can activate it either by sending it in to the options at initialization:
```js
var cb = ChooseBumps('#cb',{
onremove: function(item){
//Woho, item here...
}
});
```
or anytime later by setting `onremove` for the returned `choosebumps` instance:
```js
var cb = ChooseBumps('#cb');
//Some lines later...
cb.onremove = null;
```
*`options.onremove` accepts a function or null as input and ignores all other types.*
#### `options.onadd` (Callback)
With `options.onadd` you can attach a callback to the add event (works with search mode only).
Add gets triggered when pressing enter and no other item is selected.
The callback function will get 1 parameter with the typed text.
You can activate it either by sending it in to the options at initialization:
```js
var cb = ChooseBumps('#cb',{
onadd: function(value){
//Woho, value here...
}
});
```
or anytime later by setting `onadd` for the returned `choosebumps` instance:
```js
var cb = ChooseBumps('#cb');
//Some lines later...
cb.onadd = null;
```
*`options.onadd` accepts a function or null as input and ignores all other types.*
#### `choosebumps.select` (Function)
With `choosebumps.select` you can programmaticaly set the selected item.
The function will take the item to be selected as parameter. **Only items that are in `options.items` can be selected! (Unless items is an url which get items dynamically)**
**If the parameter is null, reset gets called!**
You can call it on the returned `choosebumps` instance:
```js
var cb = ChooseBumps('#cb',{
items: [1,2,3,4]
});
//Some lines later...
cb.select(4);
```
#### `choosebumps.remove` (Function)
With `choosebumps.remove` you can programmaticaly remove a selected item.
The function will take the item to be removed from selection as parameter. **Only items that are selected can be removed!**
**If the parameter is null, reset gets called!**
You can call it on the returned `choosebumps` instance:
```js
var cb = ChooseBumps('#cb',{
items: [1,2,3,4]
});
//Some lines later...
cb.remove(4);
```
#### `choosebumps.reset` (Function)
With `choosebumps.reset` you can programmaticaly remove all selected items.
You can call it on the returned `choosebumps` instance:
```js
var cb = ChooseBumps('#cb',{
items: [1,2,3,4]
});
//Some lines later...
cb.reset();
```
---
**Great shoutout to [Kent C. Dodds](https://github.com/kentcdodds) for providing great tutorials on [how to write an open source library](https://egghead.io/series/how-to-write-an-open-source-javascript-library)**