Usage Documentation

Single instance using an #id selector

<script src="tom-select.complete.js"></script>
<link href="tom-select.bootstrap4.css" rel="stylesheet" />
<input id="select" />
<script>
var settings = {};
new TomSelect('#select',settings);
</script>

Multiple instances using a .class selector

<script src="tom-select.complete.js"></script>
<link href="tom-select.bootstrap4.css" rel="stylesheet" />
<input class="select" /> ... <input class="select" />
<script>
document.querySelectorAll('.select').forEach((el)=>{
	let settings = {};
 	new TomSelect(el,settings);
});
</script>

Glossary

Settings
Configuration parameters passed to the TomSelect constructor and accessible with the settings property of the select object
Options
The list of objects to display. Each object must have a property with an unique value to identify the option; the property name is defined by the valueField setting. Option objects must also have a property with the label to display (as tag, in the drop down, etc.); the property name is defined by the labelField setting. The options can have other properties, ignored, unless referenced by other settings, like sortField or searchField.
Items
The list of selected options. Or more exactly, the list of the values of the selected options.
NodeDefinition
An HTMLElement or DOMString. If a DOMString is used, it should either be a CSS Selector or a string of HTML compatible with innerHTML.

General Configuration

Setting Description Type Default
options By default this is populated from the original <input> or <select> element.
options: [
	{ value: "opt1", text: "Option 1" },
	{ value: "opt2", text: "Option 2" },
]
array []
items An array of the initial selected values. By default this is populated from the original input element.
items: ["opt1"]
array []
create Determines if the user is allowed to create new items that aren't in the initial list of options. This setting can be any of the following: true, false, or a function.
create: true
create: function(input){
	return {value:input,text:input}
}
create: function(input,callback){
	callback({value:input,text:input});
}
boolean|function false
createOnBlur If true, when user exits the field (clicks outside of input), a new option is created and selected (if create setting is enabled). boolean false
createFilter Specifies a RegExp or a string containing a regular expression that the current search filter must match to be allowed to be created. May also be a predicate function that takes the filter text and returns whether it is allowed. RegExp|string|function null
delimiter The string to separate items by. When typing an item in a multi-selection control allowing creation, then the delimiter, the item is added. If you paste delimiter-separated items in such control, the items are added at once. The delimiter is also used in the getValue API call on a text <input> tag to separate the multiple values. string ','
highlight Toggles match highlighting within the dropdown menu. boolean true
persist If false, items created by the user will not show up as available options once they are unselected. boolean true
openOnFocus Show the dropdown immediately when the control receives focus. boolean true
maxOptions The max number of options to display in the dropdown. Set maxOptions to null for an unlimited number of options. int 50
maxItems The max number of items the user can select. A value of 1 makes the control mono-selection, null allows an unlimited number of items. int null
hideSelected If true, the items that are currently selected will not be shown in the dropdown list of available options. This defaults to true when in a multi-selection control, to false otherwise. boolean null
closeAfterSelect After a selection is made, the dropdown will remain open if in a multi-selection control or will close in a single-selection control. Setting closeAfterSelect to true will force the dropdown to close after selections are made. Setting closeAfterSelect to false will keep the dropdown open after selections are made. boolean undefined
allowEmptyOption If true, any options with a "" value will be treated like normal. This defaults to false to accommodate the common <select> practice of having the first empty option to act as a placeholder. boolean false
loadThrottle The number of milliseconds to wait before requesting options from the server or null. If null, throttling is disabled. Useful when loading options dynamically while the user types a search / filter expression. int 300
loadingClass The class name added to the wrapper element while awaiting the fulfillment of load requests. string 'loading'
placeholder The placeholder of the control. Defaults to input element's placeholder, unless this one is specified. To update the placeholder setting after initialization, call inputState()
const tom = new TomSelect('#input-id');
tom.settings.placeholder = "New placeholder";
tom.inputState();
string undefined
hidePlaceholder If true, the placeholder will be hidden when the control has one or more items (selected options) and is not focused. This defaults to false when in a multi-selection control, and to true otherwise. boolean null
preload If true, the load function will be called upon control initialization (with an empty search). Alternatively it can be set to 'focus' to call the load function when control receives focus. boolean|string false
The element the dropdown menu is appended to. If null, the dropdown will be appended as a child of the control. string null
addPrecedence If true, the "Add..." option is the default selection in the dropdown. boolean false
selectOnTab If true, the tab key will choose the currently selected item. boolean false
diacritics Enable or disable international character support. boolean true
controlInput Supply a custom <input> element. Supplying a null value will disable the default functionality. NodeDefinition|null <input...>
duplicates Allow selecting the same option more than once. hideSelected should also be set to false. boolean false

Data / Searching

