Spatial Navigation

npm stat npm version

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.


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.


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


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>

Users can now use 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:

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.

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:


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.


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

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

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

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