API reference

API reference

Component's options

Option Type Description
afterOptionsComponent string/contextua-component The component rendered after the list of options. It is empty by default in both single and multiple selects
allowClear boolean When truthy, single selects allow to nullify the selection
animationEnabled boolean Flag to determine whether the content will allow CSS animations. Defaults to true
ariaDescribedBy string Sets aria-describedby on the component
ariaInvalid string Sets aria-invalid on the component
ariaLabel string Sets aria-label on the component
ariaLabelledBy string Sets aria-labelledby on the component
beforeOptionsComponent string/contextua-component The component rendered before the list of options. In single selects defaults to the searchbox. In multiple select defaults to nothing
buildSelection function The function to be invoked when the user selects an option. Should return either the `option` or `null`. This is used internally by `PowerSelectMultiple` to construct a new array of options, but can be used for unselecting a single option by returning `null` to the `onchange` event.
calculatePosition Function A function that allows to customize the position and dimension of the select's content. For more info check https://www.ember-basic-dropdown.com/docs/position
class string The CSS class of the component. The component by default is tagless, so this won't take any effect unless the user specifies `tagName=div` too.
closeOnSelect boolean Defaults to true. When false, the component won't be closed after the user chooses an option, either with the mouse/keyboard or using the `choose` action in the publicAPI.
defaultHighlighted any or function By default when the select opens, the highlighted element is the selected one, or the first if none. If you want to change this behaviour, pass an option or a function that receives the publicAPI and resolves to the highlighted option.
destination 'ember-basic-dropdown-wormhole' The id of the element used as target for the content of the dropdown, when not rendered in place.
disabled boolean When truthy the component cannot be interacted
dropdownClass string Class to be applied to the dropdown only
extra object Object to store any arbitrary configuration meant to be used by custom components
groupComponent string The component to render instead of the default one around the list of options that have groups
highlightOnHover boolean Defaults to true. When false, when the user hovers over an option with the mouse, it will not be highlighted.
horizontalPosition string In the case when trigger is narrower than dropdown. By default is "auto", meaning that will position the list depending on the side of the trigger. Possible values are "left", "center" and "right".
initiallyOpened boolean Boolean property that controls if the component is rendered initially in the open state. It won't mutate if the component is opened/closed. It won't close/open the component when mutated either.
loadingMessage string Message shown in the list of options while the options are still not resolved, typically after a search but also when options is a promise.
matcher function The function(option, searchTerm) used to filter results. The default one will compare ignoring diacritics
matchTriggerWidth boolean (defaults to true) When enabled (and it's enabled by default) the dropdown with match the width of the trigger.
noMatchesMessage string Message shown when a search doesn't find any matching result.
onblur function The function to be invoked when component or any of its subitems looses the focus. The last argument is the FocusEvent, that can be used to disambiguate what gained the focus
onchange function The function to be invoked when the user selects or unselects an option
onclose function The function to be invoked when component is closed
onfocus function The function to be invoked when component or any of its subitems gains the focus. The last argument is the FocusEvent, that can be used to disambiguate what gained the focus
oninput function The function to be invoked when the user changes the text in any search input of the component. If the user returns false the default behaviour (filter/search) is prevented.
onkeydown function The function to be invoked when the user presses a key being the component or the inputs inside it focused
onopen function The function to be invoked when component is opened
options collection Collection of options to display in the component
optionsComponent string The component to render instead of the default one inside the list of options
placeholder string Text to display in the trigger of the component while no option is selected
placeholderComponent string or component Component to be rendered as placeholder. It can be used along with placeholder and has access to it
preventScroll boolean (defaults to false) Flag that prevents any elements on the page outside the dropdown from scrolling. This matches platform-provided select element behavior. Note that this has no effect when scroll is performed on touch device.
renderInPlace boolean When truthy, the list of options will be rendered in place instead of being attached to the root of the body and positioned with javascript. Enabling this option also adds a wrapper div around the trigger and the content with class .ember-power-select.
scrollTo function The function(option, select, event) that users can pass to customize the list of options must scroll to put an element into the viewport.
search function The function(searchTerm) to invoke when the user uses the search input.
searchEnabled boolean When falsey, hides the search in single selects
searchField string When the options are objects and no custom matches function is provided, this option tells the component what property of the options should the default matches use to filter
searchMessage string Message shown in options list when no search has been entered and there are no options.
searchPlaceholder string Placeholder of the search box
selected any or array The selected option (or collection of options in multiple mode)
selectedItemComponent string The component to render to customize just the selected item of the trigger
tabindex string The tabindex of the trigger
triggerClass string Class to be applied to the trigger only
triggerComponent string The component to render instead of the default one inside the trigger
triggerId string The id to be applied to the trigger. Useful link the select to a <label> tag
triggerRole string The aria-role to use on the trigger element. Defaults to 'button'
typeAheadMatcher function The function(option, searchTerm) used to match the searchTerm with an option when the selector is closed or search is disabled. The default one will compare ignoring diacritics.
verticalPosition string The strategy to position the list of options. By default is "auto", meaning that will position the list depending on the space available around the trigger. The other possible values are "above" and "below".

Public API's methods and actions

All actions, subcomponents and blocks of Ember Power Select receive an object containing the public API of the component. That object contains (some of) the state of the component and some actions to interact with it.

Properties of this object are read-only. The only way of interacting with the component through this public API object is using the actions.

{
  disabled: <boolean>,            // Truthy if the component received `disabled=true`
  highlighted: <T>,               // Contains the currently highlighted option (if any)
  isActive: <boolean>,            // Truthy if the trigger is focused. Other subcomponents can mark it as active depending on other logic.
  isOpen: <boolean>,              // Truthy if the dropdown is open.
  lastSearchedText: <string>,     // Contains the text of the last finished search. In sync searches will match `searchText`. In async searches, it will match it if the current search is fulfilled
  loading: <boolean>,             // Truthy if there is a pending promise that will update the results
  options: <array[T]>,            // Contains the regular array with the resolved collection of options.
  results: <array[T]>,            // Contains the regular array with the active set of results.
  resultsCount: <number>,         // Contains the number of results incuding those nested/disabled
  searchText: <string>,           // Contains the text of the current search
  selected: <T> or <array[T]>,    // Contains the resolved selected option (or options in multiple selects)
  uniqueId: <string>,             // Contains the unique of this instance of EmberPowerSelect. It's of the form `ember1234`.
  actions: {
    choose(option) { ... },       // Chooses the given options if it's not disabled (slight different than `select`)
    close() { ... },              // Closes the select
    highlight(option) { ... },    // Highlights the given option (if it's not disabled)
    open() { ... },               // Opens the select
    reposition() { ... },         // Repositions the dropdown (noop if renderInPlace=true)
    scrollTo(option) { ... },     // Scrolls the given option into the viewport
    search(term) { ... },         // Performs a search
    select(option) { ... },       // Selects the given option (if it's not disabled)
    toggle() { ... }              // Toggles the select
  }
}