yii2-extensions / select2

0.2.1 2026-10-23 10:01 UTC

Requires

• php: >=8.3
• php-forge/foxy: ^0.4
• yiisoft/yii2: ~2.0.55 || ^22.0@dev

Requires (Dev)

• maglnet/composer-require-checker: ^4.7
• php-forge/support: ^0.1
• phpunit/phpunit: ^10.5
• roave/infection-static-analysis-plugin: ^1.34
• symplify/easy-coding-standard: ^13.3
• yii2-extensions/phpstan: ^0.5

Suggests

• yii2-extensions/bootstrap6: Bootstrap 6 forms and asset bundles for the `bootstrap-6` Select2 theme.
• yiisoft/yii2-bootstrap5: Bootstrap 5 forms and assets for the `bootstrap-5` Select2 theme.
• yiisoft/yii2-jquery: Required on Yii 22 for ActiveForm client validation; bootstrap yii\jquery\Bootstrap.

BSD-3-Clause

• jquery
• form
• ajax
• widget
• select2
• dropdown
• yii2

Published on Packagist.org on 2026-10-23 10:03 UTC

README

Select2 widget

Searchable Select2 widgets for Yii2 forms
ActiveForm integration, multiple selections, tagging, and paginated AJAX searches

Quick start

Installation

Configure Foxy native and the asset aliases in the installation guide, then install:

composer require --prefer-dist --prefer-stable php-forge/foxy:^0.4 yii2-extensions/select2:^0.2

Dropdown list

use Yii2\Extensions\Select2\Select2;

echo $form
    ->field($model, 'country')
    ->widget(
        Select2::class,
        [
            'items' => [
                'mx' => 'Mexico',
                'ca' => 'Canada',
            ],
            'options' => ['prompt' => ''],
            'clientOptions' => [
                'placeholder' => 'Choose a country',
                'allowClear' => true,
            ],
        ],
    );

Multiple selection and tags

use yii\helpers\Html;
use Yii2\Extensions\Select2\Select2;

echo Html::label('Regions', 'regions');
echo Select2::widget(
    [
        'name' => 'regions',
        'items' => [
            'north' => 'North',
            'south' => 'South',
        ],
        'options' => [
            'id' => 'regions',
            'multiple' => true,
            'unselect' => '',
        ],
    ],
);

Set clientOptions.tags=true separately to allow new values, and validate them on the server.

The widget uses Select2 4.0 and requires jQuery. Its native asset installation consumes published files without compiling them. See the installation guide for the Yii 22 client-validation adapter and frontend compatibility details.

Documentation

Practical guides and usage examples for Select2 widgets, forms, and remote searches.

• 📚 Installation Guide: native assets and optional Bootstrap 5 and 6 themes.
• ⚙️ Configuration Guide: models, ActiveForm, accessibility, events, and lifecycle.
• 💡 Usage Examples
• 🔄 Upgrade Guide
• 🧪 Testing Guide
• 🌐 AJAX Searches and Pagination

The guides and the API reference generated from the PHPDoc in src/ are published at https://yii2-framework.github.io/docs/extensions/select2/.

AI assistance

AI agents: read the documentation index and fetch the Markdown version of a page by appending index.md to its URL. The AI agents guide covers skill installation, client setup and verification.

• 🤖 yii2-select2 skill: Select2 integration.
• 🧭 yii2-framework skill: Yii 22.0 application conventions.

The hosted documentation covers Yii 22.0. If it does not match the installed revision or is unavailable, use the repository guides, the skill source, the source PHPDoc and the changelog.

Package information

Project status

Special thanks

This code was initially developed by contributors at yii2-cms and hosted at yii-cms/yii2-select2. We thank them all. For continuity and maintenance we have moved a copy here.

Our social networks

License