Tom Select

https://tom-select.js.org/
Admin
Tom Select is a lightweight and customizable select/dropdown component for web applications with...
Tokens:37,735
Snippets:306
Trust Score:8.1
Update:1 week ago
Show doc for...
Tokens:
Raw
### Start local development server

Source: https://tom-select.js.org/docs/contribute

Starts a web server to view a local copy of tom-select.js.org. Once started, examples are available at http://localhost:8000/.

```bash
$ npm start
```

--------------------------------

### Hook after setup method

Source: https://tom-select.js.org/docs/plugins

Use this.hook('after', 'setup', ...) to run additional setup code after the control's setup method.

```javascript
// in src/plugins/plugin_name/plugin.js
export default function(plugin_options) {
	this.hook('after', 'setup', function() {
		// .. additional setup
	});
};
```

--------------------------------

### Install via npm

Source: https://tom-select.js.org/

Install Tom Select using npm package manager.

```bash
npm i tom-select
```

--------------------------------

### Override setup method with 'instead' hook

Source: https://tom-select.js.org/docs/plugins

Use this.hook('instead', 'setup', ...) to override the setup method. Ensure the overridden function returns a value if the original does.

```javascript
// in src/plugins/plugin_name/plugin.js
export default function(plugin_options) {
	var original_setup = this.setup;
	this.hook('instead', 'setup', function() {
		// .. custom setup
		return original_setup.apply(this, arguments);
	});
};
```

--------------------------------

### CSS for example wrapper

Source: https://tom-select.js.org/plugins/no-backspace-delete

Required CSS to set the positioning context for the example wrapper.

```css
#example-wrapper{
	position:relative;
}
```

--------------------------------

### Event Log HTML Setup

Source: https://tom-select.js.org/examples/events

HTML structure for the event log example: a multi-select element with US state options and a pre element to display events. The Wyoming option is pre-selected.

```html
<select id="select-state" multiple name="state[]">
	<option value="">Select a state...</option>
	<option value="AL">Alabama</option>
	<option value="AK">Alaska</option>
	<option value="AZ">Arizona</option>
	<option value="AR">Arkansas</option>
	<option value="CA">California</option>
	<option value="CO">Colorado</option>
	<option value="CT">Connecticut</option>
	<option value="DE">Delaware</option>
	<option value="DC">District of Columbia</option>
	<option value="FL">Florida</option>
	<option value="GA">Georgia</option>
	<option value="HI">Hawaii</option>
	<option value="ID">Idaho</option>
	<option value="IL">Illinois</option>
	<option value="IN">Indiana</option>
	<option value="IA">Iowa</option>
	<option value="KS">Kansas</option>
	<option value="KY">Kentucky</option>
	<option value="LA">Louisiana</option>
	<option value="ME">Maine</option>
	<option value="MD">Maryland</option>
	<option value="MA">Massachusetts</option>
	<option value="MI">Michigan</option>
	<option value="MN">Minnesota</option>
	<option value="MS">Mississippi</option>
	<option value="MO">Missouri</option>
	<option value="MT">Montana</option>
	<option value="NE">Nebraska</option>
	<option value="NV">Nevada</option>
	<option value="NH">New Hampshire</option>
	<option value="NJ">New Jersey</option>
	<option value="NM">New Mexico</option>
	<option value="NY">New York</option>
	<option value="NC">North Carolina</option>
	<option value="ND">North Dakota</option>
	<option value="OH">Ohio</option>
	<option value="OK">Oklahoma</option>
	<option value="OR">Oregon</option>
	<option value="PA">Pennsylvania</option>
	<option value="RI">Rhode Island</option>
	<option value="SC">South Carolina</option>
	<option value="SD">South Dakota</option>
	<option value="TN">Tennessee</option>
	<option value="TX">Texas</option>
	<option value="UT">Utah</option>
	<option value="VT">Vermont</option>
	<option value="VA">Virginia</option>
	<option value="WA">Washington</option>
	<option value="WV">West Virginia</option>
	<option value="WI">Wisconsin</option>
	<option value="WY" selected>Wyoming</option>
</select>
<h3>Event Log</h3>
<pre id="log" style="height:20vh;overflow:auto"></pre>
```

--------------------------------

### HTML select element for large dataset example

Source: https://tom-select.js.org/examples/performance

Provides the HTML select element with id 'select-junk' and placeholder 'Start Typing...' that the JavaScript initializes.

```html
<select id="select-junk" placeholder="Start Typing..."></select>
```

--------------------------------

### onInitialize callback example

Source: https://tom-select.js.org/docs

Shows how to use the onInitialize callback, which is invoked once the control is completely initialized.

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

--------------------------------

### HTML: Input and button for change listener example

Source: https://tom-select.js.org/plugins/change-listener

Provides the HTML markup for the change listener example: a text input with id 'input-change' and a button with id 'change-input' to trigger the change event.

```HTML
<input type="text" id="input-change" value="original value" autocomplete="off">
<button type="button" class="btn btn-sm btn-success" id="change-input">Change original input</button>
```

--------------------------------

### Add DOM event listeners after setup

Source: https://tom-select.js.org/docs/plugins

Use this.hook('after', 'setup', ...) to add event listeners to DOM elements after the control is set up.

```javascript
// in src/plugins/plugin_name/plugin.js
export default function(plugin_options) {
	this.hook('after', 'setup', function() {
		this.control.addEventListener('click',function(evt){
			alert('the control was clicked');
		});
	});
};
```

--------------------------------

### Build custom Tom Select bundle with NPM

Source: https://tom-select.js.org/docs/plugins

Clone the repo, install dependencies, and run the build command with the --plugins flag to create /dist/js/tom-select.custom.js with selected plugins.

```bash
# clone the repo
git clone https://github.com/orchidjs/tom-select.git
cd tom-select

# install dev dependencies
npm install

# create /dist/js/tom-select.custom.js
npm run build -- --plugins=remove_button,restore_on_backspace
```

--------------------------------

### HTML select element for checkbox options example

Source: https://tom-select.js.org/plugins/checkbox-options

Provides the HTML select element with multiple options, including two pre-selected options, used by the checkbox_options example.

```HTML
<select id="ex-checkbox-options" autocomplete="off" multiple>
	<option>amazing</option>
	<option selected>awesome</option>
	<option>cool</option>
	<option selected>excellent</option>
	<option>great</option>
	<option>neat</option>
	<option>superb</option>
	<option>wonderful</option>
</select>
```

--------------------------------

### HTML markup for input_autogrow example

Source: https://tom-select.js.org/plugins/input-autogrow

HTML structure for the example select element with multiple options. The select has the id 'ex-input-autogrow', is multiple, and includes a placeholder 'How cool is this?'. This markup is used with the JavaScript initialization.

```html
<div class="d-inline-block">
<select id="ex-input-autogrow" multiple autocomplete="off" placeholder="How cool is this?">
	<option>amazing</option>
	<option>awesome</option>
	<option>cool</option>
	<option>excellent</option>
	<option>great</option>
	<option>neat</option>
	<option>superb</option>
	<option>wonderful</option>
</select>
</div>
```

--------------------------------

### TomSelect render configuration

Source: https://tom-select.js.org/docs

Example configuration showing how to define custom render templates for various Tom Select UI components, including options, items, create option, optgroup headers, and more.

```APIDOC
## TomSelect render configuration

### Description
Customizes the HTML rendering of Tom Select components by providing render functions for each UI element.

### Method
Constructor option

### Endpoint
new TomSelect('#input', { render: { ... } })

### Parameters
#### render.option
- **type**: function - Required - An option in the dropdown list of available options.

#### render.item
- **type**: function - Required - An item the user has selected.

#### render.option_create
- **type**: function - Required - The "create new" option at the bottom of the dropdown. The data contains one property: `input` (which is what the user has typed).

#### render.optgroup_header
- **type**: function - Required - The header of an option group.

#### render.optgroup
- **type**: function - Required - The wrapper for an optgroup. The `html` property in the data will be the raw html of the optgroup's header and options.

#### render.no_results
- **type**: function - Required - Displayed when no options are found matching a user's search. Can be set to null to disable displaying a "no results found" message.

#### render.loading
- **type**: function - Required - Displayed when the load() method is called and hidden once results are returned.

#### render.dropdown
- **type**: function - Required - Where dropdown content will be displayed.

### Request Example
```javascript
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>';
    }
  }
});
```

### Response
#### Success Response (200)
- **render.option** (function) - An option in the dropdown list of available options.
- **render.item** (function) - An item the user has selected.
- **render.option_create** (function) - The "create new" option at the bottom of the dropdown. The data contains one property: `input` (which is what the user has typed).
- **render.optgroup_header** (function) - The header of an option group.
- **render.optgroup** (function) - The wrapper for an optgroup. The `html` property in the data will be the raw html of the optgroup's header and options.
- **render.no_results** (function) - Displayed when no options are found matching a user's search. Can be set to null to disable displaying a "no results found" message.
- **render.loading** (function) - Displayed when the load() method is called and hidden once results are returned.
- **render.dropdown** (function) - Where dropdown content will be displayed.

#### Response Example
No response example provided.
```

--------------------------------

### Programmatic option group example

Source: https://tom-select.js.org/examples/optgroups

Provides an empty select element with the class 'demo-animals' and placeholder 'Select animal...' for programmatic initialization with Tom Select.

```HTML
<select id="select-animal" class="demo-animals" placeholder="Select animal..."></select>
```

--------------------------------

### HTML select element for dropdown_input example

Source: https://tom-select.js.org/plugins/dropdown-input

HTML markup for the select element used in the dropdown_input example. It includes an autocomplete attribute and a placeholder. The options are predefined with 'awesome' selected by default.

```html
<select id="ex-dropdown-input" autocomplete="off" placeholder="How cool is this?">
	<option>amazing</option>
	<option selected>awesome</option>
	<option>cool</option>
	<option>excellent</option>
	<option>great</option>
	<option>neat</option>
	<option>superb</option>
	<option>wonderful</option>
</select>
```

--------------------------------

### HTML: Input element for restore_on_backspace example

Source: https://tom-select.js.org/plugins/restore-on-backspace

The HTML input element used in the example, with id 'input-tags6', initial value 'awesome,neat', and autocomplete disabled.

```html
<input type="text" id="input-tags6" value="awesome,neat" autocomplete="off">
```

--------------------------------

### HTML: Input element for multiple select example

Source: https://tom-select.js.org/plugins/remove-button

The HTML input element used in the multiple select example. It has the id 'input-tags' and initial value 'awesome,neat'.

```HTML
<input type="text" id="input-tags" value="awesome,neat" autocomplete="off">
```

--------------------------------

### HTML input for no_active_items example

Source: https://tom-select.js.org/plugins/no-active-items

The HTML input element used by the no_active_items example. It has the id 'ex-no-active-items' and initial value 'awesome,neat'.

```HTML
<input type="text" id="ex-no-active-items" value="awesome,neat" autocomplete="off">
```

--------------------------------

### HTML structure for No Backspace Delete example

Source: https://tom-select.js.org/plugins/no-backspace-delete

The HTML markup required to support the Tom Select instance and the custom control input.

```html
<div id="example-wrapper">
<input type="text" id="disable-backspace" value="awesome,neat" autocomplete="off">
<input type="text" id="input-disable-control" class="form-control mt-2"  autocomplete="off" placeholder="How cool is this?" >
</div>
```

--------------------------------

### HTML: Select element for single select example

Source: https://tom-select.js.org/plugins/remove-button

The HTML select element used in the single select example. It has the id 'input-tags2' and contains two options: 'awesome' and 'neat'.

```HTML
<select id="input-tags2" value="awesome" autocomplete="off">
	<option>awesome</option>
	<option>neat</option>
</select>
```

--------------------------------

### onDelete Prompt HTML Input

Source: https://tom-select.js.org/examples/events

HTML input element for the onDelete prompt example, with initial value 'awesome,neat' and placeholder text.

```html
<input id="input-tags" value="awesome,neat" autocomplete="off" placeholder="How cool is this?">
```

--------------------------------

### CSS for Custom Option and Item HTML

Source: https://tom-select.js.org/examples/customization

Styles the custom option and item templates from the previous example. The .title and .url classes are used to format the option content.

```CSS
.ts-wrapper .option .title {
	display: block;
}
.ts-wrapper .option .url {
	font-size: 12px;
	display: block;
	color: #a0a0a0;
}
```

--------------------------------

### HTML select element for caret position example

Source: https://tom-select.js.org/plugins/caret-position

HTML markup for the multiple select element used in the caret position example. It includes the id 'ex-caret-position', multiple attribute, autocomplete off, and a placeholder. The options include selected values 'amazing' and 'awesome'.

```HTML
<select id="ex-caret-position" multiple autocomplete="off" placeholder="How cool is this?">
	<option selected>amazing</option>
	<option selected>awesome</option>
	<option>cool</option>
	<option>excellent</option>
	<option>great</option>
	<option>neat</option>
	<option>superb</option>
	<option>wonderful</option>
</select>
```

--------------------------------

### HTML Input for Virtual Scroll Example

Source: https://tom-select.js.org/plugins/virtual_scroll

The HTML input element that the Tom Select instance is attached to. It has the id 'reddit-search' and a placeholder 'Search reddit'.

```html
<input type="text" id="reddit-search" placeholder="Search reddit" autocomplete="off">
```

--------------------------------

### Build from source

Source: https://tom-select.js.org/docs/contribute

Compile TypeScript and SCSS in the /src directory to JavaScript and CSS in the /buid directory.

```bash
$ npm run build
```

--------------------------------

### Initialize Tom Select with plugins array

Source: https://tom-select.js.org/docs/plugins

Pass an array of plugin names to the plugins option to enable them without any options.

```javascript
new TomSelect('#select',{
	plugins: ['plugin_a', 'plugin_b']
});
```

--------------------------------

### HTML input for drag and drop example

Source: https://tom-select.js.org/plugins/drag-drop

The HTML input element used in the drag and drop example. It has the id 'input-sortable' and a default value of 'drag,these,items,around'.

```HTML
<input type="text" id="input-sortable" value="drag,these,items,around" autocomplete="off">
```

--------------------------------

### Import and define plugins with tom-select/base

Source: https://tom-select.js.org/docs/plugins

Import TomSelect from 'tom-select/base' and plugin modules, then define them with TomSelect.define to make them available.

```javascript
import TomSelect from 'tom-select/base';
import TomSelect_remove_button from 'tom-select/plugins/remove_button.js';
import TomSelect_dropdown_header from 'tom-select/dropdown_header.js';

TomSelect.define('remove_button', TomSelect_remove_button);
TomSelect.define('dropdown_header', TomSelect_dropdown_header);
```

