ui-select2   [![Build Status](https://travis-ci.org/angular-ui/ui-select2.png)](https://travis-ci.org/angular-ui/ui-select2)
==========
This directive allows you to enhance your select elements with behaviour from the [select2](http://ivaynberg.github.io/select2/) library.

# Requirements

- [AngularJS](http://angularjs.org/)
- [JQuery](http://jquery.com/)
- [Select2](http://ivaynberg.github.io/select2/)

## Setup

1. Install **Karma**, **Grunt** and **Bower**
  `$ npm install -g karma grunt-cli bower`
2. Install development dependencies
  `$ npm install`
3. Install components
  `$ bower install`
4. ???
5. Profit!

## Testing

We use [Grunt](http://gruntjs.com/) to check for JavaScript syntax errors and execute all unit tests. To run Grunt, simply execute:

`$ grunt`

This will lint and test the code, then exit. To have Grunt stay open and automatically lint and test your files whenever you make a code change, use:

`$ grunt karma:server watch`

This will start a Karma server in the background and run unit tests in Firefox and PhantomJS whenever the source code or spec file is saved.

# Usage

We use [bower](https://github.com/bower/bower) for dependency management. Install AngularUI Select2 into your project by running the command

`$ bower install angular-ui-select2`

If you use a `bower.json` file in your project, you can have Bower save ui-select2 as a dependency by passing the `--save` or `--save-dev` flag with the above command.

This will copy the ui-select2 files into your `bower_components` folder, along with its dependencies. Load the script files in your application:
```html
<link rel="stylesheet" href="bower_components/select2/select2.css">
<script type="text/javascript" src="bower_components/jquery/jquery.js"></script>
<script type="text/javascript" src="bower_components/select2/select2.js"></script>
<script type="text/javascript" src="bower_components/angular/angular.js"></script>
<script type="text/javascript" src="bower_components/angular-ui-select2/src/select2.js"></script>
```

(Note that `jquery` must be loaded before `angular` so that it doesn't use `jqLite` internally)


Add the select2 module as a dependency to your application module:

```javascript
var myAppModule = angular.module('MyApp', ['ui.select2']);
```

Apply the directive to your form elements:

```html
<select ui-select2 ng-model="select2" data-placeholder="Pick a number">
    <option value=""></option>
    <option value="one">First</option>
    <option value="two">Second</option>
    <option value="three">Third</option>
</select>
```

## Options

All the select2 options can be passed through the directive. You can read more about the supported list of options and what they do on the [Select2 Documentation Page](http://ivaynberg.github.com/select2/)

```javascript
myAppModule.controller('MyController', function($scope) {
    $scope.select2Options = {
        allowClear:true
    };
});
```

```html
<select ui-select2="select2Options" ng-model="select2">
    <option value="one">First</option>
    <option value="two">Second</option>
    <option value="three">Third</option>
</select>
```

Some time it may make sense to specify the options in the template file.

```html
<select ui-select2="{ allowClear: true}" ng-model="select2">
    <option value="one">First</option>
    <option value="two">Second</option>
    <option value="three">Third</option>
</select>
```

## Working with ng-model

The ui-select2 directive plays nicely with ng-model and validation directives such as ng-required.

If you add the ng-model directive to same the element as ui-select2 then the picked option is automatically synchronized with the model value.

## Working with dynamic options
`ui-select2` is incompatible with `<select ng-options>`. For the best results use `<option ng-repeat>` instead.
```html
<select ui-select2 ng-model="select2" data-placeholder="Pick a number">
    <option value=""></option>
    <option ng-repeat="number in range" value="{{number.value}}">{{number.text}}</option>
</select>
```

## Working with placeholder text
In order to properly support the Select2 placeholder, create an empty `<option>` tag at the top of the `<select>` and either set a `data-placeholder` on the select element or pass a `placeholder` option to Select2.
```html
<select ui-select2 ng-model="number" data-placeholder="Pick a number">
    <option value=""></option>
    <option value="one">First</option>
    <option value="two">Second</option>
    <option value="three">Third</option>
</select>
```

## ng-required directive

If you apply the required directive to element then the form element is invalid until an option is selected.

Note: Remember that the ng-required directive must be explicitly set, i.e. to "true".  This is especially true on divs:

```html
<select ui-select2 ng-model="number" data-placeholder="Pick a number" ng-required="true">
    <option value=""></option>
    <option value="one">First</option>
    <option value="two">Second</option>
    <option value="three">Third</option>
</select>
```

## Using simple tagging mode

When AngularJS View-Model tags are stored as a list of strings, setting
the ui-select2 specific option `simple_tags` will allow to keep the model
as a list of strings, and not convert it into a list of Select2 tag objects.

```html
<input
    type="text"
    ui-select2="select2Options"
    ng-model="list_of_string"
    >
```

```javascript
myAppModule.controller('MyController', function($scope) {
    $scope.list_of_string = ['tag1', 'tag2']
    $scope.select2Options = {
        'multiple': true,
        'simple_tags': true,
        'tags': ['tag1', 'tag2', 'tag3', 'tag4']  // Can be empty list.
    };
});
```