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`	Function 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 id of a DOM element where the dropdown will be rendered using `#in-element`
destinationElement	`HTMLElement`	Instead of passing `destination`, you can pass the DOM element where the dropdown will be rendered using `#in-element`
contentComponent	`String or Component`	The component to render 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 a touch device
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 render as trigger 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.
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.
rootEventType	String	(Default: `'click'`) The type of mouse event that handles closing the dropdown. Valid values: "mousedown" and "click"

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
tabindex	Number	Tabindex of the trigger, which defaults to 0 so the trigger is focusable by default
htmlTag	String	(Default: `'div'`) The tag of the trigger component
title	String	Maps to the `title` attribute
eventType	String	(Default: `'click'`) The type of mouse event that triggers the trigger. Valid values: "mousedown" and "click"
stopPropagation	Boolean	(Default: `false`) Whether 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
animationEnabled	boolean	Flag to determine whether the content will allow CSS animations. Defaults to true
htmlTag	String	(Default: `'div'`) The tag of the content component
shouldReposition	Function	An optional function that can be used to avoid uncecessary repositions. To skip a reposition, simply return `false`. This function will be invoked when the DOM of the content is changed. It receives two arguments: a MutationRecord and the public API object.

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 change 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 } }

< Test helpers