This addon mimics a native select box. It is lightweight and highly flexible.
ember install @zestia/ember-select-box
https://zestia.github.io/ember-select-box
- Mimics a native select box, but easily stylable ✔︎
- Navigatable options and groups ✔︎
- Valid Combobox / Listbox ✔︎
- Any HTML you want ✔︎
- Full control at all times with the API ✔︎
- No configuration options ✔︎
- Very few issues over many years of Ember! ✔︎
- Customisable filtering built in ✔︎
This addon intentionally...
- Does not come with any styles
- Does not concern itself with dropdown positioning
This addon will render a Combobox if you utilise the Trigger
or Input
component.
Otherwise it will render a Listbox.
View more details
- There is one interactive element at any one time. If you render a
Trigger
, then it is the Trigger that the user interacts with. It has a role of combobox. And so, by definition, it is combined with a listbox. Whilst the Trigger has focus, it accepts user input and will allow control of its associated listbox. - Similarly, if you utilise the
Input
instead, then it is the interactive element. The Input does not automatically open or close the select box like the Trigger, since that behaviour is up to the developer to hook up. - Because each option is rendered similar to a native
<option>
, this allows the addon to provide the typeahead behaviour like native select boxes (e.g. pressing F would jump to an option containing the text 'Foo').
- When using the arrow keys on a native select box, it will stop dead when you reach the end or the beginning. Whereas, with this addon it will cycle through the options. This is following advice from w3.org.
- When mousing-out of a native single select box, the current option is forgotten. Whereas, with this addon the option stays current. This is because, the select box still has focus and as such, is still receptive to user input - like pressing Enter to select that option.
- When using a multiple native select box, selecting an option only selects that 1 option. Whereas, with this addon, the item is added if it isn't already in the collection and removed if it is (although this can be customised with
@onBuildSelection
) - Right clicking an option in a native select box will select it. Whereas, with this addon, only left clicking will.
- With EPS you have to provide it a data structure which the addon uses to draw your UI. Whereas, with this addon the markup provides the structure - the same way you do with a native select box in HTML.
- You tell EPS which component to render for each option. Whereas with this addon you just render an
Option
, and fill its contents by using Named Blocks.
Optional. Fired when the select box is ready. A useful opportunity to get access to the select box's API which is passed as a parameter.
Required. Used to determine which option(s) are selected. This value is compared to the @value
's of the option components.
Optional. Use this provide an initial set of options. See yielded options
Required. Fired when a selection is made (that is, an option is clicked, or enter/space is pressed) and the new value is different to the old value.
Optional. Similar to @onChange
but fires regardless as to whether the value changed or not. The return value controls whether or not the select box will close after the selection.
Optional. The default search behaviour filters down the @options
. Use this action to perform a custom search or
see Filtering.
Optional. If true
, the component will be unfocusable and all child components (Trigger
, Input
and Option
s) will also be disabled.
Optional. If true
, @value
is expected to be an array. If an option's value is included in that array, it will be considered 'selected'.
Optional. Fired whenever a selection is made. This function receives the values most recently selected, and the previously selected values. The return value is then used as the final selection. This is primarily used to customise select boxes where @multiple
is true
- because the behaviour for a selection is undefined and totally depends on your use-case.
Optional. Whether or not the select box should be in an open state initially.
Optional. Fired when the select box is opened
Optional. Fired when the select box is closed
Optional. Fired when an option is moused over or focused via the keyboard controls
Mimics the user making a selection, and so @onChange
may fire.
Updates the select box with a new value(s). @onChange
will not fire.
Opens the select box.
Opens or closes the select box
Closes the select box
The element of the select box
The selected value(s) of the select box
True if the select box is waiting for a search to finish
Whether the select box is open
The query used to produce the latest search results. (This may be different to the current value in the text input).
These are the same options as given to the component via @options
, yielded back to you.
Unless a search has run, in which case they will be the return value from @onSearch
Required. The value of the option.
Optional. Prevents the option from being activated or selected.
The unique id of the option element
The value of the option
The index of the option amongst the options
True if the option is active
Whether or not the option is currently disabled
Whether or not the option is currently selected
Required. The group label (similar to the native optgroup
)
A container element to house each option. If no Trigger
or Input
is rendered, then this will be a Listbox.
A combobox, which by default filters down the available @options
. Customise this behaviour by providing @onSearch
.
A combobox, which toggles the select box open/closed.
Since filtering options down (and accounting for diacritics) is a common requirement, this addon comes with a utility to help.
View example
import { filter } from '@zestia/ember-select-box';
/**
* [{
* groupLabel: 'Group 1',
* items: [{
* id: 1,
* name: 'Foo'
* }, {
* id: 2,
* name: 'Bar'
* }]
* }, {
* groupLabel: 'Group 2',
* items: [{
* id: 3,
* name: 'Baz'
* }, {
* id: 4,
* name: 'Qux'
* }]
* }]
*/
@action
handleSearch(query) {
return filter(this.args.options)
.by('name')
.groups('items')
.dropEmptyGroups()
.query(query)
.run();
}
Accepts an array of options to filter down.
Required. The query string used to filter each option
Optional. By default the value of each option will be used for filtering. Provide a string to pick a specific key from an option. Provide an array to filter by multiple properties. Or provide a function to pluck your own value.
Optional. Calling this tells the filter function that your data structure contains groups of options, and the key to where those options can be found.
Optional. Tells the filter to exclude groups with no options
Optional. By default each option will be included in the results if it contains the query string. Use this function to provide your own logic to compute whether or not an option should be included.
Kicks off the filter you've configured