# 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](#customising) * Example scenarios * Code for example scenarios * [Things to note](#things-to-note) * [FAQ](#faq) ### Installation ``` ember install ember-select-box ```
#### Native select box [Read more](#native-select-box-info) ```handlebars {{#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 ```handlebars {{#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 ```handlebars {{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. ```handlebars {{#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. ```handlebars {{#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 ```handlebars {{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. ```handlebars {{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 ```handlebars {{#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: ```handlebars {{select-box on-select=(action 'selectedAnOption')}} ``` ```javascript actions: { selectedAnOption(value, api) { api.close(); // for example. } } ```
### Customising There are 3 ways to get what you want 1. [compose](#compose) a new one 2. OR [extend](#extend) an existing one 3. OR create a new one from the [mixins](#mixins) ##### Compose It's recommended that you compose your own select box like so : ```handlebars {{#select-box value=value on-select=on-select class-prefix='my-select-box' as |sb|}}} {{sb.selected-option label=sb.value.name}} {{yield sb}} {{/select-box}} ``` ...and then use it like this: ```handlebars {{#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... ```html
Foo
Foo
Bar
Baz
``` ##### Extend If you need even more flexibility, you can extend the select box: ```javascript 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 ```javascript 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 ``'s elsewhere in the DOM if you find yourself with `overflow:hidden` style issues for example. ```handlebars {{#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 `