--------------------------------

### Initialize Tom Select with optgroup_columns plugin

Source: https://tom-select.js.org/plugins/optgroup-columns

Creates a Tom Select instance on the #select-car input, configuring options, optgroups, and enabling the optgroup_columns plugin. The plugin displays optgroups in columns and allows navigation with ← and → keys. No additional configuration settings are required for this plugin.

```javascript
new TomSelect("#select-car",{
	options: [
		{id: 'avenger', make: 'dodge', model: 'Avenger'},
		{id: 'caliber', make: 'dodge', model: 'Caliber'},
		{id: 'caravan-grand-passenger', make: 'dodge', model: 'Caravan Grand Passenger'},
		{id: 'challenger', make: 'dodge', model: 'Challenger'},
		{id: 'ram-1500', make: 'dodge', model: 'Ram 1500'},
		{id: 'viper', make: 'dodge', model: 'Viper'},
		{id: 'a3', make: 'audi', model: 'A3'},
		{id: 'a6', make: 'audi', model: 'A6'},
		{id: 'r8', make: 'audi', model: 'R8'},
		{id: 'rs-4', make: 'audi', model: 'RS 4'},
		{id: 's4', make: 'audi', model: 'S4'},
		{id: 's8', make: 'audi', model: 'S8'},
		{id: 'tt', make: 'audi', model: 'TT'},
		{id: 'avalanche', make: 'chevrolet', model: 'Avalanche'},
		{id: 'aveo', make: 'chevrolet', model: 'Aveo'},
		{id: 'cobalt', make: 'chevrolet', model: 'Cobalt'},
		{id: 'silverado', make: 'chevrolet', model: 'Silverado'},
		{id: 'suburban', make: 'chevrolet', model: 'Suburban'},
		{id: 'tahoe', make: 'chevrolet', model: 'Tahoe'},
		{id: 'trail-blazer', make: 'chevrolet', model: 'TrailBlazer'},
	],
	optgroups: [
		{$order: 3, id: 'dodge', name: 'Dodge'},
		{$order: 2, id: 'audi', name: 'Audi'},
		{$order: 1, id: 'chevrolet', name: 'Chevrolet'}
	],
	labelField: 'model',
	valueField: 'id',
	optgroupField: 'make',
	optgroupLabelField: 'name',
	optgroupValueField: 'id',
	lockOptgroupOrder: true,
	searchField: ['model'],
	plugins: ['optgroup_columns'],
	openOnFocus: false
});
```

```html
<input type="text" id="select-car" placeholder="Select cars...">
```

--------------------------------

### open()

Source: https://tom-select.js.org/docs/api

Shows the autocomplete dropdown containing the available options.

```APIDOC
## open()

### Description
Shows the autocomplete dropdown containing the available options.

### Method
open

### Parameters
None

### Returns
None
```

--------------------------------

### HTML: Input for Multiple Select Clear Button Example

Source: https://tom-select.js.org/plugins/clear-button

The HTML input element used by the multiple select clear button example. It has the id 'ex-clear-button' and a default value of 'awesome,neat'.

```html
<input type="text" id="ex-clear-button" value="awesome,neat" autocomplete="off" placeholder="How cool is this?" />
```

--------------------------------

### Initialize Tom Select with plugin options object

Source: https://tom-select.js.org/docs/plugins

Pass an object mapping plugin names to their options to configure plugins individually.

```javascript
new TomSelect('#select',{
	plugins: {
		'plugin_a': { /* ... */ },
		'plugin_b': { /* ... */ }
	}
});
```

--------------------------------

### HTML: Select for Single Select Clear Button Example

Source: https://tom-select.js.org/plugins/clear-button

The HTML select element used by the single select clear button example. It has the id 'clear-button-single' and includes options for 'How cool is this?', 'awesome', and 'neat'.

```html
<select type="text" id="clear-button-single" autocomplete="off">
	<option value="">How cool is this?</option>
	<option selected>awesome</option>
	<option>neat</option>
</select>
```

--------------------------------

### HTML: Select for Single Select with Empty Option Clear Button Example

Source: https://tom-select.js.org/plugins/clear-button

The HTML select element used by the single select with empty option example. It has the id 'clear-button-empty' and includes options for 'How cool is this?', 'awesome', and 'neat'.

```html
<select type="text" id="clear-button-empty" autocomplete="off">
	<option value="">How cool is this?</option>
	<option>awesome</option>
	<option>neat</option>
</select>
```

--------------------------------

### Initialize Tom Select with dropdown_input plugin

Source: https://tom-select.js.org/plugins/dropdown-input

JavaScript initialization for the dropdown_input plugin. The plugin adds a search input to the dropdown. No additional configuration settings are required.

```javascript
new TomSelect('#ex-dropdown-input',{
	plugins: ['dropdown_input'],
});
```

--------------------------------

