Tokenfield %VERSION%

Examples

Create elegant taggable fields with copy/paste and keyboard support.

Using jQuery UI Autocomplete

{% highlight html %} {% endhighlight %} {% highlight js %} $('#tokenfield').tokenfield({ autocomplete: { source: ['red','blue','green','yellow','violet','brown','purple','black','white'], delay: 100 }, showAutocompleteOnFocus: true }) {% endhighlight %}

Using Twitter Typeahead

{% highlight html %} {% endhighlight %} {% highlight js %} var engine = new Bloodhound({ local: [{value: 'red'}, {value: 'blue'}, {value: 'green'} , {value: 'yellow'}, {value: 'violet'}, {value: 'brown'}, {value: 'purple'}, {value: 'black'}, {value: 'white'}], datumTokenizer: function(d) { return Bloodhound.tokenizers.whitespace(d.value); }, queryTokenizer: Bloodhound.tokenizers.whitespace }); engine.initialize(); $('#tokenfield-typeahead').tokenfield({ typeahead: { source: engine.ttAdapter() } }); {% endhighlight %}

Usage

Trigger tokenfield via JavaScript:

{% highlight js %} $('.tokenfield').tokenfield() {% endhighlight %}

Options

Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-, as in data-minLength="".

Name type default description
tokens string, array [] Tokens (or tags). Can be a string with comma-separated values ("one,two,three"), an array of strings (["one","two","three"]), or an array of objects ([{ value: "one", label: "Einz" }, { value: "two", label: "Zwei" }])
allowDuplicates boolean false Whether to allow duplicate tokens or not. A token is considered a duplicated if it's value matches an existing token's value. Therefore, it is possible to enter multiple tokens with the same label, if their values are diefferent.
limit int 0 Maximum number of tokens allowed. 0 = unlimited.
minLength int 0 Minimum length required for token value.
minWidth int 60 Minimum input field width. In pixels.
autocomplete object {} jQuery UI Autocomplete options
showAutocompleteOnFocus boolean false Whether to show autocomplete suggestions menu on focus or not. Works only for jQuery UI Autocomplete, as Typeahead has no support for this kind of behavior.
typeahead object {} Twitter Typeahead options.
createTokensOnBlur boolean false Whether to turn input into tokens when tokenfield loses focus or not.
delimiter string, array ',' A character or an array of characters that will trigger token creation on keypress event. Defaults to ',' (comma). Note - this does not affect Enter or Tab keys, as they are handled in the keydown event. The first delimiter will be used as a separator when getting the list of tokens or copy-pasting tokens.
beautify boolean true Whether to insert spaces after each token when getting a comma-separated list of tokens. This affects both value returned by getTokensList() and the value of the original input field.

Data attributes for individual tokenfields

Options for individual tokenfields can alternatively be specified through the use of data attributes, as explained above.

Styling Twitter Typeahead

Twitter Typeahead comes with no default styling. Make sure to include tokenfield-typeahead.css on your page.

Methods

.tokenfield(options)

Initializes an input with a tokenfield.

{% highlight js %} $('#myField').tokenfield(); {% endhighlight %}

.tokenfield('setTokens', tokens)

Manually set the tokenfield content (replacing the old content)

{% highlight js %} $('#myField').tokenfield('setTokens', 'blue,red,white'); $('#myField').tokenfield('setTokens', ['blue','red','white']); $('#myField').tokenfield('setTokens', [{ value: "blue", label: "Blau" }, { value: "red", label: "Rot" }]); {% endhighlight %}

.tokenfield('createToken', token)

Manually create a token and append it to the input

{% highlight js %} $('#myField').tokenfield('createToken', 'purple'); $('#myField').tokenfield('createToken', { value: 'violet', label: 'Violet' }); {% endhighlight %}

.tokenfield('getTokens', active)

Get an array of tokens from the input. Set active to true to return only selected tokens.

{% highlight js %} $('#myField').tokenfield('getTokens'); {% endhighlight %}

.tokenfield('getTokensList', delimiter, beautify, active)

Get a comma-separated list of the tokens from the input. You can use an alternative separator by supplying also a delimiter argument. Setting beautify to false will prevent adding a space after each token. Set active to true to return only selected tokens.

{% highlight js %} $('#myField').tokenfield('getTokensList'); $('#myField').tokenfield('getTokensList', '; '); {% endhighlight %}

.tokenfield('disable')

Disable tokenfield (just like a normal input field)

{% highlight js %} $('#myField').tokenfield('disable'); {% endhighlight %}

.tokenfield('enable')

Enable tokenfield (just like a normal input field)

{% highlight js %} $('#myField').tokenfield('enable'); {% endhighlight %}

.tokenfield('destroy')

Destroy tokenfield and restore original input

{% highlight js %} $('#myField').tokenfield('destroy'); {% endhighlight %}

Accessing original input

Though not recommended, you can access the original input field like so: $('#tokenfield').data('bs.tokenfield').$input

You can also set new options for the autocomplete or typehead objects from the original input above like so: $('#tokenfield').data('bs.tokenfield').$input.autocomplete({source: new_array})

Events

Tokenfield exposes a few events for hooking into it's functionality.

Event Description
tokenfield:initialize Fires after Tokenfield has been initialized.
tokenfield:preparetoken This event fires when a token is all set up to be created, but before it is inserted into the DOM and event listeners are attached. You can use this event to manipulate token value and label by changing the appropriate values of token property of the event. See below for an example.
tokenfield:createtoken This event is fired after the token has been created. Here, token property of the event is also available, but is basically read-only. You can also get a direct reference to the token DOM object via e.relatedTarget. The example below uses this to set an 'invalid' class on the newly created token if it does not pass validation.
tokenfield:edittoken This event is fired just before a token is about to be edited. This allows you to manipluate the input field value before it is created. Again, to do this, manipluate the token property of the event. Here you can also access the token DOM object with e.relatedTarget.
tokenfield:removetoken This event is fired after a token is removed. You will have access to token property of the event. This way, you can determine which token was removed.
tokenfield:preventduplicate This event is fired when allowDuplicates is set to false and a duplicate is being prevented from created. You can find out the offending token by looking at the token property of the event.

The example below is pretty comprehensive. Here, we split user input into two parts: name and email. Then, we validate the email and if it is not valid, we add an invalid class to the token.

When the user starts to edit the token, we merge token value and label together again.

{% highlight js %} $('#tokenfield') .on('tokenfield:preparetoken', function (e) { var token = e.token.value.split('|') e.token.value = token[1] || token[0] e.token.label = token[1] ? token[0] + ' (' + token[1] + ')' : token[0] }) .on('tokenfield:createtoken', function (e) { // Über-simplistic e-mail validation var re = /\S+@\S+\.\S+/ var valid = re.test(e.token.value) if (!valid) { $(e.relatedTarget).addClass('invalid') } }) .on('tokenfield:edittoken', function (e) { if (e.token.label !== e.token.value) { var label = e.token.label.split(' (') e.token.value = label[0] + '|' + e.token.value } }) .on('tokenfield:removetoken', function (e) { alert('Token removed! Token value was: ' + e.token.value) }) .on('tokenfield:preventduplicate', function (e) { alert('Duplicate detected! Token value is: ' + e.token.value) }) .tokenfield() {% endhighlight %}

Keyboard support

Tokenfield includes support for manipulating tokens via keyboard

left, right arrow keys

Arrow keys will move between active tokens. Try it out: click on one of the tokens and press left and right arrow keys

Backspace and delete

You can delete a selected token with backspace or delete keys. Try it out now:

Ctrl + A / Cmd + A, Ctrl + C / Cmd + C, Ctrl + V, Cmd + V

If You have one token selected, you can select all tokens with the keyboard. Then, you can copy the tokens using keyboard. You can also paste tokens to another field.

Copy & paste support

You can copy tokens from a tokenfield and paste them to any other field as comma-separated values. When you paste to another tokenfield, they will become tokens there, aswell!

Try it out, copy the following to the field below: violet,yellow,brown

Validation states

Tokenfield also supports all the default validation states from Bootstrap

Various examples of using tokenfield

Using tokenfield with input groups

Tags:


Tags:

Using tokenfield with input group checkboxes and radio buttons

Using tokenfield with buttons in input groups


Using tokenfield with different sizes


@
@
@

Disabled tokenfield

Disabled fieldset with tokenfield

Tokenfield in inline form

Tokenfield in horizontal form

Tokenfield with fluid and fixed widths (50%, 300px, etc...)

>

Tokenfield with RTL direction