Tom Select

https://github.com/orchidjs/tom-select
Admin
Tom Select is a lightweight, framework-agnostic <select> UI control with autocomplete and keyboard...
Tokens:43,080
Snippets:261
Trust Score:8
License:Apache-2.0
Update:1 week ago
Show doc for...
Tokens:
Raw
### Start local development server

Source: https://github.com/orchidjs/tom-select/blob/master/doc_src/pages/docs/contribute.md

Run this command to start a web server that lets you preview the local documentation site at http://localhost:8000/.

```shell
$ npm start
```

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

### Hook after setup method

Source: https://github.com/orchidjs/tom-select/blob/master/doc_src/pages/docs/plugins.md

Execute code after the setup() method using the 'after' hook. This is useful for adding event listeners or additional setup.

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

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

### Install via npm

Source: https://github.com/orchidjs/tom-select/blob/master/README.md

Install the package using the npm CLI.

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

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

### Add DOM event listener after setup

Source: https://github.com/orchidjs/tom-select/blob/master/doc_src/pages/docs/plugins.md

Add a DOM event listener to the control after setup. The example adds a click listener that alerts when the control is clicked.

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

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

### Initialize Tom Select

Source: https://github.com/orchidjs/tom-select/blob/master/README.md

Basic HTML setup including the input element, stylesheet, and script initialization.

```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 config = {};
new TomSelect('#tom-select-it',config);
</script>
```

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

### Install via jsDelivr CDN

Source: https://github.com/orchidjs/tom-select/blob/master/README.md

Include the Tom Select CSS and JS files directly from the jsDelivr CDN.

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

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

### Override setup method with 'instead' hook

Source: https://github.com/orchidjs/tom-select/blob/master/doc_src/pages/docs/plugins.md

Override the setup() method using the 'instead' hook. If the original method returns a value, the overridden function must return it as well.

```js
// 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);
	});
};
```

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

### optionGroupRegister example with capitalization

Source: https://github.com/orchidjs/tom-select/blob/master/doc_src/pages/docs/index.md

Example implementation of optionGroupRegister that capitalizes the first letter of the optgroup name and uses it as the label. The group is assigned the optgroup value field from settings.

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

        group[this.settings.optgroupValueField] = optgroup;

        return group;
      },
```

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

### Customize Tom Select render templates

Source: https://github.com/orchidjs/tom-select/blob/master/doc_src/pages/docs/index.md

Defines custom render functions for all Tom Select UI components. The escape function must be used to prevent XSS vulnerabilities. The example shows how to return HTML strings or DOM elements for each render setting.

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

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

### optionGroupRegister setting signature

Source: https://github.com/orchidjs/tom-select/blob/master/doc_src/pages/docs/index.md

Placeholder signature for the optionGroupRegister setting. It is a function that transforms and manages non-existent optgroups, for example when using remote data.

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

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

### Build from source

Source: https://github.com/orchidjs/tom-select/blob/master/README.md

Command to build the project from source after cloning the repository.

```bash
npm run build
```

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

### Create TomSelect and update settings

Source: https://github.com/orchidjs/tom-select/blob/master/doc_src/pages/docs/index.md

Shows how to create a TomSelect instance and then modify its settings and refresh the input state. Use this when you need to change a setting after initialization and apply it immediately.

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

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

### Build custom Tom Select bundle with plugins

Source: https://github.com/orchidjs/tom-select/blob/master/doc_src/pages/docs/plugins.md

Build a custom bundle with selected plugins using NPM. The --plugins flag accepts a comma-separated list of plugin names.

```shell
# 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
```

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

### Initialize Tom Select with plugins array

Source: https://github.com/orchidjs/tom-select/blob/master/doc_src/pages/docs/plugins.md

Initialize Tom Select with a list of plugin names. The plugins array must contain the names of plugins that have been defined via TomSelect.define or included in the bundle.

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

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

### Initialize Tom Select with plugin options object

Source: https://github.com/orchidjs/tom-select/blob/master/doc_src/pages/docs/plugins.md

Initialize Tom Select with plugin options. Each plugin name maps to an options object that is passed to the plugin's initialization function.

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

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

### Compile TypeScript and SCSS components to /buid directory

Source: https://github.com/orchidjs/tom-select/blob/master/doc_src/pages/docs/contribute.md

Run this command to build from source. It compiles the TypeScript and SCSS files in /src to JavaScript and CSS in the /buid directory.

```shell
$ npm run build
```

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

### Run functional and unit tests

Source: https://github.com/orchidjs/tom-select/blob/master/doc_src/pages/docs/contribute.md

Run this command to execute the project's test suite and ensure your changes do not break existing functionality.

```shell
$ npm test
```

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

### Initialize Tomcat instances on all .class elements

Source: https://github.com/orchidjs/tom-select/blob/master/doc_src/pages/docs/index.md

This code creates a TomSelect instance for every input element with the class 'select'. Use a loop with CSS selector to apply to multiple inputs at once.

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

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

### Import and define plugins with require

Source: https://github.com/orchidjs/tom-select/blob/master/doc_src/pages/docs/plugins.md

Use require() to load plugins directly if your build tool supports it. This is an alternative to ES module imports.

```js
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'));
```

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

### Import and define plugins with ES modules

Source: https://github.com/orchidjs/tom-select/blob/master/doc_src/pages/docs/plugins.md

Import plugins individually and register them with TomSelect.define. Use this when using tom-select.base.js to load plugins separately.

```js
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 options and console logging