### Unique Words - HTML

Source: https://tom-select.js.org/examples/create-filter

HTML markup for the unique words example. Includes a select element with id 'select-words-unique'.

```html
<select id="select-words-unique" multiple placeholder="Enter unique words (case-insensitive)..."></select>
```

--------------------------------

### enable()

Source: https://tom-select.js.org/docs/api

Enables the control so that it can respond to focus and user input.

```APIDOC
## enable()

### Description
Enables the control so that it can respond to focus and user input.

### Method
enable

### Parameters
None

### Returns
None
```

--------------------------------

### createItem(value, [callback])

Source: https://tom-select.js.org/docs/api

Invokes the create 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.

```APIDOC
## createItem(value, [callback])

### Description
Invokes the `create` 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 `createItem( value, [triggerDropdown], and [callback])`.

### Method
createItem

### Parameters
- **value** (string) - Required - The user input value for the new item.
- **callback** (function) - Optional - Callback function invoked after the item is created.

```

--------------------------------

### Create with callback function

Source: https://tom-select.js.org/docs

Allows the user to create new items using a function that takes the input text and a callback to invoke with the new option.

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

--------------------------------

### Regex Filter - HTML

Source: https://tom-select.js.org/examples/create-filter

HTML markup for the regex filter example. Includes a select element with id 'select-words-regex' and an input for the pattern.

```html
<select id="select-words-regex" multiple placeholder="Enter a word matching the pattern..."></select>
<div class="control-group form-inline">
	<label for="regex" class="me-2">Pattern</label>
	<input type="text" id="regex" value="^a+$" class="form-control">
</div>
```

--------------------------------

### Require plugins directly with tom-select/base

Source: https://tom-select.js.org/docs/plugins

Use require() to load plugins directly if your build tool supports it, then define them with TomSelect.define.

```javascript
import TomSelect from 'tom-select/base';

TomSelect.define('remove_button', require('tom-select/plugins/remove_button.js'));
TomSelect.define('dropdown_header', require('tom-select/plugins/dropdown_header.js'));
```

--------------------------------

### Minimum Length - HTML

Source: https://tom-select.js.org/examples/create-filter

HTML markup for the minimum length example. Includes a select element with id 'select-words-length' and an input for the minimum length.

```html
<select id="select-words-length" multiple placeholder="Enter a word longer than the minimum number of characters..."></select>
<div class="control-group form-inline">
	<label for="length" class="me-2">Minimum length</label>
	<input id="length" value="2" class="form-control" />
</div>
```

--------------------------------

### focus()

Source: https://tom-select.js.org/docs/api

Brings the control into focus.

```APIDOC
## focus()

### Description
Brings the control into focus.

### Method
focus

### Parameters
None

### Returns
None
```

--------------------------------

### Initialize TomSelect with allowEmptyOption

Source: https://tom-select.js.org/examples

Initializes Tom Select on a select that allows an empty option. The `allowEmptyOption: true` option permits selecting the empty value, and `create: true` allows creating new options.

```JavaScript
new TomSelect("#select-beast-empty",{
	allowEmptyOption: true,
	create: true
});
```

```HTML
<select id="select-beast-empty" data-placeholder="Select a person..."  autocomplete="off">
				<option value="">None</option>
				<option value="4">Thomas Edison</option>
				<option value="1">Nikola</option>
				<option value="3">Nikola Tesla</option>
				<option value="5">Arnold Schwarzenegger</option>
			</select>
```

--------------------------------

### load(query)

Source: https://tom-select.js.org/docs/api

Initiates loading options from your remote data provider for the given query string. See the load() callback.

```APIDOC
## load(query)

### Description
Initiates loading options from your remote data provider for the given query string. See the load() callback.

### Method
load

### Parameters
- **query** (string) - Required - The query string to send to the remote data provider.

### Returns
None
```

--------------------------------

### searchField: Disable client-side filtering

Source: https://tom-select.js.org/docs

Set searchField to an empty array to completely disable client-side filtering, e.g., when getting search results from an external source.

```javascript
searchField: []

```

--------------------------------

### JavaScript: Initialize Tom Select with restore_on_backspace plugin

Source: https://tom-select.js.org/plugins/restore-on-backspace

Initializes a Tom Select instance on the input with id 'input-tags6', enabling the 'restore_on_backspace' plugin, setting 'persist' to false, and allowing creation of new items.

```javascript
new TomSelect('#input-tags6',{
	plugins: ['restore_on_backspace'],
	persist: false,
	create: true
});
```

--------------------------------

### Enable create with boolean

Source: https://tom-select.js.org/docs

Allows the user to create new items that aren't in the initial list of options. Setting create to true enables this feature.

```javascript
create: true
```

--------------------------------

### optionGroupRegister: Transform optgroup label

Source: https://tom-select.js.org/docs

Custom function to transform and manage non-existent optgroups, e.g., for remote data. The example capitalizes the first letter of the optgroup and uses it as the label.

