Pillbox.js is a UI container for your (optionally pill-styled) tag labels. The pillbox contains pills (tags), and each pill is aware of its state. Events are emitted whenever something interesting happens.
Pillbox.js is available as a CommonJS module. Soon, it will be available via npm, like so:
npm install --save pillbox
And you can require it in your project:
var Pillbox = ;
Pillbox variable above is a constructor that takes an object with the following properties:
container-- The parent DOM element that will contain each "pill"
pills-- An optional array containing the initial collection of pills
Pills are created with the following options:
key-- String, used to identify the pill, must be unique
value-- String that will be displayed on the rendered pill
remove-- Optional boolean, determines if pills should have close buttons when no template is present.
template-- An optional function, should return a string of HTML given an object parameter with a
states-- An optional array of strings to be used as initial states
var pb =container: documentpills: /* see pill options above */;
You don't have to add pills initially, though. You can easily add them after creating
You can also remove a pill if you know its
You can retrieve an instance of a pill if you know its key. This allows you to check or set a pill's state.
You can also request an array of all keys, which would allow you to iterate over each pill and remove it or modify its state:
var pillKeys = pb;_;
Each pill has an array of states. States translate to classes in the DOM, and they can be modified and queried with the following methods.
setState(state)-- Adds a new state based on the given string
removeState(state)-- Removes an existing state
falsedepending on the existence of a given state
cleanState()-- removes all states from the pill
draw(parent)-- Appends an element representing the pill into the given parent
erase()-- Removes the pill's element from the DOM
Pills emit several events:
"click"-- When a pill is clicked
"state:add"-- When a state is added to a pill
"state:remove"-- When a state is removed from a pill
"request:remove"-- When a pill requests to be removed (e.g. when the
However, getting pill instances is a hassle, so all pill events are also forwarded through Pillbox with a
"pill:" prefix. Instead of listening for
"request:remove" on each pill instance:
You can instead listen for the event on
pb directly, which is more concise:
In addition to forwarding Pill events, Pillbox emits two events of its own:
"pill:add"-- Emitted after a new pill is added. The pill object is passed to the callback.
"pill:remove"-- Emitted after a pill is removed. The pill's key is passed to the callback.
gulp installed globally, you can run a development build (which includes file watching) by running the following in the project directory: