Usage Documentation

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

<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

options: [
	{ value: "opt1", text: "Option 1" },
	{ value: "opt2", text: "Option 2" },
]

items: ["opt1"]

create: true

create: function(input){
	return {value:input,text:input}
}

create: function(input,callback){
	callback({value:input,text:input});
}

const tom = new TomSelect('#input-id');
tom.settings.placeholder = "New placeholder";
tom.inputState();

Data / Searching

sortField:[{field:'$order'},{field:'$score'}]

searchField: ['text','text2']

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

searchField: []

Callbacks

new TomSelect('#select',{
	onInitialize:function(){
		// the onInitialize callback is invoked once the control is completely initialized.
	}
});

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>';
		}
	}
});