ember-select-box

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}}

View attributes

Attribute	Description
value	Used to determine which option is selected, can be a promise
multiple	If true, `value` should be an array. Also adds an `is-multiple` class
disabled	If true adds an `is-disabled` class
is-open	Controls the open/closed state
on-open	Fired when the select box is opened
on-close	Fired when the select box is closed
on-init	Fired when the select box initialises. Useful opportunity to get access to the select box's API which is passed as a parameter.
on-select	Fired when an option is clicked, or enter is pressed regardless as to whether the value changed or not. Subsequently fired by use of the `select` API.
on-update	Fired once upon initialisation of the select box (as its initial value is set). Subsequently fired by use of the `update` API or if the value attribute changes.
on-search	Fired when the select box decides to run a search
on-searched	Fired after the last succesful search attempt
search-min-chars	Prevents the on-search action from firing until there are enough chars (default 1)
search-delay-time	Milliseconds to debounce the on-search action from firing (default 100)
search-slow-time	Milliseconds considered for a search to be taking too long (default 500)
class-prefix	Adds a prefix to the class name of all child select-box components
on-click-outside	Useful for closing the select box
on-focus-in	Fired when focus enters the select box, normalised if it contains an input
on-focus-out	Fired when focus leaves the select box
on-press-backspace
on-press-tab
on-press-enter	Useful for preventing default action of event
on-press-escape	Useful for closing and/or resetting a select box
on-press-left	Useful for navigating multi-select boxes
on-press-up	Useful for navigating up
on-press-right	Useful for navigating multi-select boxes
on-press-down	Useful for navigating down

View yielded API

Property	Description
sb.isSearching	Whether the promise returned from the `on-search` action is running
sb.isSlowSearch	True if the promised search results are taking a while
sb.isOpen	True if the select box is open
sb.open	Opens the select box, adding `is-open` class name
sb.close	Closes the select box removing the `is-open` class name
sb.toggle	Opens or closes the select box
sb.select	Selects an arbitrary value and fires the `on-select` action
sb.update	Updates the selected value, but does not fire the `on-select` action
sb.selectActiveOption	Selects the value of whichever option is currently active
sb.search	Runs an arbitrary search using the search function provided by `on-search`
sb.stopSearching	'Cancels' searches currently in progress (even though promises are not cancelable)
sb.setInputValue	Lets you update the input value, useful for when a selection has been made
sb.focusInput	Focuses the input associated with the select box
sb.blurInput	Unfocuses the input associated with the select box
sb.activateOptionAtIndex	Adds an `is-active` class to the option at the index
sb.activateNextOption	Activates the next option (pass in true to scroll if necessary too)
sb.activatePreviousOption	As above but reverse
sb.deactivateOptions	Makes no option be active
sb.activateSelectedOptionAtIndex	Activates the selected option at the index
sb.activateNextSelectedOption	Activates the next selected option
sb.activatePreviousSelectedOption	As above but reverse
sb.deactivateSelectedOptions	Makes no selected option be active

---

Option

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

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

View attributes

Attribute	Description
selected	Used for manually selecting an option. (Most of the time you won't need to use this because the options automatically know whether or not they are selected based on the value attrbute set on the select box component itself)
name
title
tabindex
disabled
size
tabindex
multiple
aria-label
style
value	Can be anything, including a promise
label	Used as the display text by default
on-select	Useful for firing one-off actions when an option is selected
on-activate	Fired when an individual option is activated

View yielded API

Property	Description
o.selected	Whether or not the option is currently selected
o.value	The value of the option
o.label	The label of the option
o.index	The index of the option amongst the options
o.disabled	Whether or not the option is currently disabled

---

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}}

View attributes

Attribute	Description
style	Useful for customising the style of the options container

---

Input

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

{{sb.input}}

View attributes

Attribute	Description
type	Sets the type of input text/search etc...
value
size
autofocus
placeholder
readonly
disabled
on-input	Fired when text is input
on-delete	Fired when there is no text present, but backspace is pressed
on-clear	Fired when text is cleared completely

---

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}}

View attributes

Attribute	Description
title
style
on-activate	Fired when a selected option is activated

---

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.

View attributes

Attribute	Description
style	Useful for one-off styling of selected options

---

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.