← Back


Polymer-based web component for a D2L menus




[ This description is mirrored from at on 2019-05-22 ]


Published on Bower version Build status

A Polymer-based web component for menus.


d2l-menu can be installed from Bower:

bower install d2l-menu


Include the webcomponents.js "lite" polyfill (for browsers who don't natively support web components), then import the opener and content components as needed:

  <script src="../webcomponentsjs/webcomponents-lite.js"></script>

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.

<d2l-menu label="Astronomy">
  <d2l-menu-item text="Introduction"></d2l-menu-item>
  <d2l-menu-item text="Searching the Heavens"></d2l-menu-item>
  <d2l-menu-item text="The Solar System"></d2l-menu-item>
  <d2l-menu-item text="Stars &amp; Galaxies"></d2l-menu-item>
  <d2l-menu-item text="The Night Sky"></d2l-menu-item>
  <d2l-menu-item text="The Universe"></d2l-menu-item>
  • 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.

<d2l-menu label="Astronomy">
  <d2l-menu-item text="Introduction"></d2l-menu-item>
  <d2l-menu-item text="Searching the Heavens"></d2l-menu-item>
  <d2l-menu-item text="The Solar System">
      <d2l-menu-item text="Formation"></d2l-menu-item>
      <d2l-menu-item text="Modern Solar System"></d2l-menu-item>
      <d2l-menu-item text="The Planets">
          <d2l-menu-item text="Mercury"></d2l-menu-item>
          <d2l-menu-item text="Venus"></d2l-menu-item>
          <d2l-menu-item text="Earth"></d2l-menu-item>
          <d2l-menu-item text="Mars"></d2l-menu-item>
          <d2l-menu-item text="..."></d2l-menu-item>
      <d2l-menu-item text="The Sun"></d2l-menu-item>
      <d2l-menu-item text="Asteroids"></d2l-menu-item>
      <d2l-menu-item text="Comets"></d2l-menu-item>
  <d2l-menu-item text="Stars &amp; Galaxies">
      <d2l-menu-item text="What is a Star?"></d2l-menu-item>
      <d2l-menu-item text="Lifecycle of a Star"></d2l-menu-item>
      <d2l-menu-item text="Binaries &amp; Multiples"></d2l-menu-item>
      <d2l-menu-item text="Star Clusters"></d2l-menu-item>
      <d2l-menu-item text="Star Death"></d2l-menu-item>
      <d2l-menu-item text="Galaxies"></d2l-menu-item>
  <d2l-menu-item text="The Night Sky"></d2l-menu-item>

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.

<d2l-menu label="Astronomy">
  <d2l-menu-item text="Introduction"></d2l-menu-item>
  <d2l-menu-item text="The Planets"></d2l-menu-item>
  <d2l-menu-item-link text="The Universe" href=""></d2l-menu-item-link>

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 <d2l-menu> may be selected at once (i.e. selecting one option will deselect all the other d2l-menu-item-radio items).

<d2l-menu label="Some Options">
  <d2l-menu-item-checkbox text="Option 1" value="1"></d2l-menu-item-checkbox>
  <d2l-menu-item-checkbox text="Option 2" value="2"></d2l-menu-item-checkbox>
  <d2l-menu-item-checkbox text="Option 3" value="3"></d2l-menu-item-checkbox>
<d2l-menu label="Some Options">
  <d2l-menu-item-radio text="Option 1" value="1" selected></d2l-menu-item-radio>
  <d2l-menu-item-radio text="Option 2" value="2"></d2l-menu-item-radio>
  <d2l-menu-item-radio text="Option 3" value="3"></d2l-menu-item-radio>
  • 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.
menu.addEventListener('d2l-menu-item-select', function(e) {
    console.log('item selected:',;

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 globally:

npm install -g polymer-cli

To start a local web server that hosts the demo page and tests:

polymer serve

To lint (eslint and Polymer lint):

npm run lint

To run unit tests locally using Polymer test:

npm run test:polymer:local

To lint AND run local unit tests:

npm test


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.


(Loading compatibility data...)

Was this helpful? Need more help?
Leave a comment or a question below. You can also join the chat on Discord or ask questions on StackOverflow.



  • d2l-colors#^3.1.2
  • d2l-hierarchical-view#^1.0.5
  • d2l-icons#^5.0.0
  • d2l-localize-behavior#^1.0.0
  • d2l-polymer-behaviors#^1.9.1
  • polymer#1 - 2
Apache License 2.0


Polymer 2.0+
Polymer 1.0+ in 0.3.7
Browser Independent