DOCSEARCHbyAlgolia
Submit Docs

Tom Select

website·Indexed 29 days ago

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

A customizable select library featuring a JavaScript API, plugin system, and support for remote data, item creation, and large dataset performance. Documentation includes usage guides, event APIs, and migration paths to v2.

Tokens
17.3K
Snippets
95
Records
120
Agent score
65%

What's inside Tom Select

  1. Overview of Tom Select

    Tom Select is a dynamic, framework-agnostic, and lightweight (~16kb gzipped) <select> UI control. It provides autocomplete and native-feeling keyboard navigation, making it suitable for tagging, contact lists, and country selectors. It is a fork of selectize.js, decoupled from jQuery and modernized for better extensibility.

  2. Read JSON data from option attributes

    Use the dataAttr setting to specify which HTML attribute of the <option> element should be read as JSON data about that option.
    new TomSelect('#select-element', {
  dataAttr: 'data-custom-json'
});

  3. Integrate Tom Select with Bootstrap custom validation

    To use Bootstrap's custom validation styles instead of browser defaults, add the novalidate attribute to the <form>. In the form's submit listener, add the was-validated class to the form to trigger Bootstrap's visual feedback. You can also manually toggle the is-invalid class on the Tom Select wrapper to highlight errors.
    <form id="bootstrap-form" novalidate>
	<select class="form-select" id="select-bootstrap" required placeholder="Select a person..." name="beast">
		<option value="">Select a person...</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>
	<div class="invalid-feedback">
      Please select a person
    </div>
	<div class="py-3">
		<button type="submit" class="btn btn-primary">Submit</button>
	</div>
</form>

<script>
var my_select = new TomSelect('#select-bootstrap');
var form = document.getElementById('bootstrap-form');

form.addEventListener('submit', function (event){
	// add was-validated to display custom colors
	form.classList.add('was-validated');

	if (!form.checkValidity()) {
		event.preventDefault();
		event.stopPropagation();
	}
}, false);
</script>

  4. Include Tom Select plugins in your project

    Tom Select provides different distribution bundles depending on your plugin needs. You can also manually define plugins when using the base build.

  5. Submit a Pull Request to Tom Select

    When contributing bug fixes or new features via pull requests, follow these requirements:

    1. Ensure all existing tests pass by running npm test.
    2. Only modify files in the /src or /doc_src directories. Do not commit changes to the /dist folder, as this is updated automatically after approval.
    3. It is highly recommended to add new tests to support your changes.

  6. Prevent item activation with the No Active Items plugin

    The no_active_items plugin prevents users from activating items (such as already selected options) within a Tom Select instance. By default, users can activate items via clicking, shift+clicking, or using shift+left-arrow; this plugin disables those specific interactions.
    new TomSelect('#ex-no-active-items',{
	plugins: ['no_active_items'],
	persist: false,
	create: true,
});

  7. Add DOM event listeners in a plugin

    Because plugins are initialized before the control is set up, you must use the after hook on the setup method to attach event listeners to DOM elements.
    export default function(plugin_options) {
	this.hook('after', 'setup', function() {
		this.control.addEventListener('click', function(evt) {
			alert('the control was clicked');
		});
	});
};

  8. Display option groups in columns using the optgroup_columns plugin

    The optgroup_columns plugin uses CSS flexbox layouts to display option groups in columns. It also enables keyboard shortcuts, allowing users to navigate between these columns using the left (←) and right (→) arrow keys.
    new TomSelect("#select-car", {
	options: [
		{id: 'avenger', make: 'dodge', model: 'Avenger'},
		{id: 'a3', make: 'audi', model: 'A3'},
		{id: 'avalanche', make: 'chevrolet', model: 'Avalanche'},
		// ... other options
	],
	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
});
    <input type="text" id="select-car" placeholder="Select cars...">

  9. Add a header to a Tom Select dropdown

    Use the dropdown_header plugin to add a title or custom HTML header to the top of the Tom Select dropdown menu. This is configured within the plugins object during initialization.
    new TomSelect('#select-code-language', {
	sortField: 'text',
	hideSelected: false,
	plugins: {
		'dropdown_header': {
			title: 'Language'
		}
	}
});

  10. Install Tom Select via CDN

    The fastest way to add Tom Select to a project is by including the CSS and JS files directly from jsDelivr.
    <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>

  11. Manually define plugins with TomSelect.define

    When using tom-select.base.js, you must register plugins using TomSelect.define(name, plugin_function). This can be done via ES modules or require.
    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);

// Alternatively using require:
TomSelect.define('remove_button', require('tom-select/plugins/remove_button.js'));

  12. Prevent item removal via backspace using the no_backspace_delete plugin

    The no_backspace_delete plugin for Tom Select prevents users from deleting selected items by pressing the backspace key. This is often used in conjunction with the remove_button plugin to ensure items are only removed via a dedicated UI button rather than keyboard shortcuts.
    new TomSelect('#disable-backspace',{
	plugins: ['no_backspace_delete', 'remove_button'],
	persist: false,
	create: true,
	controlInput: '#input-disable-control',
	dropdownParent: '#example-wrapper',
});