KeyboardDirectionMixin

Purpose: map arrow and Home/End keys to semantic direction methods. This allows a developer to quickly support directional navigation in a component, and to avoid common pitfalls. For example, a component listening to presses of the Left or Right keys should take care to not handle those keys if a meta key (Command key on Macs, Windows key on Windows) or alt key (Option key on Macs, Alt key on Windows) are pressed, as that would interfere with browser navigation shortcuts.

This mixin works in the middle of the Elix render pipeline:

events → methodsmethods → setState → updates → render DOM → post-render

Expects the component to provide:

Provides the component with:

  • Mappings from direction keyboard events to direction methods.

Usage

import KeyboardDirectionMixin from 'elix/src/KeyboardDirectionMixin.js';
class MyElement extends KeyboardDirectionMixin(HTMLElement) {}

Mapping direction keys to semantic direction methods

The supported mapping of keys to direction methods is:

  • Down key → invokes symbols.goDown if vertical navigation is enabled. If the Alt key is pressed, this invokes symbols.goEnd.
  • End key → invokes symbols.goEnd.
  • Home key → invokes symbols.goStart.
  • Left key → invokes symbols.goLeft if horizontal navigation is enabled. If the meta key or alt key is pressed, the key is ignored.
  • Right key → invokes symbols.goRight if horizontal navigation is enabled. If the meta key or alt key is pressed, the key is ignored.
  • Up key → invokes symbols.goUp if vertical navigation is enabled. If the Alt key is pressed, this invokes symbols.goStart.

If your goal is to map direction semantics to selection semantics (e.g., to have direction keys navigate a list of items), you can use DirectionSelectionMixin for that purpose.

The mixin inspects a property called orientation to determine whether horizontal navigation, vertical navigation, or both are enabled. Valid values for that property are "horizontal", "vertical", or "both", respectively. If the property is not defined, the default value is "both".

API

Used by classes Carousel, CarouselSlideshow, CarouselWithThumbnails, ListBox, SlideshowWithPlayControls, SlidingPages, and TabStrip.

symbols.goDown() method

Invoked when the user wants to go/navigate down. The default implementation of this method does nothing.

symbols.goEnd() method

Invoked when the user wants to go/navigate to the end (e.g., of a list). The default implementation of this method does nothing.

symbols.goLeft() method

Invoked when the user wants to go/navigate left. The default implementation of this method does nothing.

symbols.goRight() method

Invoked when the user wants to go/navigate right. The default implementation of this method does nothing.

symbols.goStart() method

Invoked when the user wants to go/navigate to the start (e.g., of a list). The default implementation of this method does nothing.

symbols.goUp() method

Invoked when the user wants to go/navigate up. The default implementation of this method does nothing.