ember-select-box v3.0.7

ember-select-box

Select box solutions are rarely perfect for what you want.

They come with a myriad of options to configure every possible situation, and they make too many assumptions about how your select-box behaves.

This addon does less, and gives you the primitives to easily compose your own.

• Ways to achieve what you want
• Example scenarios
• Code for example scenarios
• Things to note
• FAQ

Installation

ember install ember-select-box

Native select box

Read more

{{#select-box/native as |sb|}}
  {{sb.option value=1 label='One'}}
  {{sb.option value=2 label='Two'}}
  {{sb.option value=3 label='Three'}}
{{/select-box/native}}

Faux Select box

{{#select-box as |sb|}}
  {{sb.option value=1 label='One'}}
  {{sb.option value=2 label='Two'}}
  {{sb.option value=3 label='Three'}}
{{/select-box}}

Option

{{sb.option value=1 label='One'}}

{{#sb.option value=2 label='Two' as |o|}}
  {{o.label}}
{{/sb.option}}

Group

Self explanitory, just wraps the options in extra markup.

{{#sb.group label='Things'}}
  {{sb.option value=thing label=thing.name}}
{{/sb.group}}

Options

You only need to wrap the options up in with sb.options if you require extra markup for styling, or you want the options to be navigatable.

{{#sb.options}}
  {{sb.option value=1 label='One'}}
  {{sb.option value=2 label='Two'}}
{{/sb.options}}

Input

Allows you to input text into the select box, usually for running searches/filtering

{{sb.input}}

Selected option

Does not render the user's selected option automatically, but rather just provides a way for you to render the option(s) that have been selected.

{{sb.selected-option value=1 label='One'}}

{{#sb.selected-option value=2 label='Two' as |so|}}
  {{so.label}}
{{/sb.selected-option}}

Selected options

{{#sb.selected-options}}
  {{#sb.selected-option}}You chose this{{/sb.selected-option}}
  {{#sb.selected-option}}And this{{/sb.selected-option}}
{{/sb.selected-options}}

Provides a container for options that the user selected. Does not do anything by default, but it is possible to activate selected options using the API, thereby allowing you to create your own navigatable select box.

API

The select boxes that come with this addon exposes an API to you as an argument to action handlers like so:

{{select-box on-select=(action 'selectedAnOption')}}

actions: {
  selectedAnOption(value, api) {
    api.close(); // for example.
  }
}

Customising

There are 3 ways to get what you want

1. compose a new one
2. OR extend an existing one
3. OR create a new one from the mixins

Compose

It's recommended that you compose your own select box like so :

{{#select-box value=value on-select=on-select class-prefix='my-select-box' as |sb|}}}
  {{sb.selected-option label=sb.value.name}}
  <button onclick={{action sb.toggle}}>Toggle</button>
  {{yield sb}}
{{/select-box}}

...and then use it like this:

{{#my-select value=thing on-select=(action 'selectedAThing') as |sb|}}
  {{#each things as |thing|}}
    {{sb.option value=thing label=thing.name}}
  {{/each}}
{{/my-select}}

...will render...

<div class="my-select">
  <div class="my-select-box">
    <div class="my-select-box-selected-option">Foo</div>
    <button>Toggle</button>
    <div class="my-select-box-option is-selected">Foo</div>
    <div class="my-select-box-option">Bar</div>
    <div class="my-select-box-option">Baz</div>
  </div>
</div>

Extend

If you need even more flexibility, you can extend the select box:

const MySelectBox = SelectBox.extend({
  click() {
    this.send('toggle');
  }
})

Mixins

if you need even more flexibility you can create your own select box using the mixins

const MySelectBox = Component.extend(BaseSelectBox, Toggleable, Searchable);

Wormhole

ember-select-box works well with ember-wormhole. In most cases, this isn't needed - but it can be useful to render your <options>'s elsewhere in the DOM if you find yourself with overflow:hidden style issues for example.

{{#select-box class-prefix='worm-select' as |sb|}}
  {{#ember-wormhole to='destination'}}
    {{#sb.options}}
      {{yield sb}}
    {{/sb.options}}
  {{/ember-wormhole}}
{{/select-box}}

Native Select Box info

Rendering lots of components in Ember can be slow. If your select box only uses primitive values, you do not need to use {{sb.option}}, instead you can use a plain old <option> element [Example].

Things to note

• With just a few lines of code you can create an autocompleter using the input component.
• Thanks to contextual components there is not a truth helper in sight.
• This project will never come with built-in styles.
• The select box's primitives are available to you via the yielded API and as an argument to action handlers, so you should never feel held-back when creating your select box

FAQ

Q: Why aren't the native and faux select boxes two addons. A: Less effort maintaining 1 addon. Splitting out would be trivial though.