Introducing tokeninput

Dependency-free Javascript UI component providing a token based input element with grouped completion lists and free-text entry

Usage

Create an instance of the TokenInput class with two parameters:

• an instance of an Input DOM element
• a configuration object, to tailor the component to your needs

<script src="tokeninput/tokeninput.js" />
<div id="tokeninput">
  <input placeholder="Type something…" />
</div>

new TokenInput( document.getElementById( 'tokeninput' ), {} );

See index.html and demo.js for examples.

There are lots of options, see tokeninput.js

API

Method | Description -------|------------ addEventListener(element, type, listener) | Adds an event listener to the given element. getTokens() | Returns an array of objects representing each token added to the component. getSelectedCompletion() | Returns the datum of the selected completion setSelectedCompletion(datum) | Sets the selected completion getSelectedCompletionElement() | Returns the element of the selected completion removeCompletions() | Removes all the completions setTokens(newTokens) | Removes all existing tokens from the UI and replaces them with the tokens in the given array. setCompletionGroups(completionGroups) | Configures the completion groups that visually separate suggestions. removeFloatingElement() | Hides the suggestion UI. removeToken(datum, options) | Removes the given token from the component UI and the component's internal list of tokens. positionFloatingElement() | Force the floating element to reposition setElementAfterCompletions(element) | Set the element to place after completions setElementBeforeCompletions(element) | Set the element to place before completions getScrollingContainer() | Get the current scrolling container element onUp() | Trigger the up key handler onDown() | Trigger the down key handler destroy() | Cleans up by removing all registered event listeners.

Completions / suggestions

Use the following options to drive how completions are presented:

Option | Description -|- completionsForText|Function that receives the text, delayedCompletionsId and delayedCompletionsFn. Returns datums (objects) for each completion completionClassNames|Function that receives a datum to determine it's class name completionFormatter|Function that receives a datum and corresponding element for further customisation completionGroupClassNames|Function that receives the completion group, returns an array of class names completionGroupHeadingClassNames|Function that receives the completion group heading, returns an array of class names completionGroups|Object of completion group definitions, see demo.js newCompletionOption|Function that receives a group and returns the datum for the 'new' completion, defaults to "+ New (group.singular)"

Other options

Option | Description | Default -----|------------|--------- readOnly | Prevents tokens from being added / removed | false tabToAdd | Pressing the tab key submits the current token and allows a new one to be entered | true xHTML | A string which represents the delete button in a token | × tokenClassNames | A function which is called for each added token. Should return an array of class names that will be added to the token HTML element. | [] tokenFormatter | A function which is called for each added token. Can be used to customise the token element for display when not in inline mode | | inlineTokenFormatter | A function which is called for each added token. Can be used to customise the token element for display when in inline mode | | containerClickTriggersFocus | Determines if a click on the containing element will focus the tokeninput | true freeTextEnabled | Determines whether the user is able to enter arbitrary tokens (true) or forced to select a pre-existing datum (false) | false freeTextToken | A function that determines the makeup of a datum created via free-text | freeTextCompletion | A function that determines the makeup of an object that represents free-text entry which is passwd to the suggestion handler | willShowFreeTextCompletion | A function that determines whether or not to show the completion view for free-text | inlineTokenTrigger | An object which defines logic for determining whether to show completion for typed text when in inline mode | namespace | A string or function to namespace element class names | null autoSelectSingleCompletions | Select the first and only completion automatically | true positionFloatingElement | A function that is passed the floating element for manual positioning | null floatingElementParent | An element to use as the floating elements parent node, defaults to the input elements parent node | null removeOnlyCompletionsListElement | Set to true to only remove the list element rather than the whole floating element | false beforeEnter | Pre-keypress event handler | null beforeCompletionClick | Pre-click event handler | null hintElement | An element to use as a hint container | null scrollingContainerClassName | A selector for the scrolling container, by default the floating element is used | null hintAfterAdd | Show the hint element after adding a token | false disableTokenClick | Disable the build-in token click hander | false disableFocusOnRemove | Disable the automatic behaviour that focuses the input element after removing a token | false placeholderLength | Specify the placeholder length in characters | null