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+