README.md

What is angular-custom-select?

It's an AngularJS directive that builds easily styleable, functional dropdowns using divs, rather than the not-so-customizable select element. It supports ng-model and ng-options, as well as options to customize placeholder text, control disabled states, and specify the classes applied to dropdown elements. You can check out a demo here.

How can I get it?

Use Bower

bower install --save angular-custom-select

Then include the script in your app (after including Angular, of course).

Or download it from GitHub

In the /dist directory, you'll find angular-custom-select.min.js. Download that file and include it in your app (after Angular).

How do I use it?

Add angular-custom-select as a dependency for your app, like so:

angular.module('your-amazing-app', ['angular-custom-select'])

Then you can incorporate the <custom-select> element to your markup, using ng-model and ng-options as you normally would for a select element. At the moment, angular-custom-select can handle arrays of strings or objects, but it does not yet support iteration over objects. Below are some examples.

Keep in mind that the angular-custom-select directive imposes no styling, so the dropdown won't look much like a dropdown out of the box. You can take a peek at src/scss/example.scss to get inspiration for styling your own.

Array of Strings

# Controller
$scope.selectedValues = {}
$scope.strings = ['Option A', 'Option B', 'Option C', 'Option D', 'Option E'] 

<!-- View -->
<custom-select
	ng-model="selectedValues.string"
	ng-options="string for string in strings"
	placeholder="Select one of these string values...">
</custom-select>

...will produce the following markup and update the selectedValues.string model as expected:

<div class="custom-select" ng-class="{ 'expanded': expanded }">
  <div class="placeholder option">
    <span class="value">
      Select one of these string values...
    </span>
  </div>
  <div class="option">
    <span class="value">
      Option A
    </span>
  </div>
  <div class="option">
    <span class="value">
      Option B
    </span>
  </div>
  <div class="option">
    <span class="value">
      Option C
    </span>
  </div>
  <div class="option">
    <span class="value">
      Option D
    </span>
  </div>
  <div class="option">
    <span class="value">
      Option E
    </span>
  </div>
</div>	

Array of Objects

# Controller
$scope.selectedValues = {}
$scope.objects = [
 	{ name: 'Option A' }
 	, { name: 'Option B' }
 	, { name: 'Option C' }
 	, { name: 'Option D' }
	, { name: 'Option E' }
]

<!-- View -->
<custom-select
	ng-model="selectedValues.object"
	ng-options="object as object.name for object in objects"
	placeholder="Select one of these object values...">
</custom-select> 

...will produce the following markup and update the selectedValues.object model as expected:

<div class="custom-select" ng-class="{ 'expanded': expanded }">
  <div class="placeholder option">
    <span class="value">
      Select one of these string values...
    </span>
  </div>
  <div class="option">
    <span class="value">
      Option A
    </span>
  </div>
  <div class="option">
    <span class="value">
      Option B
    </span>
  </div>
  <div class="option">
    <span class="value">
      Option C
    </span>
  </div>
  <div class="option">
    <span class="value">
      Option D
    </span>
  </div>
  <div class="option">
    <span class="value">
      Option E
    </span>
  </div>
</div>

Options

You can also configure a dropdown by adding attributes to the custom-select element:

• select-class specifies the class applied to the outermost custom dropdown element, defaults to custom-select.
• option-class specifies the class applied to each option element, defaults to option.
• option-value-wrapper-class specifies the class applied to the value text element for each option element, defaults to value.
• expanded-class specifies the class applied to the outermost custom dropdown element when the menu is open, defaults to expanded.
• placeholder-class specifies the class applied to the default/placeholder option element, defaults to placeholder.
• placeholder-label specifies the text of the default/placeholder option, defaults to Select a value....
• disabled-attribute specifies the attribute to trigger a disabled state for options, only works for objects, defaults to null.
• disabled-class specifies the class applied to disabled options, defaults to disabled.

Working with the Source

Installing Dependencies

After installing Ruby and Bundler, run bundle install from the project root to install the necessary Ruby gems.

After installing Node.js, NPM, and Gulp, run npm install from the project root to install the necessary NPM package dependencies.

After installing Bower, run bower install from the project root to install the necessary Bower component dependencies.

Compiling for Development

Run gulp to observe changes made to any .coffee files in the project, then respond by compiling/concatenating/copying the appropriate assets. The resulting files can be found in the build directory.

Compiling for Production

Run 'gulp dist' to compile angular-custom-select.min.js for production.