❤
npm
Sign UpSign In

choosebumps

1.13.7 • Public • Published

choose-bumps

Build Status npm Bower npm npm

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.

Installation

You can get it on npm.

npm install choosebumps --save

Or bower, too.

bower install choosebumps --save

If you're not using either package manager, you can use choosebumps by downloading the files in the dist folder.

Including the JavaScript

Place choosebumps in the end of <body>.

Including the CSS

Place dist/choosebumps.css or 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.

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

 
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:

var cb = ChooseBumps('#cb',{
  items: [1,2,3,4]
});

or anytime later by setting items for the returned choosebumps instance:

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.

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.

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:

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:

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:

var cb = ChooseBumps('#cb',{
  placeholder: 'Choose your force now!'
});

or anytime later by setting placeholder for the returned choosebumps instance:

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:

var cb = ChooseBumps('#cb',{
  noresults: 'Did not find any results for {{query}}'
});

or anytime later by setting noresults for the returned choosebumps instance:

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:

var cb = ChooseBumps('#cb',{
  search: true
});

or anytime later by setting search for the returned choosebumps instance:

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:

var cb = ChooseBumps('#cb',{
  minlength: 2
});

or anytime later by setting minlength for the returned choosebumps instance:

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:

var cb = ChooseBumps('#cb',{
  searchfields: 'firstname lastname adress' //Space separated string
});

or anytime later by setting searchfields for the returned choosebumps instance:

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:

var cb = ChooseBumps('#cb',{
  multiple: true
});

or anytime later by setting multiple for the returned choosebumps instance:

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.

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:

var cb = ChooseBumps('#cb',{
  template: '{{data.name}}'
});

or anytime later by setting multiple for the returned choosebumps instance:

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.

  [
    {
      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:

var cb = ChooseBumps('#cb',{
  categorize: 'name.last'
});

or anytime later by setting categorize for the returned choosebumps instance:

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:

var cb = ChooseBumps('#cb',{
  onselect: function(item){
    //Woho, item here...
  }
});

or anytime later by setting onselect for the returned choosebumps instance:

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:

var cb = ChooseBumps('#cb',{
  onremove: function(item){
    //Woho, item here...
  }
});

or anytime later by setting onremove for the returned choosebumps instance:

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:

var cb = ChooseBumps('#cb',{
  onadd: function(value){
    //Woho, value here...
  }
});

or anytime later by setting onadd for the returned choosebumps instance:

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:

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:

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:

var cb = ChooseBumps('#cb',{
  items: [1,2,3,4]
});
//Some lines later...
cb.reset();

Great shoutout to Kent C. Dodds for providing great tutorials on how to write an open source library

Versions

Current Tags

  • Version
    Downloads (Last 7 Days)
    • Tag
  • 1.13.7
    35
    • latest

Version History

Package Sidebar

Install

npm i choosebumps

Repository

github.com/crsten/choose-bumps

Homepage

github.com/crsten/choose-bumps#readme

Weekly Downloads

35

Version

1.13.7

License

MIT

Unpacked Size

91.5 kB

Total Files

16

Last publish

Collaborators

  • crsten
Try on RunKit
Report malware