README

Contents of this file

• Introduction
• Requirements
• Recommended modules
• Installation
• Configuration
• Form API usage
• Field widget usage
• Library files and licensing
• Troubleshooting
• Development
• Maintainers

Introduction

The Tom Select module provides an opt-in Drupal integration for Tom Select, a JavaScript select enhancement library.

The module is intentionally narrow in scope. It does not replace every select element on the site automatically. Site builders and developers choose where Tom Select is enabled.

The module provides:

• a Drupal library definition for a locally installed Tom Select library;
• a Drupal behavior that initializes Tom Select on opt-in select elements;
• a Form API integration using #tom_select;
• a configurable field widget named Tom Select for supported option fields.

This module does not provide a new field type. Existing Drupal field storage and field data remain unchanged. The module only changes the form widget and browser interaction for supported select elements.

Requirements

This module requires:

• Drupal ^10.3 or ^11;
• PHP >=8.2;
• Tom Select installed as a local frontend library.

The expected local library files are:

web/libraries/tom-select/dist/css/tom-select.default.min.css
web/libraries/tom-select/dist/js/tom-select.complete.min.js

Recommended modules

No additional Drupal modules are required.

The module can be used with Drupal core field widgets and Form API select elements. It is also suitable for custom modules that build their own forms.

Installation

Install the Drupal module as usual for a contributed or custom module.

If the module is installed through Composer:

composer require db-web-solutions/drupal-tom-select
drush en tom_select
drush cr

If the module is installed manually, place it in a Drupal module directory such as:

web/modules/contrib/tom_select

or:

web/modules/custom/tom_select

Then enable it:

drush en tom_select
drush cr

Installing Tom Select

Download the Tom Select distribution from the upstream project and place the compiled files in Drupal's libraries directory:

web/libraries/tom-select/
├── dist/
│   ├── css/
│   │   └── tom-select.default.min.css
│   └── js/
│       └── tom-select.complete.min.js
├── LICENSE
└── NOTICE

The library directory should keep the upstream license files. Tom Select is licensed under Apache-2.0.

The Drupal module code is licensed under GPL-2.0-or-later.

Configuration

There is no global configuration page.

Tom Select is enabled per form element or per field widget. This prevents the module from changing unrelated select elements across a site.

Form API usage

Custom forms can opt in by adding #tom_select to a select element:

$form['example'] = [
  '#type' => 'select',
  '#title' => $this->t('Example'),
  '#options' => [
    'one' => $this->t('One'),
    'two' => $this->t('Two'),
  ],
  '#tom_select' => TRUE,
];

Tom Select options can be passed through #tom_select_options:

$form['example'] = [
  '#type' => 'select',
  '#title' => $this->t('Example'),
  '#options' => [
    'one' => $this->t('One'),
    'two' => $this->t('Two'),
  ],
  '#empty_option' => $this->t('- Select -'),
  '#tom_select' => TRUE,
  '#tom_select_options' => [
    'allowEmptyOption' => TRUE,
  ],
];

Multiple select example:

$form['tags'] = [
  '#type' => 'select',
  '#title' => $this->t('Tags'),
  '#multiple' => TRUE,
  '#options' => [
    'summer' => $this->t('Summer'),
    'winter' => $this->t('Winter'),
    'all-season' => $this->t('All season'),
  ],
  '#tom_select' => TRUE,
  '#tom_select_options' => [
    'plugins' => ['remove_button'],
  ],
];

Developers may also call the helper function:

$form['example'] = tom_select_attach($form['example'], [
  'allowEmptyOption' => TRUE,
]);

Field widget usage

For configurable fields:

1. Go to Manage form display for the entity bundle.
2. Select the Tom Select widget for a supported field.
3. Save the form display.
4. Clear Drupal caches if the widget does not appear immediately.

Supported field types:

• Entity reference;
• List text;
• List integer;
• List float.

The field widget reuses Drupal core option handling. It does not change field storage, submitted values, or entity data structure.

Library files and licensing

The module references Tom Select as a local Drupal library:

tom_select/tom-select

The referenced files are root-relative to the Drupal web root:

/libraries/tom-select/dist/css/tom-select.default.min.css
/libraries/tom-select/dist/js/tom-select.complete.min.js

When distributing a project that includes Tom Select files, keep the upstream Tom Select LICENSE and NOTICE files with the library.

Do not remove upstream copyright notices from the compiled library files.

Troubleshooting

Tom Select is not applied to a form element

Check that the element is a select element and that #tom_select is set:

'#tom_select' => TRUE,

Also check that Drupal caches were cleared after enabling the module:

drush cr

Browser console says TomSelect is not defined

The Tom Select JavaScript file is probably missing or installed at a different path.

Verify this file exists:

web/libraries/tom-select/dist/js/tom-select.complete.min.js

Styles are missing

Verify this file exists:

web/libraries/tom-select/dist/css/tom-select.default.min.css

The field widget does not appear

Confirm the field type is supported. The widget is available for entity reference and list fields.

Development

Install development dependencies:

composer install

Run PHPCS:

composer phpcs

Run PHPStan:

composer phpstan

PHPStan is configured at level 9.

Auto-fix PHPCS issues where possible:

composer phpcbf

Maintainers

Current maintainers:

• DB Web Solutions