device-navigation v3.1.1

device-navigation

Allows navigation between HTML elements in one or two dimensions with non-mouse devices and unifies it with the mouse navigation experience.

Note that this is specifically built for usage within lit or element-vir HTML templates.

• demo
• docs
• code
• npm

Install

npm i device-navigation

Usage

1. Mark each element that should be navigable with the nav() directive:

   import {html} from 'element-vir';
   import {nav} from 'device-navigation';
   
   const myTemplate = html`
       <div ${nav()}></div>
   `;

2. Construct a NavController instance, passing in an element which is parent of all navigable elements:

   import {assert} from '@augment-vir/assert';
   import {html} from 'element-vir';
   import {nav, NavController} from 'device-navigation';
   
   const myTemplate = html`
       <main>
           <div ${nav()}></div>
           <div ${nav()}></div>
           <div ${nav()}></div>
       </main>
   `;
   
   function setNavController() {
       const main = document.querySelector('main');
       assert.isDefined(main);
       return new NavController(main);
   }

3. Call NavController methods from within listeners:

   import {html} from 'element-vir';
   import {nav, NavController, NavDirection} from 'device-navigation';
   
   const myTemplate = html`
       <main>
           <div ${nav()}></div>
           <div ${nav()}></div>
           <div ${nav()}></div>
       </main>
   `;
   
   function setupListeners(navController: NavController) {
       window.addEventListener('keydown', (event) => {
           if (event.code === 'ArrowUp') {
               navController.navigate({
                   allowWrapping: true,
                   direction: NavDirection.Up,
               });
           } else if (event.code === 'ArrowDown') {
               navController.navigate({
                   allowWrapping: true,
                   direction: NavDirection.Down,
               });
           } else if (event.code === 'Enter') {
               navController.enterInto();
           }
           // etc.
       });
   }

To see a full example, see the demo element.