Spatial Navigation

Written: 2017-10-17, Updated: 2019-11-27

This repository is for supportive tools of Spatial Navigation such as polyfill, demo, and relevant documents. The spatial navigation spec has been migrated from WICG to CSS WG as an official draft according to the decision at the CSS WG meeting in TPAC 2018.

You can raise a spec issue in CSS WG, but also raise others(polyfill, demo, ideas) in WICG here.

Overview

Spatial navigation is the ability to navigate between focusable elements based on their position within a structured document. Spatial navigation is often called 'directional navigation' which enables four(top/left/bottom/right) directional navigation. Users are usually familiar with the 2-way navigation using both 'tab key' for the forward direction and 'shift+tab key' for the backward direction, but not familiar with the 4-way navigation using arrow keys.

Regarding TV remote control, game console pad, IVI jog dial with 4-way keys, and Web accessibility, the spatial navigation has been a rising important input mechanism in several industries.

Details

Read the Spec
Read the Explainer
Play with the Polyfill
Try the Demo and Extension tool
See the Implementation status
Give feedback on issues for spec in CSS WG or issues for others in WICG

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 in 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 to 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

Standard APIs	Feature
navigate()	Enables the author to trigger spatial navigation programmatically
spatialNavigationSearch()	Finds the element which will gain the focus within the spatial navigation container from the currently focused element
getSpatialNavigationContainer()	Gets the spatial navigation container of an element
focusableAreas()	Finds focusable elements within the spatial navigation container
Navigation Events	Occurs depending on the specific contextual behavior associated with spatial navigation
--spatial-navigation-contain	Creates customized spatial navigation containers
--spatial-navigation-action	Controls the interaction for the scrollable element
--spatial-navigation-function	Selects the navigation algorithm

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 candidate 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.

Current Status

Browser Support for Spec

The spec hasn't been implemented in any browser yet. If any update, we will add it to here.

Browser Support for Polyfill

The Spatial Navigation Polyfill has been tested and known to work in the following browsers:

49+

61+

11.1+

17+

36+

Remaining Issues

The polyfill is not yet complete. It roughly matches the specification but does not yet follow it closely, and has several known issues.

See the list of open bugs in github.

FAQ

Q. I’m not sure how the spatial navigation works.

You can see the video that shows the spatial navigation operations in the YouTube page (link).
You can see the brief description for the spatial navigation in Wikipedia (link).
In several references below, you can get the help to understand the spatial navigation operation better.

Q. Isn’t it enough just using the relevant web frameworks?

Several web frameworks and extensions for the spatial navigation have been provided so far due to no support from web engines. For examples, js-spatial-navigation made by Mozilla seems one of the frameworks and its quality would be good to support the features of the spatial navigation. Spotlight library implemented by LGE is also an instance of the frameworks for the spatial navigation, even though it was deprecated now. However, the support of spatial navigation from web frameworks has some limits as follows:
- Difficult to align native scroll behavior when moving the focus to an element out of view
- Difficult to align native focus method for a11y support
- Performance degradation due to the expensive cost of DOM Access
- Inconsistency of user experience (various kinds of frameworks)
- Impossible to control isolated frames like iframe and shadow DOM

Q. The spatial navigation seems not the general feature esp. in mobile with no physical key-based interface.

Honestly, the mobile(feature phone) has been a first citizen of the spatial navigation about ten years old. Before touch-based interface, the majority of interface for mobile was the key-based interface. Recently(2018-2019), KaiOS-based feature phones have been propagated mainly in several developing countries such as Africa, India, and Southeast Asia. The devices doesn't support a touch interface, so users need to use the arrow keys to select a item on all applications including a browser.
In the future, the input mechanism for smart devices will change to something like voice command, hand gesture, and gaze direction, but the key-based interface will never disappear, even though it'll be used as a secondary method. The key-based interface used to be evaluated as one of the most intuitive ways with a strong sense feedback of finger after pushing a key, as if it's inconvenient a touch-based keyboard without any physical keys.

Q. I would like to raise an issue or idea about spatial navigation.

Please put any question via the following two links:
Issues in CSS WG for spec issues
Issues in WICG WG for any other issues
Everything for the spatial navigation is welcome! :D

Reference

WICD Core 1.0 Working Group Note (W3C)
- https://www.w3.org/TR/WICD/#focus-handling
A JavaScript library targeting to Firefox OS (Mozilla)
- https://github.com/luke-chang/js-spatial-navigation
A JavaScript library targeting to LG webOS platform (LG Electronics)
- https://github.com/enactjs/enact/tree/master/packages/spotlight
- https://github.com/enyojs/spotlight (deprecated a few years ago)
Pass the Remote: User Input on TV Devices (Netflix Tech Blog)
- https://medium.com/netflix-techblog/pass-the-remote-user-input-on-tv-devices-923f6920c9a8
Implementing TV remote control navigation (MDN)
- https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS_for_TV/TV_remote_control_navigation
Spatial Navigation in the web (slides presented in BlinkOn 8)
- https://docs.google.com/presentation/d/1x4RaJIzTYeX0-nySVuq0TThe5shfmOsjbGIMrZJLBTE/edit
Focus interaction in UIKit (Apple)
- https://developer.apple.com/documentation/uikit/focus_interactions
Focus navigation with keyboard, gamepad, and accessibility tools (MS)
- https://docs.microsoft.com/en-us/windows/uwp/input-and-devices/managing-focus-navigation
Designing for Xbox and TV (MS)
- https://docs.microsoft.com/en-us/windows/uwp/input-and-devices/designing-for-tv

Name		Name	Last commit message	Last commit date
Latest commit History 1,061 Commits
.github		.github
blink_impl		blink_impl
demo		demo
docs		docs
images		images
polyfill		polyfill
resources		resources
tests		tests
tools/chrome-extension		tools/chrome-extension
.DS_Store		.DS_Store
.gitignore		.gitignore
.npmignore		.npmignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE.md		LICENSE.md
README.md		README.md
implStatus.md		implStatus.md
package-lock.json		package-lock.json
package.json		package.json
w3c.json		w3c.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Spatial Navigation

Overview

Details

Why Use the Polyfill