Dropdown Interaction component used to scaffold dropdowns.

A dropdown component consists of content that appears only when a button associated with the dropdown is clicked.

Table of contents


Usage guidelines

How to use
  • If the dropdown contains actionable items, those items should be native <button> or <a> elements instead of instances of the button component.
Technical notes
  • Built on top of the Popper.js library.
  • Exposes a toggleDropdown() method on the triggering element.
Content guidelines
Tooltips
  • Tooltips should outline what a feature does and what else it affects. We usually decide to add them as part of usability testing, but you can include one proactively for complex or unusual features.
  • Be concise. Keep it to 15 words or less. You can save space by using this instead of repeating the name of the input or interface element.
  • You can include an optional Learn more link to documentation for further reading. This does not count toward the word limit. Don’t link the entire tooltip.
    • Example tooltip for geo-restrictions: Restrict access to a video by geographic location. This only applies to Chorus player embeds. Learn more.
  • Avoid using pronouns, since the person working on a story or video may not be the author of it. For example, “This story is embargoed” is preferred over “Your story is embargoed.”

Attributes

An asterisk next to a value denotes that it is the default value for that attribute. Unless noted otherwise, attributes should be added to the component element directly. Boolean attributes work based on their presence or absence from the component.

<res-component booleanAttribute stringAttribute="parameter">    
  <child-element></child-element>
</res-component>
AttributeTypeDescription
for (required)stringId of element that will have dropdown attached to it
placementstringPlacement option to be passed to popper.js
  • auto
  • auto-start
  • auto-end
  • top
  • top-start
  • top-end
  • right
  • right-start
  • right-end
  • bottom
  • bottom-start
  • bottom-end
  • left
  • left-start
  • left-end
triggerstringThe event type that triggers the dropdown (currently only supports click)
  • click
  • none
designstringSpecify dropdown style
  • dark
  • none
visiblebooleanSets the inital visibility of the dropdown (added and removed programatically)
flippedbooleanAdded programatically when the placement is inverted due to space constraints
unflippablebooleanPrevent the placement from being inverted due to space contraints
ignoreParentbooleanIf present, dropdown will not close when triggering element is clicked

API

NameTypeDataDescription
togglemethod---Toggle dropdown
referenceNodepropertyelementReference to the triggering element (read only)

Events

EventDetailReturns
changeno keyevent.detail returns true if dropdown is visible, else undefined

Notes

Expects not to have specific DOM:
  • <res-button> - The res-button component should not be used inside of res-dropdowns. Use native button elements instead.

History

VersionNote
0.16.0Prevent res-button children from rendering in res-dropdowns; add styles for button and a elements inside of res-dropdowns
0.14.1Change toggle event name to change and add the unflippable attribute
0.14.0Add ignoreParent attribute, use currentColor to facilitate easier caret color changes.
0.13.0Streamline caret styles, add design attribute with options for dark and none.
0.12.0Apply new spacing scale.
0.11.10Add touchstart as an event listener for touch-enabled devices.
0.11.8Reverts 0.11.6 fix, removes drop-shadow (causing bug), darkens default border
0.11.6Use top/left positioning instead of translate3D to fix El Capitan bug.
0.9.0Emit event when dropdown toggles.
0.7.5Added teardown/build methods.
0.7.2Initial build to spec.