spatial-navigation

What is this?

This is a JavaScript implementation of the Spatial Navigation Specification.

It enables users to navigate the page using the arrow keys of the keyboard (or remote control, or game pad…), instead of (or in addition to) the Tab key, the mouse cursor, or the touch screen.

Depending on the content and layout of the page, pressing one of the directional keys will either move the focus in that direction, or scroll the page, as appropriate.

For more details, see the specification or its explainer document.

Why Use the Polyfill

Eventually, we expect spatial navigation to be natively supported by browsers. However, this is not yet the case.

Until then, authors who wish to experiment with providing this feature to their users can include this polyfill in their page.

It can also be used for people interested in reviewing the specification it order to test the behavior it defines in various situations.

How to Use

Installation

npm i spatial-navigation-polyfill

We recommend only using versions of the polyfill that have been published to npm, rather than cloning the repo and using the source directly. This helps ensure the version you’re using is stable and thoroughly tested. See the changes in the polyfill so far.

If you do want to build from source, make sure you clone the latest tag!

Including the Polyfill in a page

Include the following code in your web page, and the polyfill will be included, enabling spatial navigation.

...
    <script src="/node_modules/spatial-navigation-polyfill/polyfill/spatial-navigation-polyfill.js"></script>
  </body>
</html>

Users can now user the keyboard’s arrow keys to navigate the page.

Handling Browser Events

In the polyfill, keydown event and mouseup event are used for the spatial navigation. The event handlers of those are attached to the window object.

We recommend to use it with the polyfill as below:

If you want to use those event handlers for other usages besides the spatial navigation,
- attach the event handler on the children of window object or
- call the event handler during the capturing phase of the event.
If you don’t want those events work with the spatial navigation, call preventDefault().

Using the APIs

The spatial navigation specification defines several JavaScript events and APIs. Using these is not necessary to use the polyfill, and users can start using the arrow keys as soon as the polyfill is included, but they can be convenient for authors who wish to override the default behavior in some cases. See the specification for more details.

Standard APIs

Experimental APIs

NOTE: The APIs below are non-standard and experimental features of the spatial navigation.

isContainer (element) :
- Determines whether the element is a spatial Navigation container.
- Returns true if the element is the spatial Navigation container, and false if not.
- Parameter
  - element : Required.
    - Any element.
findCandidates (element, dir, option) :
- Searchs all valid candidates for a certain direction.
- Returns a list of elements.
- Parameter
  - element : Required.
    - The currently focused element to search for candidates.
  - dir : Required.
    - The direction to find candidates.
    - It should be one of ['up', 'down', 'left', 'right'].
  - option : Optional.
    - Default value is {'mode': 'visible'}.
    - The FocusableAreasOptions to find candidates.
    - It should be {'mode': 'visible'} or { mode: 'all' }.
findNextTarget (element, dir, option) :
- Indicates what is the best element to move the focus for a certain direction.
- Returns the next target element.
  - If there is no target for the direction, it returns null.
  - If scrolling occurs, it returns the element itself.
- Parameter
  - element : Required.
    - The currently focused element to search for candidates.
  - dir : Required.
    - The direction to find candidates.
    - It should be one of ['up', 'down', 'left', 'right'].
  - option : Optional.
    - Default value is {'mode': 'visible'}.
    - The FocusableAreasOptions to find candidates.
    - It should be {'mode': 'visible'} or { mode: 'all' }.
getDistanceFromTarget (element, candidateElement, dir) :
- Calculates the distance between the currently focused element and a certain candiate element.
- Parameter
  - element : Required.
    - The currently focused element to search for candidates.
  - candidateElement : Required.
    - The candidate element which may gain the focus.
  - dir : Required.
    - The direction to find candidates.
    - It should be one of ['up', 'down', 'left', 'right'].
keyMode :
- Variable for getting or setting which key type to use for the spatial navigation.
- value
  - It should be one of ['ARROW', 'SHIFTARROW', 'NONE'].
  - In the case of using 'NONE' value, the spatial navigation feature will be turned off.