selecton

Selecton.js combines a search bar and a drop-down menu with nested child lists. It helps you to display hierarchical order within your drop-down menus. Selecton.js is completely object-based, meaning that all values are represented as objects. See example here.

Installing

If you use npm, npm install selecton. You can also download the latest release. Otherwise use unpkg to get the latest release. For example:

<script src="https://unpkg.com/selecton/build/selecton.js"></script>

For a specific version:

<script src="https://unpkg.com/selecton@version/build/selecton.js"></script>

For the minified version:

<script src="https://unpkg.com/selecton@version/build/selecton.min.js"></script>

For the css:

<link rel="stylesheet" type="text/css" href="https://unpkg.com/selecton@version/build/css/selecton-light.min.css">

<link rel="stylesheet" type="text/css" href="https://unpkg.com/selecton@version/build/css/selecton-dark.min.css">

Note: dark and light means on what background they appear better. If you want to change the styles, you should clone the repo and take a look at the sccs folder.

Import

import {default as Selecton} from 'selecton';

Build

Clone or download the repository. Run npm install to install all dependencies. To manipule the css and to make changes to the source code run npm run watch and gulp (in different tabs).

Quick-start

<!-- add css -->
<link rel="stylesheet" type="text/css" href="selecton.css" />

<!-- add container -->
<div id="selecton-container"></div>

<!-- add selecton.js -->
<script src="selecton.js"></script>

<script>
    // declare data
    var data = [{key:'A'}, {key:'B'}, {key:'C'}];

    // define order of items in the input field (optional)
    var data = ['B', 'A', 'C'];

    // create new selecton instance and pass the config as an object
    var selecton = new Selecton({
        el: '#selecton-container'
    });

    // pass the data and the order to selecton
    selecton.update(data, order);

    // listen for changes
    selecton.on('change', function(data){
        console.log(data); // only the selected items, alternatively use selecton.getData()
    });
</script>

Configuration and options

Constructor config

config	description	required	type	default
el	css selector of element in which selecton will appear	✅	string
key	which property is used to bind the data	❌	function	function(d){ return d.key; }
renderInputItem	render input item	❌	function	function(d){ return d.key; }
renderDropdownItem	render drop-down item	❌	function	function(d){ return d.key; }
open	drop-down opens up on start	❌	boolean	false
showHierachyButton	show hierarchy button in input item	❌	boolean	true
showRemoveButton	show remove button in input item	❌	boolean	true

Item properties

property	description	required	type	default
key	this key is used to bind the the data to the DOM-element. this key has to be unique within the parent.	✅	string
color	if color is specified, the color is used to colorize the input item	❌	string	'#1e90ff'
selectable	selectable decides if the item is click-able and search-able	❌	boolean	true
closed	does not show up on start	❌	boolean	true
selected	indicated if the item is selected	❌	boolean	false

The following properties are used internally by selecton.js and should not be overwritten:

property	description	type
_depth_	depth level in hierarchy	number
_parent_	key of parent	string
_search_	search string to highlight search match	string
_temporarilyHighlighted_	property to highlight item temporarily	boolean

Methods

Each selecton instance comes with some useful methods:

selecton.update() updates the the input and the drop-down menu

selecton.on('change', callback) Listen for changes

selecton.on('keyup', callback) Listen for keyup event

selecton.getData() returns the whole data set with the computed values as objects

selecton.getSelectedItems() returns the selected items as objects

Dependencies

Selecton.js uses d3-selection for the data-binding and d3-drag for the dragging.

Browser support

Chrome, Safari, Firefox, IE11+