Overview

Tokenize2 has a lot of amazing options and events, in order to simplify the comprehension of these, we will present all options and then it will be detailed with example and demos.

Option name Default Description
dataSource 'select' Define where Tokenize2 will get values. You can use select, an URL for remote data or a callable.
debounce 0 Define the waiting time in milliseconds between remote searches. Available only if dataSource is an URL.
delimiter , Define the tokens delimiter, you can use a string or an array of string if you want use multiple delimiters.
sortable false This option require jQuery UI.
Define if tokens are sortable.
placeholder false Define the form control placeholder, if it's false no placeholder will be displayed.
tokensMaxItems 0 Define the maximum number of tokens allowed in the control, unlimited if it's 0.
tokensAllowCustom false Define if custom tokens are allowed.
dropdownMaxItems 10 Define the maximum number of items displayed in the search dropdown.
searchMinLength 0 Define the minimum number of characters required to start searching.
searchMaxLength 0 Define the maximun number of characters allowed for search (token length as well if custom).
searchFromStart true Define if search will find result from the begining of string. This option is only available for select value in dataSource option.
searchHighlight true Define if search will be highlighted in result items.
displayNoResultsMessage false Define if no result message have to be display.
noResultsMessageText No results mached "%s" Define no results label.
zIndexMargin 500 Define the z-index positive margin from the parent z-index.
tabIndex 0 Define Tokenize2 tab-index.
allowEmptyValues false Allow empty value for tokens.

To define options for Tokenize2 just do like the example below.

$('.tokenize-demo').tokenize2({
    placeholder: "Type something to start..."
});

Options demonstration

dataSource

3 types of value are allowed for this option, select for local datas, an URL for remote datas and a callable if you want to make your own function. The default value is select.

Usage with local datas

For this usage you have to create an fill a <select> form control with all values as <option> tag.

<select class="tokenize-source-demo-1" multiple>
    <option value="Africa">Africa</option>
    <option value="Americas">Americas</option>
    <option value="Asia">Asia</option>
    <option value="Europe">Europe</option>
    <option value="Oceania">Oceania</option>
</select>

Just add 'select' value for the dataSource option.

$('.tokenize-source-demo-1').tokenize2({
    dataSource: 'select'
});

Usage with remote datas

To use this type of data source, you have two things to do. First configure Tokenize2 to get datas from a remote URL and then create the remote script to find datas according search.

In the example below, I have a JSON file containing a list of all countries and a PHP script file who will find in the JSON file the result according searching value.

$('.tokenize-source-demo-2').tokenize2({
    dataSource: 'remote.php'
});

Search value is passed with search post value in the request.

Usage with callable datas (Experimental)

Callable option allow you to create your own search function. In the example below we will create a custom function to call Ajax and replace search request data with term.

$('.tokenize-source-demo-3').tokenize2({
    dataSource: function (term, object) {
        $.ajax('remote.php', {
            type: 'POST',
            data: { search: term, start: 0 },
            dataType: 'json',
            success: function (data) {
                var $items = [];
                object.trigger('tokenize:dropdown:clear');
                $.each(data, function (k, v) {
                    $items.push(v);
                });
                object.trigger('tokenize:dropdown:show');
                object.trigger('tokenize:dropdown:fill', [$items]);
            }
        });
    }
});

Note in the example above that you need to trigger the tokenize:dropdown:fill event to display the result in the dropdown.

debounce

The debounce option allow you to set a waiting time between each search.
This option in only available in you use dataSource with an URL.

By default, there is not waiting time, requests are executed each time a letter is typed in the Tokenize2 field.

In the example below we have set debounce to 1000 (1 second).

$('.tokenize-debounce-demo').tokenize2({
    dataSource: 'remote.php',
    debounce: 1000
});

delimiter

Delimiter option allow you to define which character will validate a token. You can define a single character or an array of chars. The default value is the comma ,.

Note that the tab and return key validate the token too.

In the example below we will set both , and - for delimiter.
For the purposes of demonstration we set tokensAllowCustom to true.

Type something in the box below an validate it with one of the delimiters.

$('.tokenize-delimiter-demo').tokenize2({
    delimiter: [',', '-']
});

sortable

This option allow to use the sortable api of the jQuery UI library for the tokens.

Results using $('.tokenize-sortable-demo').data('tokenize2').toArray().join(', '):

$('.tokenize-sortable-demo').tokenize2({
    sortable: true
});

placeholder

This placeholder option add a placeholder to the Tokenize2 control. By default there is no placeholder.

$('.tokenize-delimiter-demo').tokenize2({
    placeholder: 'Type something to start...'
});

The placeholder style can be customized using .tokenize > .tokens-container > .placeholder CSS class.

tokensMaxItems

This option allow you to restrict the maximum number of tokens.

In the example below we have limited the number of tokens to 6.

$('.tokenize-max-demo').tokenize2({
    tokensMaxItems: 6
});

tokensAllowCustom

The tokensAllowCustom option allow you to create custom tokens, type a text that is not in the search result and validate it with the delimiter ,, return or tab key.

$('.tokenize-custom-demo').tokenize2({
    tokensAllowCustom: true
});

In case of you type for example switz, the default behavior in when you type a validation key (return or tab) the token Switzerland will be added. If you really want to add switz, just hold the control key when pressing validation key.

Note that this behavior dosen't work with delimiters.

dropdownMaxItems

This options allow you to change the maximum number of search result displayed in the dropdown. The default value is 10.

$('.tokenize-dropdown-demo').tokenize2({
    dropdownMaxItems: 5
});

searchMinLength

The searchMinLength option allow you to specify the minimum of characters required to start searching.

$('.tokenize-min-demo').tokenize2({
    searchMinLength: 3
});

searchFromStart

This options allow you to specify if Tokenize2 will search from the begining of a string, but default this option is set to true.

In the example below we have set the option to false.

$('.tokenize-start-demo').tokenize2({
    searchFromStart: false
});

searchHighlight

The searchHighlight options allow you to choose if you want your search highlighted in the result dropdown. By default this option is set to true.

In the example below we have set the option to false.

$('.tokenize-highlight-demo').tokenize2({
    searchHighlight: false
});

dropdownSelectFirstItem

The dropdownSelectFirstItem option allow you to choose if the first item is automatically selected on search, usefull to be false when tokensAllowCustom is true. By default this option is set to true.

In the example below we have set the option to false.

$('.tokenize-select-first-demo').tokenize2({
    tokensAllowCustom: true,
    dropdownSelectFirstItem: false
});