---
title: API
tags: docs
---

{% from "macro_config.njk" import config_table %}

<p>Instances of Tom Select can be controlled programmatically via the methods described in this section.</p>

{% highlight "js" %}
var control = new TomSelect('#select');
control.addOption({value:'test'});
control.addItem('test');
{% endhighlight %}

<p>To address an already <em>existing</em> Tom Select control, you can get it with:</p>
{% highlight "js" %}
let select = document.getElementById('#select');
let control = select.tomselect;
{% endhighlight %}

<h2>Constructor</h2>

{% highlight "js" %}
new TomSelect(input_element,settings);
{% endhighlight %}
<p>
Where <code>input_element</code> is a <a href="/docs/#glossary">NodeDefinition</a> of an <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement">Input Element</a> or
<a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLSelectElement">Select Element</a>.
Note: using CSS Selectors that match multiple elements will only create a Tom Select instance on the first matching element.
</p>

<h2>Option Methods</h2>

<table class="table table-striped">
	<thead>
	<tr>
		<th width="120px">Method</th>
		<th>Description</th>
	</tr>
	</thead>
	<tr>
		<td><code>addOption(data,user_created=false)</code></td>
		<td>Adds an available option.
		If it already exists, nothing will happen.
		Options created with <code>user_created=true</code> will not show up as available options once they are unselected if <code>settings.persist=false</code>
		Note: this does not refresh the options list dropdown (use refreshOptions() for that).
	</td>
	</tr>
	<tr>
		<td><code>addOptions(data[],user_created=false)</code></td>
		<td>Adds an array of options</td>
	</tr>

	<tr>
		<td><code>updateOption(value, data)</code></td>
		<td>Updates an option available for selection. If it is visible in the selected items or options dropdown, it will be re-rendered automatically.</td>
	</tr>
	<tr>
		<td><code>removeOption(value)</code></td>
		<td>Removes the option identified by the given value.</td>
	</tr>
	<tr>
		<td><code>getOption(value,create=false)</code></td>
		<td>Retrieves the dom element for the option identified by the given value. If <code>create</code> is true, the dom element will be created if it hasn't already been created.</td>
	</tr>
	<tr>
		<td><code>getAdjacent(HTMLElement, direction)</code></td>
		<td>Retrieves the dom element for the previous or next option, relative to the currently highlighted option. The <code>direction</code> argument should be 1 for "next" or -1 for "previous".</td>
	</tr>
	<tr>
		<td><code>refreshOptions(triggerDropdown)</code></td>
		<td>Refreshes the list of available options shown in the autocomplete dropdown menu.</td>
	</tr>
	<tr>
		<td><code>clearOptions(clearFilter?)</code></td>
		<td>
			<p>Removes all unselected options from the control. To clear selection options, call clear() before calling clearOptions().</p>
			<p>As of v2.1, a custom clearFilter() can be passed as an argument to control which options are removed.</p>
		</td>
	</tr>
	<tr>
		<td><code>clearFilter(option,value)</code></td>
		<td>Callback used by clearOptions() to decide whether or not an option should be removed. Return true to keep an option, false to remove</td>
	</tr>
</table>

<h2>Item Methods</h2>
<table class="table table-striped">
	<thead>
	<tr>
		<th width="120px">Method</th>
		<th>Description</th>
	</tr>
	</thead>
	<tr>
		<td><code>clear(silent)</code></td>
		<td>Resets / clears all selected items from the control. If <code>silent</code> is truthy, no change event will be fired on the original input.</td>
	</tr>
	<tr>
		<td><code>getItem(value)</code></td>
		<td>Returns the dom element of the item matching the given value.</td>
	</tr>
	<tr>
		<td><code>addItem(value, silent)</code></td>
		<td>"Selects" an item. Adds it to the list at the current caret position. If <code>silent</code> is truthy, no change event will be fired on the original input.</td>
	</tr>
	<tr>
		<td><code>removeItem(value|HTMLElement, silent)</code></td>
		<td>Removes the selected item matching the provided value. If <code>silent</code> is truthy, no change event will be fired on the original input.</td>
	</tr>
	<tr>
		<td><code>createItem(value, [callback])</code></td>
		<td>
			Invokes the <code>create</code> method provided in the settings that should provide the data for the new item, given the user input. Once this completes, it will be added to the item list.
			Prior to v2.1.1, the method's signature was <code>createItem( value, [triggerDropdown], and [callback])</code>.
		</td>
	</tr>
	<tr>
		<td><code>refreshItems()</code></td>
		<td>Re-renders the selected item lists.</td>
	</tr>
</table>

<h2>Optgroup Methods</h2>
<table class="table table-striped">
	<thead>
	<tr>
		<th width="120px">Method</th>
		<th>Description</th>
	</tr>
	</thead>
	<tr>
		<td><code>addOptionGroup(id, data)</code></td>
		<td>Registers a new optgroup for options to be bucketed into. The <code>id</code> argument refers to a value of the property in option identified by the <code>optgroupField</code> setting.</td>
	</tr>
	<tr>
		<td><code>removeOptionGroup(id)</code></td>
		<td>Removes a single option group.</td>
	</tr>
	<tr>
		<td><code>clearOptionGroups()</code></td>
		<td>Removes all existing option groups.</td>
	</tr>
