Ember

TEDSelect

A data down, actions up select component built with real DOM elements

Installation

ember install ember-ted-select

Features

ember-ted-select is a simple select element component that can do everything a native select element can do and more:

  • disabled options
  • multi-select
  • custom prompt
  • option sorting

It uses the data down, actions up pattern to avoid problematic two-way data binding, and can be used as a replacement for the deprecated {{view 'select'}} helper.

Examples

Basic usage

Call ember-ted-select in your template by providing a list of options and an action to trigger when the value of the select changes.

Remember, the selected value is not two-way bound. It's up to you to handle the new value within your action.

{{ted-select
  content=TEDevents
  onchange=(action "update")}}

Selected: {{selected.title}}
// controller.js / component.js
selected: null,

actions: {
  update(newOption){
    this.set('selected', newOption);
  }
}
Selected:

By default, the add-on will look for content.id for the option value attribute, and content.title for the option label. You can specify alternate keys using optionLabelKey and optionValueKey.

{{ted-select
  content=TEDevents
  optionValueKey="id"
  optionLabelKey="title"
  onchange=(action "update")}}

Styling & customization

ember-ted-select will use only browser-default styles. Customization is completely up to you.

For convenience, the class name on the select element itself can be changed using the selectClassNames option. This is helpful for applying framework styles, like Bootstrap's .form-control class, shown here and in the following examples.

You can also customize the select element's ID using the selectId option.

You can customize the prompt text with prompt="your custom string" or remove it completely with prompt=null.

{{ted-select
 selectClassNames="form-control"
 selectId="ted-events-select"
 prompt="Choose an event"
 content=TEDevents }}

Pass in an initial selection

You can set the value of the select using the `selected` property, especially useful for pre-populating the select with a default or initial value. Notice that selecting a new option won't mutate the outside variable

{{ted-select
  selectClassNames="form-control"
  content=TEDevents
  selected=initialSelection
  onchange=(action "update")
}}
Initial selection: TED 2014
Updated by select:

Sorting the options list

You can sort the options list by passing a single property or a comma separated list of properties to sortBy. You can also use the :desc qualifier for reversed sort order, similar to Ember.computed.sort.

{{ted-select
  selectClassNames="form-control"
  content=TEDevents
  sortBy="title"
}}

Disabled options

You can allow some options to be disabled by passing in a boolean object property to use as the disabled flag.

{{ted-select
  content=TEDevents
  selectClassNames="form-control"
  optionDisabledKey="isTEDxEvent"
}}

Disabled input

You can disable the entire input by passing in a boolean value to disabled.

{{ted-select
  content=TEDevents
  selectClassNames="form-control"
  disabled=true
}}

Named input

You can set the name attribute on the input by passing in a string value to name.

{{ted-select
  content=TEDevents
  selectClassNames="form-control"
  name="awesome-ted-select"
}}

Multi-select

All options available with single selection are also available with mutli-select, but the value of the select is now an array of options instead of a single value.

{{ted-select
  selectClassNames="form-control"
  content=TEDevents
  multiple=true
  onchange=(action "updateMultiple")
}}

<p>selected option(s): </p>
<ul>
  {{#each selectedOptions as |option|}}
    <li>{{option.title}}</li>
  {{/each}}
</ul>

selected option(s):

Two-way bound

Data down, actions up is recommended, but if you would like to two-way bind the select value to an external property, you can do so using the mut helper instead of an onchange action.

{{ted-select
  content=TEDevents
  selectClassNames="form-control"
  optionLabelKey="title"
  optionValueKey="id"
  selected=selectedOption
  onchange=(action (mut selectedOption))
}}
Selected:

Configurable properties

Property Purpose Expected Type Default value
content Pass in a content array to populate the select options. Each array element must be an object with properties for both the 'value' attribute and option label text. array null
optionValueKey [optional] Specify a property of the content object to use as each option's value attribute. string 'id'
optionLableKey [optional] Specify a property of the content object to use as each option's label. string 'title'
optionDisabledKey [optional] Specify a boolean property of the content object to use as a flag for the disabledattribute. string, null null
onchange Specify your own closure action to trigger when the select value changes. Standard usage is: (action "update"). Your action handler will receive the new value, as a single value for a standard select or as an array if multiple is active.
You can also force a two-way binding by using the [`mut` helper](http://emberjs.com/api/classes/Ember.Templates.helpers.html#method_mut). See two-way-bound for an example.
Ember action Ember.K (noop)
selected Pass in an initial selection or update the selected value from outside the component. Must match one of the options in the content array for single select, or be an array of objects for multi-select. Object, Array null
sortBy [optional] Specify a property of the content array, or a commas separated list of properties, to use for sorting the options. Append :desc to a property to reverse the sort order. When set to null, options will remain in the order of the original array. string, null null
multiple [optional] When true, adds the multiple attribute to the rendered <select>element.
When active, the onchange action will pass an array of objects rather than a single selected object.
boolean false
disabled [optional] Pass a boolean value in to disabled the entire input. boolean false
name [optional] Add a name sttribute to the select element. string, null null
selectClassNames Adds one or more custom class names to the select element. Pass multiple classes as a space separated list: form-control My-select string, null null
selectId Sets the ID on the select element. string, null null
prompt [optional] String or null. Sets the prompt text or hides the prompt option when set to null. string, null 'Select an item'