Source: https://github.com/orchidjs/tom-select/blob/master/test/html/bootstrap5.html

Initializes all elements with class 'ts' as Tom Select instances, setting persist to false, createOnBlur to true, create to false, and logging to console when initialized.

```javascript
document.querySelectorAll('.ts').forEach(function (select) {
  new TomSelect(select, {
    persist: false,
    createOnBlur: true,
    create: false,
    onInitialize: () => console.log('TomSelect is now initialized'),
  });
});
```

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

### options array configuration

Source: https://github.com/orchidjs/tom-select/blob/master/doc_src/pages/docs/index.md

Sets the initial list of selectable options. By default this is populated from the original <input> or <select> element. The default value is an empty array.

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

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

### create setting (boolean or function)

Source: https://github.com/orchidjs/tom-select/blob/master/doc_src/pages/docs/index.md

Controls whether the user can create new items not in the initial list. Can be true, false, or a function. The function form can return an option object or use a callback. The default is false.

```js
create: true
```

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

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

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

### TomSelect onInitialize callback

Source: https://github.com/orchidjs/tom-select/blob/master/doc_src/pages/docs/index.md

Shows how to pass an onInitialize callback to the TomSelect constructor. The callback 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.
	}
});
```

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

### JavaScript: Initialize Tom Select with options

Source: https://github.com/orchidjs/tom-select/blob/master/test/html/tab.html

Initializes a Tom Select instance on an input with id 'input-tags'. Options include create, duplicates, and commented-out persist, createOnBlur, and hidePlaceholder. The commented options are not active.

```javascript
var ts = new TomSelect("#input-tags",{
  //persist: false,
  //createOnBlur: true,
  create: true,
  duplicates: true,
  //hidePlaceholder: true,
});
```

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

### Initialize Tom Select with create options

Source: https://github.com/orchidjs/tom-select/blob/master/test/html/bootstrap-dropdown.html

Creates a Tom Select instance on the input with ID 'input-tags', enabling tag creation on blur and allowing new items to be created. The commented code shows how to prevent the dropdown menu from closing on click.

```javascript
var ts = new TomSelect("#input-tags",{
  persist: false,
  createOnBlur: true,
  create: true
});
//document.querySelector('.dropdown-menu').addEventListener('click',(e)=>{
//  e.preventDefault();
//  e.stopPropagation();
//});
```

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

### Initialize single Tom Select instance by ID selector

Source: https://github.com/orchidjs/tom-select/blob/master/doc_src/pages/docs/index.md

Uses an input element with id 'select' and creates one TomSelect instance. Requires including the stylesheet and script before the script code.

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

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

### Available Events

Source: https://github.com/orchidjs/tom-select/blob/master/doc_src/pages/docs/events.md

List of events that can be listened to on a Tom Select instance, with their parameters and descriptions.

```APIDOC
## Events

### initialize
- **Params**: none
- **Description**: Invoked once the control is completely initialized.

### change
- **Params**: `value`
- **Description**: Invoked when the value of the control changes.

### focus
- **Params**: none
- **Description**: Invoked when the control gains focus.

### blur
- **Params**: none
- **Description**: Invoked when the control loses focus.

### item_add
- **Params**: `value`, `item`
- **Description**: Invoked when an item is added (i.e., when an option is selected).

### item_remove
- **Params**: `value`, `$item`
- **Description**: Invoked when an item is deselected.

### item_select
- **Params**: `item`
- **Description**: Invoked when an item is selected.

### clear
- **Params**: none
- **Description**: Invoked when the control is manually cleared via the clear() method.

### option_add
- **Params**: `value`, `data`
- **Description**: Invoked when a new option is added to the available options list.

### option_remove
- **Params**: `value`
- **Description**: Invoked when an option is removed from the available options.

### option_clear
- **Params**: none
- **Description**: Invoked when all options are removed from the control.

### optgroup_add
- **Params**: `id`, `data`
- **Description**: Invoked when a new option group is added to the available options list.

### optgroup_remove
- **Params**: `id`
- **Description**: Invoked when an option group is removed.

### optgroup_clear
- **Params**: none
- **Description**: Invoked when all option groups are removed.

### dropdown_open
- **Params**: `dropdown`
- **Description**: Invoked when the dropdown opens.

### dropdown_close
- **Params**: `dropdown`
- **Description**: Invoked when the dropdown closes.

### type
- **Params**: `str`
- **Description**: Invoked when the user types while filtering options.