```javascript
optionGroupRegister: function (optgroup) {}

```

```javascript
optionGroupRegister: function (optgroup) {
        var capitalised = optgroup.charAt(0).toUpperCase() + optgroup.substring(1);
        var group = {
          label: capitalised
        };

        group[this.settings.optgroupValueField] = optgroup;

        return group;
      },

```

--------------------------------

### Initialize Tom Select with input_autogrow plugin

Source: https://tom-select.js.org/plugins/input-autogrow

JavaScript initialization for the input_autogrow plugin on the #ex-input-autogrow select element. The plugin automatically increases the input width as the user types. No additional configuration settings are required.

```javascript
new TomSelect('#ex-input-autogrow',{
	plugins: ['input_autogrow'],
});
```

--------------------------------

### Run functional and unit tests

Source: https://tom-select.js.org/docs/contribute

Ensure all tests pass by running the test suite.

```bash
$ npm test
```

--------------------------------

### Create Tom Select instance and add option/item

Source: https://tom-select.js.org/docs/api

Creates a new Tom Select instance on an element with ID 'select', then adds an option and selects it.

```javascript
var control = new TomSelect('#select');
control.addOption({value:'test'});
control.addItem('test');
```

--------------------------------

### Update placeholder after initialization

Source: https://tom-select.js.org/docs

Shows how to update the placeholder setting after initialization by calling inputState().

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

--------------------------------

### Create with function returning value

Source: https://tom-select.js.org/docs

Allows the user to create new items using a function that takes the input text and returns an option object.

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

--------------------------------

### Basic usage with HTML and JavaScript

Source: https://tom-select.js.org/

Initialize Tom Select on an input element with default settings. Requires including the CSS and JavaScript files, then creating a new TomSelect instance.

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

--------------------------------

### new TomSelect(input_element, settings)

Source: https://tom-select.js.org/docs/api

Creates a new Tom Select instance on the given input element. The input element can be an Input Element or Select Element, and CSS selectors matching multiple elements will only create an instance on the first match.

```APIDOC
## new TomSelect(input_element, settings)

### Description
Creates a new Tom Select instance on the given input element. The input element can be an Input Element or Select Element, and CSS selectors matching multiple elements will only create an instance on the first match.

### Method
Constructor

### Parameters
- **input_element** (NodeDefinition) - Required - An Input Element or Select Element.
- **settings** (Object) - Required - Configuration settings for the Tom Select instance.

### Example
```javascript
var control = new TomSelect('#select');
```
```

--------------------------------

### Initialize Tom Select with checkbox_options plugin

Source: https://tom-select.js.org/plugins/checkbox-options

Creates a new Tom Select instance on the #ex-checkbox-options select element, enabling the checkbox_options plugin with custom checked and unchecked CSS classes.

```JavaScript
new TomSelect('#ex-checkbox-options',{
	plugins: {
		'checkbox_options': {
			'checkedClassNames':   ['ts-checked'],
			'uncheckedClassNames': ['ts-unchecked'],
		}
	},
});
```

--------------------------------

### Initialize Tom Select with no_backspace_delete

Source: https://tom-select.js.org/plugins/no-backspace-delete

Initializes the Tom Select instance with the no_backspace_delete and remove_button plugins enabled.

```javascript
new TomSelect('#disable-backspace',{
	plugins: ['no_backspace_delete','remove_button',],
	persist: false,
	create: true,
	controlInput: '#input-disable-control',
	dropdownParent: '#example-wrapper',
});
```

--------------------------------

### Basic HTML select with multiple selection and placeholder

Source: https://tom-select.js.org/examples

Use this HTML select as the base for Tom Select initialization. It includes a placeholder, multiple selection, and autocomplete off. Two options (California and Wyoming) are pre-selected.

```html
<select id="select-state" name="state[]" multiple placeholder="Select a state..." autocomplete="off">
			<option value="">Select a state...</option>
			<option value="AL">Alabama</option>
			<option value="AK">Alaska</option>
			<option value="AZ">Arizona</option>
			<option value="AR">Arkansas</option>
			<option value="CA" selected>California</option>
			<option value="CO">Colorado</option>
			<option value="CT">Connecticut</option>
			<option value="DE">Delaware</option>
			<option value="DC">District of Columbia</option>
			<option value="FL">Florida</option>
			<option value="GA">Georgia</option>
			<option value="HI">Hawaii</option>
			<option value="ID">Idaho</option>
			<option value="IL">Illinois</option>
			<option value="IN">Indiana</option>
			<option value="IA">Iowa</option>
			<option value="KS">Kansas</option>
			<option value="KY">Kentucky</option>
			<option value="LA">Louisiana</option>
			<option value="ME">Maine</option>
			<option value="MD">Maryland</option>
			<option value="MA">Massachusetts</option>
			<option value="MI">Michigan</option>
			<option value="MN">Minnesota</option>
			<option value="MS">Mississippi</option>
			<option value="MO">Missouri</option>
			<option value="MT">Montana</option>
			<option value="NE">Nebraska</option>
			<option value="NV">Nevada</option>
			<option value="NH">New Hampshire</option>
			<option value="NJ">New Jersey</option>
			<option value="NM">New Mexico</option>
			<option value="NY">New York</option>
			<option value="NC">North Carolina</option>
			<option value="ND">North Dakota</option>
			<option value="OH">Ohio</option>
			<option value="OK">Oklahoma</option>
			<option value="OR">Oregon</option>
			<option value="PA">Pennsylvania</option>
			<option value="RI">Rhode Island</option>
			<option value="SC">South Carolina</option>
			<option value="SD">South Dakota</option>
			<option value="TN">Tennessee</option>
			<option value="TX">Texas</option>
			<option value="UT">Utah</option>
			<option value="VT">Vermont</option>
			<option value="VA">Virginia</option>
			<option value="WA">Washington</option>
			<option value="WV">West Virginia</option>
			<option value="WI">Wisconsin</option>
			<option value="WY" selected>Wyoming</option>
		</select>
```

