Skip to content

Latest commit

 

History

History
630 lines (552 loc) · 15.4 KB

README.md

File metadata and controls

630 lines (552 loc) · 15.4 KB
Raw

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.

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
multiple If true, `value` should be an array
disabled If true adds an `is-disabled` class
is-open Controls the open/closed state
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.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.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
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

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=attrs.value on-select=attrs.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:

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

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

let 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.