### load
- **Params**: `data`
- **Description**: Invoked when new options have been loaded and added to the control (via the `load` option or `load` API method).

### destroy
- **Params**: none
- **Description**: Invoked right before the control is destroyed.
```

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

### items array configuration

Source: https://github.com/orchidjs/tom-select/blob/master/doc_src/pages/docs/index.md

Sets the initial selected values. By default this is populated from the original input element. The default value is an empty array.

```js
items: ["opt1"]
```

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

### Event Emitter Methods

Source: https://github.com/orchidjs/tom-select/blob/master/doc_src/pages/docs/events.md

Methods to subscribe and unsubscribe to events on a Tom Select instance.

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

### Description
Subscribes a handler function to the specified event.

### Method
on

### Parameters
- **event_name** (string) - Required - The name of the event to listen for.
- **handler** (function) - Required - The function to call when the event is triggered.

### Example
```js
var handler = function() { /* ... */ };
var select = new TomSelect('#input-id');
select.on('event_name', handler);
```

## off(event_name, handler?)

### Description
Unsubscribes a handler from the specified event. If no handler is provided, all handlers for that event are removed.

### Method
off

### Parameters
- **event_name** (string) - Required - The name of the event to unsubscribe from.
- **handler** (function) - Optional - The specific handler to remove. If omitted, all handlers for the event are removed.

### Example
```js
select.off('event_name');
select.off('event_name', handler);
```
```

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

### Event emitter usage

Source: https://github.com/orchidjs/tom-select/blob/master/doc_src/pages/docs/events.md

Shows how to attach and detach event handlers using the on and off methods. The handler is a function that receives event-specific parameters.

```javascript
var handler = function() { /* ... */ };
var select = new TomSelect('#input-id');
select.on('event_name', handler);
select.off('event_name');
select.off('event_name', handler);
```

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

### Initialize multiple Tom Select with clearAfterSelect

Source: https://github.com/orchidjs/tom-select/blob/master/test/html/bootstrap5.html

Initializes the element with id 'ts-multiple' as Tom Select, enabling the clearAfterSelect option for multiple selection.

```javascript
new TomSelect('#ts-multiple', {
  clearAfterSelect: true,
});
```

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

### Tom Select with virtual_scroll plugin and remote Reddit data

Source: https://github.com/orchidjs/tom-select/blob/master/test/html/virtual-scroll.html

Use this snippet to create a Tom Select instance with the virtual_scroll plugin, fetching remote data from Reddit's search API. It sets a custom firstUrl and load function that uses fetch to retrieve results, prepares the next URL for pagination via setNextUrl, and renders options with a custom template. The class TestSelect overrides close() to prevent closing the dropdown, and maxOptions is set to 200.

```javascript
class TestSelect extends TomSelect{ close(){} } new TestSelect('#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) { 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 // !! set before invoking callback() 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: { option: function(data, escape) { return `<div>${ escape(data.$order) } - ${ escape(data.title) }</div>`; } }, });
```

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

### searchField with array of property names

Source: https://github.com/orchidjs/tom-select/blob/master/doc_src/pages/docs/index.md

Sets the search fields to analyze when filtering options.

```javascript
searchField: ['text','text2']
```

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

### Add plugin dependency with this.require

Source: https://github.com/orchidjs/tom-select/blob/master/doc_src/pages/docs/plugins.md

Add a dependency on another plugin using this.require(). The required plugin must be defined before this plugin is initialized.

```js
// in src/plugins/plugin_name/plugin.js
export default function(plugin_options) {
	this.require('another_plugin');
};
```

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

### searchField with weighted fields

Source: https://github.com/orchidjs/tom-select/blob/master/doc_src/pages/docs/index.md

Assigns weights to each search field to improve search results.

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

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

### Plugin boilerplate

Source: https://github.com/orchidjs/tom-select/blob/master/doc_src/pages/docs/plugins.md

Boilerplate for a Tom Select plugin. The exported function receives plugin options and is called with the TomSelect instance as this.

```js
// in src/plugins/plugin_name/plugin.js
export default function(plugin_options) {
	// plugin_options: plugin-specific options
	// this: TomSelect instance
};
```

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

### CSS: Hide placeholder when items exist

Source: https://github.com/orchidjs/tom-select/blob/master/test/html/tab.html

Use this CSS rule to make the placeholder text transparent when the control has items. It targets the input inside .ts-control when the parent has the .has-items class.

```css
.has-items .ts-control > input::placeholder { color:transparent; }
```

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

### searchField empty to disable client-side filtering

Source: https://github.com/orchidjs/tom-select/blob/master/doc_src/pages/docs/index.md

Completely disables client-side filtering, useful when search results come from an external source.

```javascript
searchField: []
```

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

### sortField to disable sorting

Source: https://github.com/orchidjs/tom-select/blob/master/doc_src/pages/docs/index.md

Disables sorting by score and maintains the original order of options by using the $order field first.

```javascript
sortField:[{field:'$order'},{field:'$score'}]
```
Tokens:
Raw