**[ This description is mirrored from README.md at [github.com/BrightspaceUI/dropdown](https://github.com//BrightspaceUI/dropdown/blob/v7.4.0/README.md) on 2019-05-22 ]** **Looking for SASS-based `vui-dropdown`?** It's [over here](https://github.com/Brightspace/valence-ui-dropdown/tree/sass). # d2l-dropdown [](https://www.webcomponents.org/element/BrightspaceUI/dropdown) [![Bower version][bower-image]][bower-url] [![Build status][ci-image]][ci-url] A [Polymer](https://www.polymer-project.org)-based web component for dropdown/flyouts. ## Installation `d2l-dropdown` can be installed from [Bower][bower-url]: ```shell bower install d2l-dropdown ``` ## Usage Include the [webcomponents.js](http://webcomponents.org/polyfills/) "lite" polyfill (for browsers who don't natively support web components), then import the opener and content components as needed: ```html ``` ### Dropdown Openers #### Generic Opener `d2l-dropdown` is a generic opener for dropdown content (`d2l-dropdown-content` or `d2l-dropdown-menu`) enabling alternate opener implementation using existing elements/components. Provide and indicate your own opener element with the class attribute value `d2l-dropdown-opener`. Wire-up is automatic. ```html Open! Some content... ``` If the dropdown is initially empty when it's opened, the dropdown pointer will not be positioned correctly. In such cases, the `no-auto-open` attribute may be added to the opener, enabling you to take control of when the dropdown is actually opened: ```html ... ``` ```javascript dropdown.addEventListener('click', function() { // fetch some content ... // take control of when the dropdown is actually opened dropdown.toggleOpen(); }); ``` #### Button Opener `d2l-dropdown-button` is a `d2l-button` opener for dropdown content (`d2l-dropdown-content` or `d2l-dropdown-menu`). Provide `text` for the button and content component as needed. ```html Some content... ``` * `primary` - optionally render button as primary button #### Subtle Button Opener `d2l-dropdown-button-subtle` is a `d2l-button-subtle` opener for dropdown content (`d2l-dropdown-content` or `d2l-dropdown-menu`). Provide `text` for the button and content component as needed. ```html Some content... ``` #### Context Menu Opener `d2l-dropdown-context-menu` is a simple/minimal opener for dropdown content (`d2l-dropdown-content` or `d2l-dropdown-menu`). Provide `text` for accessibility and content component as needed. Optionally, specify the `translucent` attribute for busy/rich backgrounds. ```html Some content... ``` #### More Opener `d2l-dropdown-more` is a simple/minimal opener for dropdown content (`d2l-dropdown-content` or `d2l-dropdown-menu`). Provide `text` for accessibility and content component as needed. Optionally, specify the `translucent` attribute for busy/rich backgrounds. ```html Some content... ``` #### Visible on Ancestor Behavior For busy/rich backgrounds, the `d2l-dropdown-more` and `d2l-dropdown-context-menu` openers support the [VisibleOnAncestorBehavior](https://github.com/Brightspace/d2l-polymer-behaviors-ui) that can be enabled by specifying the `visible-on-ancestor` attribute. See [VisibleOnAncestorBehavior](https://github.com/Brightspace/d2l-polymer-behaviors-ui) for more details on configuring that behavior. ```html ``` ### Dropdown Contents #### Generic Content `d2l-dropdown-content` is a generic container for dropdown content. It provides behavior such as sizing, positioning, and managing focus gain/loss. ```html Google

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

D2L ``` * `min-width` (number) - optionally override default min-width * `max-width` (number) - optionally override default max-width * `no-auto-fit` - optionally opt out of auto-sizing * `no-padding` - optionally render with no padding * `no-pointer` - optionally render without a pointer * `render-content` - optionally stamp contents into DOM immediately * `vertical-offset` - optionally provide custom offset, positive or negative * `align` (enum) - optionally align dropdown. Valid values are "start","end". If not set, the dropdown will attempt be centred * `boundary` (object) - optionally provide boundaries to where the dropdown will appear. Valid properties are "above", "below", "left", "right" ```javascript // triggered when dropdown opened content.addEventListener('d2l-dropdown-open', () => { ... }); // triggered when dropdown closed content.addEventListener('d2l-dropdown-close', () => { ... }); ``` #### Menu Content `d2l-dropdown-menu` is a container for a [d2l-menu](https://github.com/Brightspace/d2l-menu-ui) component. It provides behavior in addition to the basic behavior of `d2l-dropdown-content` such as closing the menu when menu items are selected, resetting to the root of nested menus when reopening, etc. ```html ``` ## Developing, Testing and Contributing After cloning the repo, run `npm install` to install dependencies. If you don't have it already, install the [Polymer CLI](https://www.polymer-project.org/2.0/docs/tools/polymer-cli) globally: ```shell npm install -g polymer-cli ``` To start a [local web server](https://www.polymer-project.org/2.0/docs/tools/polymer-cli-commands#serve) that hosts the demo page and tests: ```shell polymer serve ``` To lint ([eslint](http://eslint.org/) and [Polymer lint](https://www.polymer-project.org/2.0/docs/tools/polymer-cli-commands#lint)): ```shell npm run lint ``` To run unit tests locally using [Polymer test](https://www.polymer-project.org/2.0/docs/tools/polymer-cli-commands#tests): ```shell npm run test:polymer:local ``` To lint AND run local unit tests: ```shell npm test ``` [bower-url]: http://bower.io/search/?q=d2l-dropdown [bower-image]: https://badge.fury.io/bo/d2l-dropdown.svg [ci-url]: https://travis-ci.org/BrightspaceUI/dropdown [ci-image]: https://travis-ci.org/BrightspaceUI/dropdown.svg?branch=master ## Versioning Commits and PR merges to master will automatically do a minor version bump which will: * Update the version in `package.json` * Add a tag matching the new version * Create a github release matching the new version By using either **[increment major]** or **[increment patch]** notation inside your merge message, you can overwrite the default version upgrade of minor to the position of your choice.