**[ This description is mirrored from README.md at [github.com/BrightspaceUI/menu](https://github.com//BrightspaceUI/menu/blob/v2.3.0/README.md) on 2019-05-22 ]** # d2l-menu [](https://www.webcomponents.org/element/BrightspaceUI/menu) [![Bower version][bower-image]][bower-url] [![Build status][ci-image]][ci-url] A [Polymer](https://www.polymer-project.org/1.0/)-based web component for menus. ## Installation `d2l-menu` can be installed from [Bower][bower-url]: ```shell bower install d2l-menu ``` ## 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 ``` ### Menu A basic menu can be defined using `d2l-menu` and a combination of `d2l-menu-item` and `d2l-menu-item-link`. **Important**: specify a label on your `d2l-menu` for screen-readers. ```html ``` * `label` - required to announce menu text with screen-readers **Note:** `d2l-menu` renders without an outer border since it's typically used in a context where a containing element defines a border (ex. `d2l-dropdown-menu` or side nav). ### Nested Menus Nested menus can be defined by placing a `d2l-menu` inside a `d2l-menu-item`. For nested menus, a `label` attribute is automatically applied using the text attribute of the `d2l-menu-item` that contains it - no need to duplicate this value. A "return" menu item will be added to the top of the nested menu by default. ```html ``` ### Menu Items By default, there are several menu item types provided. These include `d2l-menu-item` (for JS handlers), `d2l-menu-item-link` (for navigating), and `d2l-menu-item-checkbox`/`d2l-menu-item-radio` (for selection). While navigation can be done in JS too, `d2l-menu-item-link` gives users the ability to right-click and open in a new tab. If providing a JS handler, wire-up to the `d2l-menu-item-select` event. In addition, a `d2l-menu-item-separator` can be used to semantically separate menu items. ```html ``` The selection menu items act as you would expect a checkbox or radio item to act. Multiple checkboxes in the same menu may be selected, but only one radio item in a given `` may be selected at once (i.e. selecting one option will deselect all the other `d2l-menu-item-radio` items). ```html ``` ```html ``` * `text` - required for `d2l-menu-item` * `href` - required for `d2l-menu-item-link` * `value` - required for `d2l-menu-item-checkbox`/`d2l-menu-item-radio` * `prevent-default` - optional for `d2l-menu-item-link` - disables normal link behavior. This can help if you want both a JS handler and the browser's 'open in new tab' functionality (e.g. popup window links). * `selected` - optional for `d2l-menu-item-checkbox`/`d2l-menu-item-radio`, this will set the item to be selected by default. ```javascript menu.addEventListener('d2l-menu-item-select', function(e) { console.log('item selected:', e.target); }); ``` ## 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-menu [bower-image]: https://badge.fury.io/bo/d2l-menu.svg [ci-url]: https://travis-ci.org/BrightspaceUI/menu [ci-image]: https://travis-ci.org/BrightspaceUI/menu.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.