PHPackages                             db-web-solutions/drupal-tom-select - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. db-web-solutions/drupal-tom-select

ActiveDrupal-module

db-web-solutions/drupal-tom-select
==================================

Drupal integration for Tom Select.

1.0.0(today)01↑2900%GPL-2.0-or-laterPHPPHP >=8.2

Since Jun 13Pushed todayCompare

[ Source](https://github.com/db-web-solutions/drupal-tom-select)[ Packagist](https://packagist.org/packages/db-web-solutions/drupal-tom-select)[ RSS](/packages/db-web-solutions-drupal-tom-select/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (5)Versions (2)Used By (0)

Tom Select
==========

[](#tom-select)

Contents of this file
---------------------

[](#contents-of-this-file)

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

Introduction
------------

[](#introduction)

The Tom Select module provides an opt-in Drupal integration for [Tom Select](https://tom-select.js.org/), 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
------------

[](#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
-------------------

[](#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
------------

[](#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
---------------------

[](#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
-------------

[](#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
--------------

[](#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
------------------

[](#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
---------------------------

[](#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
---------------

[](#troubleshooting)

### Tom Select is not applied to a form element

[](#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

[](#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

[](#styles-are-missing)

Verify this file exists:

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

```

### The field widget does not appear

[](#the-field-widget-does-not-appear)

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

Development
-----------

[](#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
-----------

[](#maintainers)

Current maintainers:

- DB Web Solutions

###  Health Score

39

—

LowBetter than 85% of packages

Maintenance100

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity45

Maturing project, gaining track record

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

0d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/36db7daa30d5e194dbc01e003fa45f4c0404c7045d1602b76cd11c0ae58265dd?d=identicon)[dmitrijs.brujevs](/maintainers/dmitrijs.brujevs)

###  Code Quality

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/db-web-solutions-drupal-tom-select/health.svg)

```
[![Health](https://phpackages.com/badges/db-web-solutions-drupal-tom-select/health.svg)](https://phpackages.com/packages/db-web-solutions-drupal-tom-select)
```

###  Alternatives

[drupal/core-recommended

Locked core dependencies; require this project INSTEAD OF drupal/core.

6941.5M396](/packages/drupal-core-recommended)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)