Setting Description Type Default
options See above array []
optgroups Option groups that options will be bucketed into. If your element is a <select> with <optgroup>s this property gets populated automatically. Make sure each object in the array has a property named whatever optgroupValueField is set to. array []
dataAttr The <option> attribute from which to read JSON data about the option. string null
valueField The name of the property to use as the value when an item is selected. string 'value'
optgroupValueField The name of the option group property that serves as its unique identifier. string 'value'
labelField The name of the property to render as an option / item label (not needed when custom rendering functions are defined). string 'text'
optgroupLabelField The name of the property to render as an option group label (not needed when custom rendering functions are defined). string 'label'
optgroupField The name of the property to group items by. string 'optgroup'
disabledField The name of the property to disabled option and optgroup. string 'disabled'
sortField

sortField maps directly to the sort setting in Sifter.

By default, results will be sorted by their $score first, then by the original order of options. To disable sorting entirely and maintain the original order of options, use:

sortField:[{field:'$order'},{field:'$score'}]
string
array
function
[{field:'$score'}, {field:'$order'}]
searchField An array of property names to analyze when filtering options.
searchField: ['text','text2']

Weights can be given to each field to improve search results

searchField: [{field:'text',weight:2},{field:'text2',weight:0.5}]

To completely disable the client side filtering (if youre getting the search results from an external source), set the searchField to an empty array.

searchField: []
array ['text']
searchConjunction When searching for multiple terms (separated by space), this is the operator used. Can be 'and' or 'or' . string 'and'
lockOptgroupOrder If truthy, all optgroups will be displayed in the same order as they were added (by the `$order` property). Otherwise, it will order based on the score of the results in each. boolean false
copyClassesToDropdown Copy the original input classes to the dropdown element. boolean true

Callbacks

new TomSelect('#select',{
	onInitialize:function(){
		// the onInitialize callback is invoked once the control is completely initialized.
	}
});
Setting Description
load(query, callback) Invoked when new options should be loaded from the server. Called with the current query string and a callback function to call with the results when they are loaded (or nothing when an error arises). Remote data examples
shouldLoad(query) Use the shouldLoad() callback to implement minimum input length or other input validation. If the callback returns false, load() will not be called and the not_loading template will be added to the dropdown instead of the loading or no_results templates.
score(search) Overrides the scoring function used to sort available options. The provided function should return a function that returns a number greater than or equal to zero to represent the score of an item (the function's first argument). If 0, the option is declared not a match. See the remote data examples for a sample implementation.
onInitialize() Invoked once the control is completely initialized.
onFocus() Invoked when the control gains focus.
onBlur() Invoked when the control loses focus.
onChange(value) Invoked when the value of the control changes.
onItemAdd(value, $item) Invoked when an item is selected.
onItemRemove(value, $item) Invoked when an item is deselected.
onClear() Invoked when the control is manually cleared via the clear() method.
onDelete(values, event) Invoked when the user attempts to delete the current selection. Selected items will not be deleted if the callback returns false.
onOptionAdd(value, data) Invoked when a new option is added to the available options list.
onOptionRemove(value) Invoked when an option is removed from the available options.
onDropdownOpen(dropdown) Invoked when the dropdown opens.
onDropdownClose(dropdown) Invoked when the dropdown closes.
onType(str) Invoked when the user types while filtering options.
onLoad(options, optgroup) Invoked when new options have been loaded and added to the control (via the load option or load API method).

Render Templates

Nearly every piece of HTML in Tom Select is customizable with a render template. Each template is defined by a function that is passed two arguments (data and escape) and returns NodeDefinition with a single root element. The escape argument is a function that takes a string and escapes all special HTML characters. This is very important to use to prevent XSS vulnerabilities.

new TomSelect('#input',{
	optionClass: 'option',
	itemClass: 'item',
	render:{
		option: function(data, escape) {
			return '<div>' + escape(data.text) + '</div>';
		},
		item: function(data, escape) {
			return '<div>' + escape(data.text) + '</div>';
		},
		option_create: function(data, escape) {
			return '<div class="create">Add <strong>' + escape(data.input) + '</strong>&hellip;</div>';
		},
		no_results:function(data,escape){
			return '<div class="no-results">No results found for "'+escape(data.input)+'"</div>';
		},
		not_loading:function(data,escape){
			// no default content
		},
		optgroup: function(data) {
			let optgroup = document.createElement('div');
			optgroup.className = 'optgroup';
			optgroup.appendChild(data.options);
			return optgroup;
		},
		optgroup_header: function(data, escape) {
			return '<div class="optgroup-header">' + escape(data.label) + '</div>';
		},
		loading:function(data,escape){
			return '<div class="spinner"></div>';
		},
		dropdown:function(){
			return '<div></div>';
		}
	}
});
Setting Description Type Default
render.option An option in the dropdown list of available options. function null
render.item An item the user has selected. function null
render.option_create The "create new" option at the bottom of the dropdown. The data contains one property: input (which is what the user has typed). function null
render.optgroup_header The header of an option group. function null
render.optgroup The wrapper for an optgroup. The html property in the data will be the raw html of the optgroup's header and options. function null
render.no_results Displayed when no options are found matching a user's search. Can be set to null to disable displaying a "no results found" message. function null
render.loading Displayed when the load() method is called and hidden once results are returned. function null
render.dropdown Where dropdown content will be displayed. function null