stevenvachon/scrolling-menu

A custom element for a menu that scrolls horizontally or vertically.

<scrolling-menu/>

A (native) web component for a menu that scrolls horizontally or vertically.

• Based on Shadow DOM v1 and Custom Elements v1.
• Menu items (<option>) are virtualized, meaning that only those within visible boundaries are added to the DOM tree, thereby supporting very long lists.
• Mostly unstyled, making customization simpler.

Check out the feature demo.

Installation

Node.js >= 10 is required. To install, type this at the command line:

npm install scrolling-menu

Usage

Import as an ES Module:

import 'scrolling-menu';

Import as a CommonJS Module:

require('scrolling-menu');

Instantiate via HTML:

<scrolling-menu>
  <option value="1">Label 1</option>
  <option value="2" selected>Label 2</option>
  <option value="3" disabled>Label 3</option>
</scrolling-menu>

Instantiate via JavaScript:

document.createElement('scrolling-menu').append(document.createElement('option'));

DOM Properties

direction property

Type: String
Default value: 'vertical'
The axis with which menu options follow. Possible values: 'horizontal', 'vertical'.

disabled property

Type: Boolean
Default value: false
Sets the state of user interactivity. Inspired by HTMLElement::disabled.

selectedIndex property

Type: Number
The index of the last selected option, where multiple selections are not possible. Inspired by HTMLSelectElement::selectedIndex.

Attributes

direction attribute

See direction property.

disabled attribute

See disabled property.

Events

change event

See HTMLElement change event.

input event

See HTMLElement input event.

Slots

decrement slot

Custom HTML content for the UI control that decrements the selected option.

<scrolling-menu>
  <span slot="decrement">
    <i class="some-icon"></i>
    Decrement
  </span>
</scrolling-menu>

increment slot

Custom HTML content for the UI control that increments the selected option.

<scrolling-menu>
  <span slot="increment">
    <i class="some-icon"></i>
    Increment
  </span>
</scrolling-menu>

option slot

Custom HTML content for each menu item. Instances of {{label}} and {{value}} will be interpolated.

<scrolling-menu>
  <a href="path/{{value}}" slot="option">
    <i class="some-icon"></i>
    {{label}}
  </a>
</scrolling-menu>

CSS Parts

disabled-option part

The disabled-state option part.

scrolling-menu::part(disabled-option) {
  /* … */
}

option part

The element that contains the option slot.

scrolling-menu::part(option) {
  /* … */
}

options-container part

The element that contains [elements that contain] option parts.

scrolling-menu::part(options-container) {
  /* … */
}

selected-option part

The selected-state option part.

scrolling-menu::part(selected-option) {
  /* … */
}

Compatibility

Depending on your target browsers, you may need polyfills/shims for the following:

• Array::find, Array.from, Array::includes
• attachShadow, customElements
• classList, toggleAttribute
• dispatchEvent, new Event()
• Math.trunc, Number.isNaN
• MutationObserver, ResizeObserver
• requestAnimationFrame
• <template>

FAQ

1. Why not add options and selectedOptions properties from HTMLSelectElement?
   Unfortunately, they're live HTMLElement collections that cannot be extended.