README

A Yii2 widget for Tom Select - a dynamic, framework agnostic, and lightweight (~16kb gzipped) <select> UI control with autocomplete and native-feeling keyboard navigation.

Features

• ✅ Bootstrap 5 integration
• ✅ Local vendor files (no CDN dependencies)
• ✅ Full Tom Select API support
• ✅ All plugins included
• ✅ Model and non-model usage
• ✅ AJAX/Remote data loading
• ✅ Custom rendering templates
• ✅ Event handling
• ✅ Multi-select support
• ✅ Tagging/item creation
• ✅ Diacritics support

Requirements

• PHP >= 7.4
• Yii2 >= 2.0.45
• yii2-bootstrap5 >= 2.0.0

Installation

Install via Composer:

composer require errohitsinghal/yii2-tom-select

Quick Start

Basic Select

use errohitsinghal\tomselect\TomSelect;

<?= TomSelect::widget([
    'model' => $model,
    'attribute' => 'category_id',
    'items' => [
        '1' => 'Option 1',
        '2' => 'Option 2',
        '3' => 'Option 3',
    ],
]) ?>

Without Model

<?= TomSelect::widget([
    'name' => 'category',
    'value' => 1,
    'items' => [
        '1' => 'Option 1',
        '2' => 'Option 2',
        '3' => 'Option 3',
    ],
]) ?>

Multi-Select

<?= TomSelect::widget([
    'model' => $model,
    'attribute' => 'tags',
    'items' => $tagList,
    'multiple' => true,
    'plugins' => ['remove_button', 'clear_button'],
]) ?>

Configuration Options

Widget Properties

Available Plugins

Tom Select comes with many built-in plugins:

Usage with ActiveForm

The widget integrates seamlessly with Yii2's ActiveForm. You have two options:

Option 1: Using the Widget Directly

use errohitsinghal\tomselect\TomSelect;
use yii\bootstrap5\ActiveForm;

<?php $form = ActiveForm::begin(); ?>

<?= $form->field($model, 'category_id')->widget(TomSelect::class, [
    'items' => $categories,
    'placeholder' => 'Select a category...',
]) ?>

<?= $form->field($model, 'tags')->widget(TomSelect::class, [
    'items' => $tagList,
    'multiple' => true,
    'create' => true,
    'plugins' => ['remove_button'],
]) ?>

<?php ActiveForm::end(); ?>

Option 2: Using the ActiveField Extension

For a cleaner syntax, use the custom ActiveField class:

use errohitsinghal\tomselect\TomSelect;
use errohitsinghal\tomselect\ActiveField;
use yii\bootstrap5\ActiveForm;

<?php $form = ActiveForm::begin([
    'fieldClass' => ActiveField::class,
]); ?>

// Basic select
<?= $form->field($model, 'category_id')->tomSelect($categories, [
    'placeholder' => 'Select a category...',
]) ?>

// Multi-select with plugins
<?= $form->field($model, 'tags')->tomSelect($tagList, [
    'multiple' => true,
    'plugins' => ['remove_button', 'clear_button'],
]) ?>

// Tagging field (pre-configured)
<?= $form->field($model, 'keywords')->tomSelectTags() ?>

// AJAX loading field
<?= $form->field($model, 'user_id')->tomSelectAjax('/api/users/search', [
    'valueField' => 'id',
    'labelField' => 'name',
    'searchField' => ['name', 'email'],
    'placeholder' => 'Search users...',
]) ?>

<?php ActiveForm::end(); ?>

ActiveField Helper Methods

Complete Form Example

<?php

use errohitsinghal\tomselect\ActiveField;
use yii\bootstrap5\ActiveForm;
use yii\web\JsExpression;

?>

<?php $form = ActiveForm::begin([
    'fieldClass' => ActiveField::class,
]); ?>

<div class="row">
    <div class="col-md-6">
        <?= $form->field($model, 'title')->textInput(['maxlength' => true]) ?>
    </div>
    <div class="col-md-6">
        <?= $form->field($model, 'status')->tomSelect([
            'draft' => 'Draft',
            'published' => 'Published',
            'archived' => 'Archived',
        ]) ?>
    </div>
</div>

<div class="row">
    <div class="col-md-6">
        <?= $form->field($model, 'category_id')->tomSelect($categories, [
            'placeholder' => 'Select category...',
            'allowEmptyOption' => true,
        ]) ?>
    </div>
    <div class="col-md-6">
        <?= $form->field($model, 'tags')->tomSelectTags([
            'placeholder' => 'Add tags...',
        ]) ?>
    </div>
</div>