</table>

<h2>Event Methods</h2>
<table class="table table-striped">
<thead>
	<tr>
		<th width="120px">Method</th>
		<th>Description</th>
	</tr>
</thead>
	<tr>
		<td><code>on(event, handler)</code></td>
		<td>Adds an event listener.</td>
	</tr>
	<tr>
		<td><code>off(event, handler)</code></td>
		<td>Removes an event listener.</td>
	</tr>
	<tr>
		<td><code>off(event)</code></td>
		<td>Removes all event listeners.</td>
	</tr>
	<tr>
		<td><code>trigger(event, ...)</code></td>
		<td>Triggers event listeners.</td>
	</tr>
</table>

<h2>Dropdown Methods</h2>
<table class="table table-striped">
<thead>
	<tr>
		<th width="120px">Method</th>
		<th>Description</th>
	</tr>
</thead>
	<tr>
		<td><code>open()</code></td>
		<td>Shows the autocomplete dropdown containing the available options.</td>
	</tr>
	<tr>
		<td><code>close()</code></td>
		<td>Closes the autocomplete dropdown menu.</td>
	</tr>
	<tr>
		<td><code>positionDropdown()</code></td>
		<td>Calculates and applies the appropriate position of the dropdown.</td>
	</tr>
</table>

<h2>Other Methods</h2>
<table class="table table-striped">
<thead>
	<tr>
		<th width="120px">Method</th>
		<th>Description</th>
	</tr>
</thead>
	<tr>
		<td><code>destroy()</code></td>
		<td>Destroys the control and unbinds event listeners so that it can be garbage collected.</td>
	</tr>
	<tr>
		<td><code>load(query)</code></td>
		<td>Initiates loading options from your remote data provider for the given query string. See the <a href="/docs/#callbacks">load() callback</td>
	</tr>
	<tr>
		<td><code>focus()</code></td>
		<td>Brings the control into focus.</td>
	</tr>
	<tr>
		<td><code>blur()</code></td>
		<td>Forces the control out of focus.</td>
	</tr>
	<tr>
		<td><code>lock()</code></td>
		<td>Disables user input on the control (note: the control can still receive focus).</td>
	</tr>
	<tr>
		<td><code>unlock()</code></td>
		<td>Re-enables user input on the control.</td>
	</tr>
	<tr>
		<td><code>disable()</code></td>
		<td>Disables user input on the control completely. While disabled, it cannot receive focus.</td>
	</tr>
	<tr>
		<td><code>enable()</code></td>
		<td>Enables the control so that it can respond to focus and user input.</td>
	</tr>
	<tr>
		<td><code>getValue()</code></td>
		<td>Returns the value of the control. If multiple items can be selected with a "select" input tag (e.g. <a href="/docs#maxItems">&lt;select multiple&gt;</a>), this returns an array. Otherwise, returns a string (separated by <code>delimiter</code> if "multiple").</td>
	</tr>
	<tr>
		<td><code>setValue(value, silent)</code></td>
		<td>Resets the selected items to the given value.</td>
	</tr>
	<tr>
		<td><code>setCaret(index)</code></td>
		<td>Moves the caret to the specified position (<code>index</code> being the index in the list of selected items).</td>
	</tr>
	<tr>
		<td><code>isFull()</code></td>
		<td>Returns whether or not the user can select more items.</td>
	</tr>
	<tr>
		<td><code>clearCache()</code></td>
		<td>Clear cached option renderings.</td>
	</tr>
	<tr>
		<td><code>setTextboxValue(str)</code></td>
		<td>Sets the value of the input field.</td>
	</tr>
	<tr>
		<td><code>sync()</code></td>
		<td>Synchronizes the Tom Select instance with the underlying &lt;select&gt; or &lt;input&gt;</td>
	</tr>
</table>

<h2>Related Objects</h2>

<h4>Search</h4>

<table class="table table-striped">
<thead>
	<tr>
		<th width="120px">Option</th>
		<th>Description</th>
		<th width="60px">Type</th>
	</tr>
</thead>
	<tr>
		<td><code>options</code></td>
		<td>Original search options.</td>
		<td><code>object</code></td>
	</tr>
	<tr>
		<td><code>query</code></td>
		<td>The raw user input.</td>
		<td><code>string</code></td>
	</tr>
	<tr>
		<td><code>tokens</code></td>
		<td>An array containing parsed search tokens. A token is an object containing two properties: <code>string</code> and <code>regex</code> .</td>
		<td><code>array</code></td>
	</tr>
	<tr>
		<td><code>total</code></td>
		<td>The total number of results.</td>
		<td><code>int</code></td>
	</tr>
	<tr>
		<td><code>items</code></td>
		<td>A list of matched results. Each result is an object containing two properties: <code>score</code> and <code>id</code> .</td>
		<td><code>array</code></td>
	</tr>
</table>