--------------------------------

### Include via jsDelivr CDN

Source: https://tom-select.js.org/

Add Tom Select to a project by including the CSS and JavaScript files from jsDelivr.

```html
<link href="https://cdn.jsdelivr.net/npm/tom-select@2.6.2/dist/css/tom-select.css" rel="stylesheet">
<script src="https://cdn.jsdelivr.net/npm/tom-select@2.6.2/dist/js/tom-select.complete.min.js"></script>
```

--------------------------------

### Initialize Tom Select with maxItems: 3

Source: https://tom-select.js.org/examples

Initializes Tom Select on the #select-state element, limiting the user to selecting up to three items. The HTML select must have the id 'select-state' and include the state options as shown.

```HTML
<select id="select-state" name="state[]" multiple placeholder="Select a state..." autocomplete="off"> <option value="">Select a state...</option> <option value="AL">Alabama</option> <option value="AK">Alaska</option> <option value="AZ">Arizona</option> <option value="AR">Arkansas</option> <option value="CA" selected>California</option> <option value="CO">Colorado</option> <option value="CT">Connecticut</option> <option value="DE">Delaware</option> <option value="DC">District of Columbia</option> <option value="FL">Florida</option> <option value="GA">Georgia</option> <option value="HI">Hawaii</option> <option value="ID">Idaho</option> <option value="IL">Illinois</option> <option value="IN">Indiana</option> <option value="IA">Iowa</option> <option value="KS">Kansas</option> <option value="KY">Kentucky</option> <option value="LA">Louisiana</option> <option value="ME">Maine</option> <option value="MD">Maryland</option> <option value="MA">Massachusetts</option> <option value="MI">Michigan</option> <option value="MN">Minnesota</option> <option value="MS">Mississippi</option> <option value="MO">Missouri</option> <option value="MT">Montana</option> <option value="NE">Nebraska</option> <option value="NV">Nevada</option> <option value="NH">New Hampshire</option> <option value="NJ">New Jersey</option> <option value="NM">New Mexico</option> <option value="NY">New York</option> <option value="NC">North Carolina</option> <option value="ND">North Dakota</option> <option value="OH">Ohio</option> <option value="OK">Oklahoma</option> <option value="OR">Oregon</option> <option value="PA">Pennsylvania</option> <option value="RI">Rhode Island</option> <option value="SC">South Carolina</option> <option value="SD">South Dakota</option> <option value="TN">Tennessee</option> <option value="TX">Texas</option> <option value="UT">Utah</option> <option value="VT">Vermont</option> <option value="VA">Virginia</option> <option value="WA">Washington</option> <option value="WV">West Virginia</option> <option value="WI">Wisconsin</option> <option value="WY" selected>Wyoming</option> </select>
```

```JavaScript
new TomSelect("#select-state",{
	maxItems: 3
});
```

--------------------------------

### addOptions(data[], user_created=false)

Source: https://tom-select.js.org/docs/api

Adds an array of options to the control.

```APIDOC
## addOptions(data[], user_created=false)

### Description
Adds an array of options to the control.

### Method
Option Method

### Parameters
- **data[]** (Array) - Required - An array of option data objects.
- **user_created** (Boolean) - Optional - Default: false. Indicates if the options were created by the user.
```

--------------------------------

### Virtual Scroll with Reddit Search (JavaScript)

Source: https://tom-select.js.org/plugins/virtual_scroll

Initializes Tom Select with the virtual_scroll plugin, fetching remote data from Reddit's search API. The firstUrl method provides the initial URL, load fetches data and calls setNextUrl for pagination, and render.loading_more displays a loading message. Requires the virtual_scroll plugin and maxOptions set to 200.