<div class="row">
    <div class="col-md-6">
        <?= $form->field($model, 'author_id')->tomSelectAjax('/api/users/search', [
            'placeholder' => 'Search author...',
        ]) ?>
    </div>
    <div class="col-md-6">
        <?= $form->field($model, 'related_posts')->tomSelect($posts, [
            'multiple' => true,
            'maxItems' => 5,
            'plugins' => ['remove_button'],
            'placeholder' => 'Select up to 5 related posts...',
        ]) ?>
    </div>
</div>

<div class="form-group">
    <?= \yii\bootstrap5\Html::submitButton('Save', ['class' => 'btn btn-primary']) ?>
</div>

<?php ActiveForm::end(); ?>

Form Validation Styling

Tom Select automatically integrates with Bootstrap 5 validation states. When a field has validation errors, the Tom Select control will display with the appropriate error styling.

// The widget respects Yii2's validation
<?= $form->field($model, 'category_id')->tomSelect($categories) ?>

// Custom error display
<?= $form->field($model, 'category_id', [
    'errorOptions' => ['class' => 'invalid-feedback d-block'],
])->tomSelect($categories) ?>

Usage Examples

With Option Groups

<?= TomSelect::widget([
    'model' => $model,
    'attribute' => 'vehicle',
    'items' => [
        'Cars' => [
            'toyota' => 'Toyota',
            'honda' => 'Honda',
            'ford' => 'Ford',
        ],
        'Motorcycles' => [
            'yamaha' => 'Yamaha',
            'kawasaki' => 'Kawasaki',
        ],
    ],
]) ?>

Tagging (Create New Items)

<?= TomSelect::widget([
    'model' => $model,
    'attribute' => 'tags',
    'type' => TomSelect::TYPE_TEXT,
    'multiple' => true,
    'create' => true,
    'plugins' => ['remove_button'],
    'clientOptions' => [
        'persist' => false,
        'createOnBlur' => true,
    ],
]) ?>

With Plugins and Options

<?= TomSelect::widget([
    'model' => $model,
    'attribute' => 'users',
    'items' => $userList,
    'multiple' => true,
    'plugins' => [
        'remove_button' => [
            'title' => 'Remove this item',
        ],
        'clear_button' => [
            'title' => 'Remove all items',
        ],
        'dropdown_header' => [
            'title' => 'Select Users',
        ],
    ],
]) ?>

AJAX Remote Data Loading

<?= TomSelect::widget([
    'model' => $model,
    'attribute' => 'user_id',
    'placeholder' => 'Search for a user...',
    'clientOptions' => [
        'valueField' => 'id',
        'labelField' => 'name',
        'searchField' => ['name', 'email'],
        'load' => new \yii\web\JsExpression('function(query, callback) {
            if (!query.length) return callback();
            fetch("/api/users/search?q=" + encodeURIComponent(query))
                .then(response => response.json())
                .then(json => callback(json.results))
                .catch(() => callback());
        }'),
    ],
]) ?>

With Custom Rendering

use yii\web\JsExpression;

<?= TomSelect::widget([
    'model' => $model,
    'attribute' => 'country_id',
    'items' => $countries,
    'renderOption' => new JsExpression('function(data, escape) {
        return "<div class=\"option\">" +
            "<img src=\"/img/flags/" + escape(data.value) + ".png\" class=\"me-2\" width=\"20\">" +
            "<span>" + escape(data.text) + "</span>" +
        "</div>";
    }'),
    'renderItem' => new JsExpression('function(data, escape) {
        return "<div class=\"item\">" +
            "<img src=\"/img/flags/" + escape(data.value) + ".png\" class=\"me-2\" width=\"16\">" +
            escape(data.text) +
        "</div>";
    }'),
]) ?>

Event Handling

use yii\web\JsExpression;

<?= TomSelect::widget([
    'model' => $model,
    'attribute' => 'category',
    'items' => $categories,
    'clientEvents' => [
        'change' => new JsExpression('function(value) {
            console.log("Selected:", value);
            // Trigger dependent dropdown update
            updateSubcategories(value);
        }'),
        'item_add' => new JsExpression('function(value, item) {
            console.log("Added item:", value);
        }'),
        'dropdown_open' => new JsExpression('function(dropdown) {
            console.log("Dropdown opened");
        }'),
    ],
]) ?>

Virtual Scroll for Large Datasets

<?= TomSelect::widget([
    'model' => $model,
    'attribute' => 'product_id',
    'placeholder' => 'Search products...',
    'plugins' => ['virtual_scroll'],
    'maxOptions' => null,
    'clientOptions' => [
        'valueField' => 'id',
        'labelField' => 'name',
        'searchField' => 'name',
        'firstUrl' => new JsExpression('function(query) {
            return "/api/products?q=" + encodeURIComponent(query) + "&page=1";
        }'),
        'load' => new JsExpression('function(query, callback) {
            const url = this.getUrl(query);
            fetch(url)
                .then(response => response.json())
                .then(json => {
                    this.setNextUrl(query, json.next_url);
                    callback(json.results);
                })
                .catch(() => callback());
        }'),
    ],
]) ?>

