title	tags
Usage Documentation	docs

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

index.md

index.md

Single instance using an #id selector

Multiple instances using a .class selector

Glossary

General Configuration

Data / Searching

Callbacks

Render Templates

Files

index.md

Latest commit

History

index.md

File metadata and controls

Single instance using an #id selector

Multiple instances using a .class selector

Glossary

General Configuration

Data / Searching

Callbacks

Render Templates