```javascript
new TomSelect('#reddit-search',{
	valueField: 'permalink',
	labelField: 'title',
	searchField: ['title'],
	plugins:['virtual_scroll'],
	maxOptions: 200,

	// fetch remote data
	firstUrl: function(query){
		return 'https://api.reddit.com/search?q=' + encodeURIComponent(query);
	},
	load: function(query, callback) {

		// retrieve the appropriate url
		const url = this.getUrl(query);

		fetch(url)
			.then(response => response.json())
			.then(json => {

				// prepare the next url that will be loaded when the dropdown is scrolled to the bottom
				// important! should set before invoking callback()
				if( json.data.after ){
					const next_url = 'https://api.reddit.com/search?q=' + encodeURIComponent(query)+'&after='+json.data.after;
					this.setNextUrl(query, next_url);
				}

				// add data to the results
				let data = json.data.children.map(row => row.data);
				callback(data);

			}).catch((e)=>{
				callback();
			});

	},
	render: {
		loading_more: function(data, escape) {
			return `<div class="loading-more-results py-2 d-flex align-items-center"><div class="spinner"></div> Loading more results from reddit </div>`;
		}
	},

});
```

--------------------------------

### Initialize Tom Select with drag_drop plugin

Source: https://tom-select.js.org/plugins/drag-drop

Creates a Tom Select instance on the input with id 'input-sortable', enabling the drag_drop plugin. The 'persist' option is set to false and 'create' is true, allowing new items to be added.

```JavaScript
new TomSelect('#input-sortable',{
	plugins: ['drag_drop'],
	persist: false,
	create: true
});
```

--------------------------------

### Initialize Tom Select with option groups

Source: https://tom-select.js.org/examples/optgroups

Configures a Tom Select instance on the '#select-animal' element. Options are assigned to groups via the 'class' field, and optgroups are defined with labels and scientific names. The render.optgroup_header function customizes the group header to display the label and scientific name.

```javascript
new TomSelect('#select-animal',{
	options: [
		{class: 'mammal', value: "dog", name: "Dog" },
		{class: 'mammal', value: "cat", name: "Cat" },
		{class: 'mammal', value: "horse", name: "Horse" },
		{class: 'mammal', value: "kangaroo", name: "Kangaroo" },
		{class: 'bird', value: 'duck', name: 'Duck'},
		{class: 'bird', value: 'chicken', name: 'Chicken'},
		{class: 'bird', value: 'ostrich', name: 'Ostrich'},
		{class: 'bird', value: 'seagull', name: 'Seagull'},
		{class: 'reptile', value: 'snake', name: 'Snake'},
		{class: 'reptile', value: 'lizard', name: 'Lizard'},
		{class: 'reptile', value: 'alligator', name: 'Alligator'},
		{class: 'reptile', value: 'turtle', name: 'Turtle'}
	],
	optgroups: [
		{value: 'mammal', label: 'Mammal', label_scientific: 'Mammalia'},
		{value: 'bird', label: 'Bird', label_scientific: 'Aves'},
		{value: 'reptile', label: 'Reptile', label_scientific: 'Reptilia'}
	],
	optgroupField: 'class',
	labelField: 'name',
	searchField: ['name'],
	render: {
		optgroup_header: function(data, escape) {
			return '<div class="optgroup-header">' + escape(data.label) + ' <span class="scientific">' + escape(data.label_scientific) + '</span></div>';
		}
	}
});
```

```html
<select id="select-animal" class="demo-animals" placeholder="Select animal..."></select>
```

```css
.demo-animals .scientific {
	font-weight: normal;
	opacity: 0.3;
	margin: 0 0 0 2px;
}
.demo-animals .scientific::before {
	content: '(';
}
.demo-animals .scientific::after {
	content: ')';
}
```

--------------------------------

### on(event, handler)

Source: https://tom-select.js.org/docs/api

Adds an event listener.

```APIDOC
## on(event, handler)

### Description
Adds an event listener.

### Method
on

### Parameters
- **event** (string) - Required - The event name.
- **handler** (function) - Required - The event handler function.

```

--------------------------------

### Multiple instances using a .class selector

Source: https://tom-select.js.org/docs

Initialize Tom Select on multiple input elements using a class selector. Iterates over all elements with the class and creates a new TomSelect instance for each. Requires the same CSS and JS includes.

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

--------------------------------

### Initialize Tom Select with no_active_items plugin

Source: https://tom-select.js.org/plugins/no-active-items

Creates a Tom Select instance on the input with id 'ex-no-active-items', enabling the 'no_active_items' plugin. The 'persist' option is set to false and 'create' is true, allowing users to create new items but not select existing ones.

```JavaScript
new TomSelect('#ex-no-active-items',{
	plugins: ['no_active_items'],
	persist: false,
	create: true,
});
```

--------------------------------

### Tom Select constructor

Source: https://tom-select.js.org/docs/api

Creates a new Tom Select instance with the given input element and settings.

```javascript
new TomSelect(input_element,settings);
```

--------------------------------

### Set initial selected items

Source: https://tom-select.js.org/docs

Specifies the initial selected values. By default, this is populated from the original input element.

```javascript
items: ["opt1"]
```
Tokens:
Raw