Using HTML Options

<?= TomSelect::widget([
    'model' => $model,
    'attribute' => 'status',
    'items' => $statuses,
    'options' => [
        'id' => 'custom-id',
        'class' => 'custom-class',
        'data-custom' => 'value',
    ],
]) ?>

Dependent/Chained Dropdowns

// Parent dropdown
<?= TomSelect::widget([
    'model' => $model,
    'attribute' => 'country_id',
    'items' => $countries,
    'variableName' => 'countrySelect',
    'clientEvents' => [
        'change' => new JsExpression('function(value) {
            citySelect.clear();
            citySelect.clearOptions();
            if (value) {
                citySelect.load(value);
            }
        }'),
    ],
]) ?>

// Child dropdown
<?= TomSelect::widget([
    'model' => $model,
    'attribute' => 'city_id',
    'items' => [],
    'variableName' => 'citySelect',
    'placeholder' => 'Select country first...',
    'clientOptions' => [
        'valueField' => 'id',
        'labelField' => 'name',
        'load' => new JsExpression('function(countryId, callback) {
            fetch("/api/cities?country_id=" + countryId)
                .then(response => response.json())
                .then(json => callback(json))
                .catch(() => callback());
        }'),
    ],
]) ?>

Pre-populating with Initial Options (AJAX)

<?= TomSelect::widget([
    'model' => $model,
    'attribute' => 'user_id',
    'clientOptions' => [
        'valueField' => 'id',
        'labelField' => 'name',
        'searchField' => ['name', 'email'],
        // Pre-populate with selected option
        'options' => [
            [
                'id' => $model->user_id,
                'name' => $model->user->name,
                'email' => $model->user->email,
            ],
        ],
        'items' => [$model->user_id],
        'load' => new JsExpression('function(query, callback) {
            if (!query.length) return callback();
            fetch("/api/users?q=" + encodeURIComponent(query))
                .then(response => response.json())
                .then(json => callback(json))
                .catch(() => callback());
        }'),
    ],
]) ?>

API Methods

After initialization, you can access the Tom Select instance through the variable name:

<?= TomSelect::widget([
    'model' => $model,
    'attribute' => 'category',
    'items' => $categories,
    'variableName' => 'mySelect',
]) ?>

<script>
// Clear selection
mySelect.clear();

// Add option dynamically
mySelect.addOption({value: 'new', text: 'New Option'});

// Select an item
mySelect.addItem('new');

// Remove option
mySelect.removeOption('value');

// Get current value
var value = mySelect.getValue();

// Set value
mySelect.setValue('newValue');

// Lock/disable
mySelect.lock();
mySelect.disable();

// Unlock/enable
mySelect.unlock();
mySelect.enable();

// Destroy instance
mySelect.destroy();
</script>

Using Base Asset (Smaller Footprint)

If you don't need all plugins, use the base asset:

<?= TomSelect::widget([
    'model' => $model,
    'attribute' => 'category',
    'items' => $categories,
    'useBaseAsset' => true,
]) ?>

Client Options Reference

All Tom Select options are supported via the clientOptions property. Common options include:

Events Reference

Styling

The widget uses Bootstrap 5 themed CSS by default. You can customize the appearance:

Override CSS Variables

.ts-wrapper {
    --ts-pr-clear-button: 0;
    --ts-pr-caret: 0;
    --ts-pr-min: .75rem;
}

.ts-control {
    border-radius: 0.375rem;
}

.ts-dropdown {
    border-radius: 0.375rem;
}

Custom CSS Classes

<?= TomSelect::widget([
    'model' => $model,
    'attribute' => 'category',
    'items' => $categories,
    'options' => [
        'class' => 'my-custom-select',
    ],
]) ?>

Troubleshooting

Widget not initializing

Make sure jQuery is loaded if you're using it elsewhere. Tom Select doesn't require jQuery but may conflict if jQuery plugins modify the DOM.

Options not showing

Check that your items array is properly formatted:

'items' => [
    'value1' => 'Label 1',
    'value2' => 'Label 2',
]

AJAX not working

Ensure your endpoint returns JSON in the expected format:

[
    {"id": 1, "name": "Option 1"},
    {"id": 2, "name": "Option 2"}
]

And configure valueField and labelField to match your data structure.

Multiple selection not working

Make sure multiple is set to true:

'multiple' => true,

Support

If you find this package helpful, consider buying me a coffee! ☕

License

This package is open-sourced software licensed under the MIT License.

Credits

• Tom Select - The underlying JavaScript library
• Yii2 Framework - The PHP framework

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Changelog

1.0.0

• Initial release
• Full Tom Select API support
• Bootstrap 5 integration
• All plugins included
• Comprehensive documentation