# Select2

> Searchable Select2 widgets for Yii2 forms

**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](/docs/extensions/select2/installation/index.md), then install:

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

### Dropdown list

```php
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

```php
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](https://select2.org/) 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](/docs/extensions/select2/installation/index.md): native assets and optional Bootstrap 5 and 6 themes.
- ⚙️ [Configuration Guide](/docs/extensions/select2/configuration/index.md): models, ActiveForm, accessibility, events, and lifecycle.
- 💡 [Usage Examples](/docs/extensions/select2/examples/index.md)
- 🔄 [Upgrade Guide](https://github.com/yii2-extensions/select2/blob/main/UPGRADE.md)
- 🧪 [Testing Guide](/docs/extensions/select2/testing/index.md)
- 🌐 [AJAX Searches and Pagination](/docs/extensions/select2/remote-data/index.md)

The guides and the [API reference](https://yii2-framework.github.io/docs/extensions/select2/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](https://yii2-framework.github.io/docs/llms.txt) and fetch the Markdown version
of a page by appending `index.md` to its URL. The
[AI agents guide](https://yii2-framework.github.io/docs/project/ai-agents/) covers skill installation, client setup and
verification.

- 🤖 [`yii2-select2` skill](/docs/extensions/select2/agents/index.md): Select2 integration.
- 🧭 [`yii2-framework` skill](https://yii2-framework.github.io/docs/guide/skills/yii2-framework/): 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](#documentation), the [skill source](https://github.com/yii2-extensions/select2/blob/main/skills/yii2-select2/SKILL.md), the source PHPDoc and the
[changelog](https://github.com/yii2-extensions/select2/blob/main/CHANGELOG.md).

## Special thanks

This code was initially developed by contributors at yii2-cms and hosted at
[yii-cms/yii2-select2](https://github.com/yii-cms/yii2-select2). We thank them all. For continuity and maintenance we
have moved a copy here.

## Our social networks

[Follow on X](https://x.com/Terabytesoftw)
[Follow on Facebook](https://www.facebook.com/wilmer.arambula.9)
[Join our Subreddit](https://www.reddit.com/r/Yii2/)
[Join on Telegram](https://t.me/yii_framework_in_english)

## License

[License](https://github.com/yii2-extensions/select2/blob/main/LICENSE)

## Package

- Source code and issues: [yii2-extensions/select2](https://github.com/yii2-extensions/select2). Star the repository if the package is useful to you.
- Composer package: [yii2-extensions/select2](https://packagist.org/packages/yii2-extensions/select2).
- Changelog: [CHANGELOG.md](https://github.com/yii2-extensions/select2/blob/main/CHANGELOG.md).