kartik-v/yii2-widget-select2

Enhanced Yii2 wrapper for the Select2 jQuery plugin (sub repo split from yii2-widgets).

Fund package maintenance!
Open Collective

Installs: 6 968 304

Dependents: 288

Suggesters: 1

Security: 0

Stars: 322

Watchers: 20

Forks: 144

Open Issues: 5

Language:CSS

Type:yii2-extension

v2.2.5 2023-06-22 07:43 UTC

README

Financial Contributors on Open Collective Stable Version Unstable Version License

Total Downloads Monthly Downloads Daily Downloads

This is the Select2 widget and a Yii 2 enhanced wrapper for the Select2 jQuery plugin. This input widget is a jQuery based replacement for select boxes. It supports searching, remote data sets, and infinite scrolling of results. The widget is specially styled for Bootstrap 3 and offers a few enhancements not available in the source plugin. The widget allows graceful degradation to a normal HTML select or text input, if the browser does not support JQuery.

NOTE: This extension is a sub repo split of yii2-widgets. The split has been done since 08-Nov-2014 to allow developers to install this specific widget in isolation if needed. One can also use the extension the previous way with the whole suite of yii2-widgets.

Installation

The preferred way to install this extension is through composer. Check the composer.json for this extension's requirements and dependencies. Read this web tip /wiki on setting the minimum-stability settings for your application's composer.json.

To install, either run

$ php composer.phar require kartik-v/yii2-widget-select2 "@dev"

or add

"kartik-v/yii2-widget-select2": "@dev"

to the require section of your composer.json file.

Release Changes

NOTE: Refer the CHANGE LOG for details on changes to various releases.

The widget has a major version revamp with v2.0. This release includes updates to use Select2 plugin release v4.0. Select2 release v4.0 is a major rewrite over Select2 v3.x and hence quite a few enhancements or changes should be expected. To use the earlier plugin release v3.5.2, you must point it to the v1.0.1 release of the widget.

Enhancements with release v2.0:

  • New theme property that allows you to set themes in Select2 to style your widget.
  • A brand new theme by Krajee Select2::THEME_KRAJEE is specially styled for Select2. This will help achieve various new yii2-widget-select2 features. This theme matches the bootstrap 3 styling with enhancements.
  • Additional themes provided in form of Select2::THEME_DEFAULT, Select2::THEME_CLASSIC, and Select2::THEME_BOOTSTRAP. One can add their own custom theme and configure the widget.
  • No more query plugin property needed. It is also not mandatory to configure data even if you have not set tags or query or ajax. Widget will intelligently evaluate the properties and default list values.
  • Enhanced tagging support. Use it just like a multiple select but with taggable values. In addition, one can create tags on the fly.
  • Enhanced ajax support. Refer the demos for details.
  • The initSelection method of Select2 3.5.x plugin is obsolete/removed. New initValueText property is been provided with the Select2 widget to cater to this (e.g. for ajax based loading).
  • Ability to disable selective option values in the Select2 dropdown OR add HTML attributes to selective options.
  • Enhancement by Krajee to disable the search box to use like a normal select.
  • Enhancements to locales and translations. Allow multiple language Select2 widgets on the same page.

Documentation and Demo

You can refer detailed documentation and demos and API Code Documentation on usage of the extension.

Usage

use kartik\select2\Select2;

// Normal select with ActiveForm & model
echo $form->field($model, 'state_1')->widget(Select2::classname(), [
    'data' => $data,
    'language' => 'de',
    'options' => ['placeholder' => 'Select a state ...'],
    'pluginOptions' => [
        'allowClear' => true
    ],
]);

// Multiple select without model
echo Select2::widget([
    'name' => 'state_2',
    'value' => '',
    'data' => $data,
    'options' => ['multiple' => true, 'placeholder' => 'Select states ...']
]);

Contributors

Code Contributors

This project exists thanks to all the people who contribute. [Contribute]. 68747470733a2f2f6f70656e636f6c6c6563746976652e636f6d2f796969322d7769646765742d73656c656374322f636f6e7472696275746f72732e7376673f77696474683d38393026627574746f6e3d66616c7365

Financial Contributors

Become a financial contributor and help us sustain our community. [Contribute]

Individuals

68747470733a2f2f6f70656e636f6c6c6563746976652e636f6d2f796969322d7769646765742d73656c656374322f696e646976696475616c732e7376673f77696474683d383930

Organizations

Support this project with your organization. Your logo will show up here with a link to your website. [Contribute]

68747470733a2f2f6f70656e636f6c6c6563746976652e636f6d2f796969322d7769646765742d73656c656374322f6f7267616e697a6174696f6e2f302f6176617461722e737667 68747470733a2f2f6f70656e636f6c6c6563746976652e636f6d2f796969322d7769646765742d73656c656374322f6f7267616e697a6174696f6e2f312f6176617461722e737667 68747470733a2f2f6f70656e636f6c6c6563746976652e636f6d2f796969322d7769646765742d73656c656374322f6f7267616e697a6174696f6e2f322f6176617461722e737667 68747470733a2f2f6f70656e636f6c6c6563746976652e636f6d2f796969322d7769646765742d73656c656374322f6f7267616e697a6174696f6e2f332f6176617461722e737667 68747470733a2f2f6f70656e636f6c6c6563746976652e636f6d2f796969322d7769646765742d73656c656374322f6f7267616e697a6174696f6e2f342f6176617461722e737667 68747470733a2f2f6f70656e636f6c6c6563746976652e636f6d2f796969322d7769646765742d73656c656374322f6f7267616e697a6174696f6e2f352f6176617461722e737667 68747470733a2f2f6f70656e636f6c6c6563746976652e636f6d2f796969322d7769646765742d73656c656374322f6f7267616e697a6174696f6e2f362f6176617461722e737667 68747470733a2f2f6f70656e636f6c6c6563746976652e636f6d2f796969322d7769646765742d73656c656374322f6f7267616e697a6174696f6e2f372f6176617461722e737667 68747470733a2f2f6f70656e636f6c6c6563746976652e636f6d2f796969322d7769646765742d73656c656374322f6f7267616e697a6174696f6e2f382f6176617461722e737667 68747470733a2f2f6f70656e636f6c6c6563746976652e636f6d2f796969322d7769646765742d73656c656374322f6f7267616e697a6174696f6e2f392f6176617461722e737667

License

yii2-widget-select2 is released under the BSD-3-Clause License. See the bundled LICENSE.md for details.