A data down, actions up select component built with real DOM elements
ember install ember-ted-select
ember-ted-select
is a simple select element component that can do everything a native select element can do and more:
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.
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);
}
}
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")}}
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 }}
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")
}}
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"
}}
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"
}}
You can disable the entire input by passing in a boolean value to disabled
.
{{ted-select
content=TEDevents
selectClassNames="form-control"
disabled=true
}}
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"
}}
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):
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))
}}
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 disabled attribute. |
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' |