# tokeninput

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

Latest version **1.0.4** (published 2025-10-15) · ISC license · 0 weekly downloads

## Install

```sh
npm install tokeninput
pnpm add tokeninput
yarn add tokeninput
bun add tokeninput
```

## Health

**Score 45/100 (D)** — status: stable.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 1.0.4 |
| Published | 2025-10-15 |
| First published | 2020-10-29 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 71.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | bipsync |
| Maintainers | steveh_bipsync |
| Keywords | token |

## Links

- npm: https://www.npmjs.com/package/tokeninput
- Repository: https://github.com/Bipsync/tokeninput
- Homepage: https://github.com/Bipsync/tokeninput#readme
- Issues: https://github.com/Bipsync/tokeninput/issues
- npm.io page: https://npm.io/package/tokeninput

## Recent versions

- 1.0.4 (latest) — 2025-10-15
- 1.0.3 — 2025-10-10
- 1.0.2 — 2025-07-10
- 1.0.0 — 2020-10-29

## README

### 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

```html
<script src="tokeninput/tokeninput.js" />
<div id="tokeninput">
  <input placeholder="Type something…" />
</div>
```
```javascript
new TokenInput( document.getElementById( 'tokeninput' ), {} );
```

See [index.html](index.html) and [demo.js](demo.js) for examples.

There are lots of options, see [tokeninput.js](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 | `&times;`
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`

---
_Source: https://npm.io/package/tokeninput · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._