API reference

It's hard to find a proper place in the guides for explaining every single option in depth, and some of them are so straightforward that they don't require an example, so use this section as a more exhaustive list.


Dropdown

Option Type Description
calculatePosition Function Fuction to customize how the content of the dropdown is positioned.
class String The class of the dropdown component. Since this component is tagless by default, you need to combine it with the tagName to be effective
defaultClass String Another way of providing a class to the component without polluting the class attribute. Useful in contextual component to allow users give their own classes while still retaining some defaults
destination String The selector of a DOM element where the dropdown will be rendered using #-in-element
contentComponent String or Component The component to rended as content instead of the default content component. You probably don't want to use this option.
horizontalPosition String The horizontal positioning strategy of the content. Can be one of auto (the default), left, center or right
matchTriggerWidth Boolean (Default: false). Flag that indicates whether or not the content's width should be equal to the width of the trigger.
preventScroll Boolean (Default: 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 devic
renderInPlace String When passed true, the content will render next to the trigger instead of being placed in the root of the body.
initiallyOpened Boolean (Default: false). When passed true the component is first rendered open. Used in combination with preventScroll it changes Fastboot user experience, but other than that it does not alter its behavior. The user can close it as usual.
tagName String (Default: "") The tag of the component.
triggerComponent String The component to rended as content instead of the default trigger component.
verticalPosition String The vertical positioning strategy of the content. Can be one of auto (the default), above or below
registerAPI Function An action that will be invoked with the new public API of the component every time there is a change in the state of the component.
onFocus Function Action that will be invoked when the component gains focus
onOpen Function Action that will be called when the component is about to open. Returning false from this function will prevent the component from being opened.
onClose Function Action that will be called when the component is about to close. Returning false from this function will prevent the component from being closed.

Trigger

Option Type Description
ariaDescribedBy String Maps to aria-described-by
ariaInvalid Boolean Maps to aria-invalid
ariaLabel String Maps to aria-label
ariaLabelledBy String Maps to aria-labeledby
class String Extra classes to be added to the trigger components
onBlur Function Action that will be invoked when a blur event is fired on the trigger
onFocus Function Action that will be invoked when a focus event is fired on the trigger
onFocusIn Function Action that will be invoked when a focusin event is fired on the trigger
onFocusOut Function Action that will be invoked when a focusout event is fired on the trigger
onKeyDown Function Action that will be invoked when a keydown event is fired on the trigger
onKeyUp Function Action that will be invoked when a keyup event is fired on the trigger
onMouseDown Function Action that will be invoked when an mousedown event is fired on the trigger
onMouseEnter Function Action that will be invoked when an mouseenter event is fired on the trigger
onMouseLeave Function Action that will be invoked when an mouseleave event is fired on the trigger
onTouchEnd Function Action that will be invoked when an touchend event is fired on the trigger
tabindex Number Tabindex of the trigger, which defaults to 0 so the tigger is focusable by default
title String Maps to the title attribute
eventType String (Default: 'mousedown') The type of mouse event that triggers the trigger. Valid values: "mousedown" and "click"
stopPropagation Boolean (Default: false) Wether the trigger should prevent the propagation of the event that triggers it (click or mousedown)

Content

Option Type Description
class String The class of the dropdown's content
to String [DEPRECATED]The selector of a DOM element where the dropdown will be rendered using ember-wormhole
onFocusIn Function Function invoked when the focusin even is fired withing the component
onFocusOut Function Function invoked when the focusout even is fired withing the component
onMouseEnter Function Function invoked when the mouseenter even is fired withing the component
onMouseLeave Function Function invoked when the mouseleave even is fired withing the component
onKeyDown Function Action that will be invoked when a keydown event is fired on the content
animationEnabled boolean Flag to determine whether the content will allow CSS animations. Defaults to true

Public API's methods and actions

All actions and subcomponents of Ember Basic Dropdown receive a single object containing the entirety of the public API of the component.

Any non underscored property or action of this object can be considered public and it's not going to suffed changes without causing a major version bump, so if you are building another component on top of Ember Basic Dropdown, you know that you are safe as long as you use this object.

  {
    uniqueId: <string>,             // Contains the unique of this instance of EmberBasicDropdown. It's of the form `ember1234`.
    disabled: <boolean>,            // Truthy if the component received `disabled=true`
    isOpen: <boolean>,              // Truthy if the component is currently opened
    actions: {
      close() { ... },              // Closes the dropdown
      open() { ... },               // Opens the dropdown
      reposition() { ... },         // Repositions the dropdown
      toggle() { ... }              // Toggles the dropdown
    }
  }