Skip to content
This repository has been archived by the owner on Jun 18, 2019. It is now read-only.


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Build Status NPM version

Velge (ch•oose)

  1. verb - Pick out or select as being the most appropriate of two or more alternatives.
  2. noun - Nimble autocompleting tag management in javascript

Velge Example

Velge is a nimble tag management widget. It is written in pure javascript, has no dependencies, is fully tested with Mocha, and can be installed via NPM or Bower.

Some of the features:

  • Event emission for all state and ui events.
  • Fuzzy pattern matching for searching.
  • Customizable sorting, validation, normalization.
  • Keyboard shortcuts for navigation, quick submission, and removal.

The library is very lightweight and constructed in a way that allows for easy feature additions. We'd love more people to use it, request features, and contribute!


The simplest way is through NPM:

npm install velge --save

You'll then want to import the compiled .js and .css:

<link href="/node_modules/velge/dist/velge.css" rel="stylesheet" type="text/css">
<script src="/node_modules/velge/dist/velge.min.js"></script>

If you prefer to import velge directly you can import it directly through CommonJS:

var velge = require('velge');


Velge can be attached to any container. The structure isn't of any importance:

<div class='velge'></div>

Initialize velge with a selector for the container and customization options:

var container = document.getElementById('container');

var velge = new Velge(container, {
  placeholder: 'Choose'

Any choices that are provided at initialization will be used to pre-populate the dropdown and chosen lists.

Loading Tags

All tag matching is performed locally. As such you must load in all possible choices and an optional set of chosen values:

  .add({ name: 'orange' })
  .add({ name: 'berry' })
  .add({ name: 'tangy' });

  .choose({ name: 'apple' })
  .choose({ name: 'juicy' });

// Choices: 'orange', 'berry', 'tangy', 'apple', 'juicy'

Tag objects can be anything that have a "name" property. Whatever object is loaded is what will be passed to any callbacks.

It isn't always tidy to add choices and chosen separately. For convenience they can also be loaded during construction:

new Velge(element, {
  choices: [
    { name: 'macintosh' },
    { name: 'cortland' }
  chosen: [
    { name: 'jonagold' },
    { name: 'snow sweet' }


The velge instance emits events for persisting changes after tags have been added, chosen, rejected, or deleted.

  .on('add',    function(object) { console.log('added', object) })
  .on('choose', function(object) { console.log('chose', object) })
  .on('reject', function(object) { console.log('reject', object) })
  .on('delete', function(object) { console.log('deleted', object) });

You may prefer to save all changes at the same time, maybe via a more form-like submit action. That can be achieved by using getChosen:

var chosen = velge.getChosen();
var names  = { return });

Other Events

Sometimes it is helpful to be notified of DOM level events within velge. Currently velge provides focus events which are bubbled up from the input area.

  .on('focus', function(event) { console.log('has focus'); })
  .on('blur',  function(event) { console.log('lost focus'); })


By default choices will be displayed in the order they were added. It is possible to specify a sorting behavior during construction, or afterwards:

var comparitor = function(a, b) {
  if ( >      { return 1;  }
  else if ( < { return -1; }
  else                      { return 0;  }

var velge = new Velge(element, {
  comparitor: comparitor

// Setting options will trigger an immediate re-sort
velge.setOptions({ comparitor: function(a, b) {
  if (a.createdAt > b.createdAt)      { return 1;  }
  else if (a.createdAt < b.createdAt) { return -1; }
  else                                { return 0;  }

Limitation Mode

While velge is designed as an interface for applying multiple "tags" to a resource it can also operate in single, limitation, mode. Under single mode only the most recent tag will be kept, all others will be unchosen.

var velge = new Velge(element, { limitation: true })

Error Handling

Because velge displays all tag additions instantly it can easily fall out of sync with the underlying collection. If, for example, an ajax request fails you can rollback the addition:

var addCallback = function(choice) {
    data: choice,
    type: "POST",
    url:  "/api/resource/1/tags"
  }).fail(function(error) {


The project is built with modules from NPM. Simply run:

npm install

Once all modules are installed you're all set to test, lint, or build.

npm run test  # scripts/test
npm run lint  # scripts/lint
npm run build # scripts/build


MIT, see LICENSE.txt for details.