Title: CSS Spatial Navigation Level 1
Shortname: css-nav
Level: 1
Status: ED
Work Status: exploring
Group: csswg
TR: https://www.w3.org/TR/css-nav-1/
ED: https://drafts.csswg.org/css-nav-1/
Previous Version: https://www.w3.org/TR/2019/WD-css-nav-1-20190423/
Previous Version: https://www.w3.org/TR/2019/WD-css-nav-1-20191126/
Editor: Jihye Hong, LG Electronics, jh.hong@lge.com, w3cid 79168
Editor: Florian Rivoal, Invited Expert, https://florian.rivoal.net, w3cid 43241
Abstract: This specification defines a general model for navigating the focus using the arrow keys,
    as well as related CSS, JavaScript features and Events.
At risk: {{getSpatialNavigationContainer()}}
At risk: {{focusableAreas()}}
At risk: 'spatial-navigation-contain'
At risk: ''spatial-navigation-action: scroll''
At risk: 'spatial-navigation-function'

spec: ui-events; urlPrefix: https://w3c.github.io/uievents/;
    type: event;
        text: keydown
        text: click
    type: dfn;
        text: event target
spec: html; urlPrefix: https://html.spec.whatwg.org/multipage/;
    urlPrefix: interaction.html
        type: dfn;
            text: control group
            text: currently focused area of a top-level browsing context
            text: DOM anchor
            text: expressly inert
            text: focusable area
            text: sequential focus navigation order
            text: sequential focus navigation starting point
            text: sequential navigation search algorithm
            text: tabindex; url: #attr-tabindex
    urlPrefix: rendering.html
        type: dfn;
            text: being rendered; url: #being-rendered
    urlPrefix: semantics-other.html
        type: dfn;
            text: actually disabled; url: #concept-element-disabled
    urlPrefix: browsers.html
        type: dfn;
            text: browsing context
    urlPrefix: dom.html
        type: dfn;
            text: the body element; url: #the-body-element-2
    urlPrefix: infrastructure.html
        type: dfn;
            text: removed; url: #nodes-are-removed
spec: dom; urlPrefix: https://dom.spec.whatwg.org/
    type: dfn;
        text: document element
spec: feature-policy; urlPrefix: https://w3c.github.io/webappsec-feature-policy/;
    type: dfn;
        text: is enabled; url: #is-feature-enabled
        text: default allowlist; url: #default-allowlist
        text: policy-controlled feature; url: #policy-controlled-feature
spec: overscroll-behavior; urlPrefix: https://drafts.csswg.org/css-overscroll-behavior-1/;
    type: dfn;
        text: scroll boundary
spec: css2; urlPrefix: https://drafts.csswg.org/css2/
    urlPrefix: box.html
        type: dfn;
            text: border box; url: #x14
    urlPrefix: zindex.html
        type: dfn;
            text: painting order; url: #painting-order

spec:html; type:method; for:HTMLOrSVGElement; text:focus()

Introduction

Module interaction

Overview

This section is not normative. Using a UA-defined mechanism (typically arrow keys, possibly in combination with modifier keys like Shift or Control), the user may ask the user agent to navigate in a particular direction. This will either move the focus from its current location to a new focusable item in the direction requested, or scroll if there is no appropriate item. More specifically, the user agent will first search for visible and focusable items in the direction indicated within the current spatial navigation container (by default, the root element, scrollable elements, and iframes, but other elements can be made into spatial navigation containers using the 'spatial-navigation-contain' property). If it finds any, it will pick the best one for that direction, and move the focus there. If it does not, it will scroll the spatial navigation container in the requested direction instead of moving focus. Doing so may uncover focusable elements which would then be eligible targets to move the focus to next time spatial navigation in the same direction is requested. If the spatial navigation container cannot be scrolled, either because it is not a scrollable element or because it is already scrolled to the maximum in that direction, the user agent will select the next spatial navigation container up the ancestry chain, and recursively repeat the above process until it finds some element to focus or scroll, or reaches the root element. Note: As a consequence of this processing model, the elements that are reachable by sequential navigation and by spatial navigation are almost the same. Elements that are currently outside of the viewport of a scrollable element can only be reached by spatial navigation once they have been scrolled into view. Therefore, elements that cannot be scrolled into view by default.

At key points during this search for the appropriate response to the spatial navigation request, the user agent will fire events. These enable the author to prevent the upcoming action (by calling {{preventDefault()}}), and if desired to provide an alternate action, such as using the {{HTMLOrSVGElement/focus()}} method on a different element of the author's choosing. To help the author write such alternate actions, and as part of exposing underlying platform primitives as per the Extensible Web principles, this specification also defines JavaScript APIs that expose key constructs of the underlying model. See [[#js-api]] for details about the JavaScript API, [[#events-nav-type]] for details about the various events, and [[#declarative]] for details about the CSS properties.

This example shows how a series of focusable elements arranged in a scrollable element would be navigated when using spatial navigation. For the sake of keeping the description simple, this example assumes a user agent where spatial navigation is triggered using arrow keys.

On the left of figure 2, "Box 2" is focused. Pressing the ArrowDown key moves the focus to "Box 3" without scrolling because "Box 3" is visible in the scrollport of the spatial navigation container.

On the first of figure 3, under "Box 3", there isn't any visible element in the scrollport. Therefore, the effect of pressing the ArrowDown is to scroll down, as shown in the second. The next press of the ArrowDown key makes "Box 4" come into the scrollport, and the focus will move to it when there is additional pressing the ArrowDown, as the fourth. This example uses the markup as follows:

        #scroller {
            width: 700px;
            height: 700px;
            overflow-x: hidden;
            overflow-y: auto;
        }

        .box {
            width: 150px;
            height: 110px;
            background-color: blue;
        }

        .box:focus {
            background-color: red;
        }
    

        <div id="scroller">
            <div class="box" tabindex="0">Box 1</div>
            <div class="box" tabindex="0">Box 2</div>
            <div class="box" tabindex="0">Box 3</div>
            <div class="box" tabindex="0">Box 4</div>
        </div>
    

Triggering Spatial Navigation

JavaScript API

Triggering Navigation Programmatically

The {{Window/navigate()}} method enables the author to trigger spatial navigation programmatically, as if the user had done so manually (for instance, by pressing the arrow keys in a browser where that is the way to trigger spatial navigation). Note: As this triggers the same processing model as manual navigation, all the same results should be expected: the same chain of events will be fired and the same element will be scrolled or focused. Note: The author can use this to trigger spatial navigation based on a different UI mechanism than the one assigned by the user agent, such as mapping to different keys, or triggering spatial navigation from a clickable on-screen directional pad, or in reaction to other events than UI ones. It could also be used when an author wants to interrupt navigation to do some asynchronous operation (e.g. load more content in an infinite scroller) then resume the navigation where they canceled. Note: This API is also useful for testing purposes, as there it is difficult to trigger spatial navigation that does not depend on vendor specific UI conventions.

enum SpatialNavigationDirection {
    "up",
    "down",
    "left",
    "right",
};

partial interface Window {
    undefined navigate(SpatialNavigationDirection dir);
};

When the navigate(dir) method is called, the user agent must run the following step: * If direction dir is "up", "down", "left", or "right", run the spatial navigation steps in dir. Issue(3387): The name of this API is under discussion

Low level APIs

These APIs are designed to be low level constructs following the processing model closely. As such, they should be easy to use by the author who wants to extend or override the way spatial navigation works.

enum FocusableAreaSearchMode {
    "visible",
    "all"
};

dictionary FocusableAreasOption {
    FocusableAreaSearchMode mode;
};

dictionary SpatialNavigationSearchOptions {
    sequence<Node>? candidates;
    Node? container;
};

partial interface Element {
    Node getSpatialNavigationContainer();
    sequence<Node> focusableAreas(optional FocusableAreasOption option = {});
    Node? spatialNavigationSearch(SpatialNavigationDirection dir, optional SpatialNavigationSearchOptions options = {});
};

Note: The way the direction is expressed allows us to expand to more than 4-way navigation later if this is found necessary. More directional keywords or a numerical angle could be added. Note: the {{focusableAreas()}} and {{getSpatialNavigationContainer()}} methods are at-risk. When these methods are called, the user agent must run the steps described below:

: getSpatialNavigationContainer() :: 1. Return the nearest ancestor of the element that is a spatial navigation container, or the document if the nearest spatial navigation container is the viewport. Note: If the element is a spatial navigation container, {{getSpatialNavigationContainer()}} also returns the nearest spatial navigation container, not the element itself.

: focusableAreas(option) :: 1. Let visibleOnly be false if option is present and its value is equal to 'all', or true otherwise. 2. Let areas be the result of finding focusable areas within the element with visibleOnly as argument. 4. Return areas

The following code shows how to get all the visible focusable elements in the current page using {{Element/focusableAreas()}}. If the method finds a spatial navigation container, it recursively finds focusable areas inside it. Because the value of the {{FocusableAreasOption/mode}} attribute in this method is visible, the focusable elements which aren't inside the scrollport are excluded from the result.

    <body>
        <button></button>
        <div style="width:300px; height:200px; overflow-x: scroll;">
            <button style="left:25px;"></button>
            <button style="left:150px;"></button>
            <button style="left:350px;"></button>
        </div>
    </body>
    

        const focusableAreas = document.body.focusableAreas({mode: 'visible'});
        focusableAreas && focusableAreas.forEach(focusable => {
          focusable.style.outline = '5px solid red';
        });
    

The figure below is the result of this code.

: spatialNavigationSearch(dir, options) :: 1. Let direction be the value of dir. 2. Let container be * if the value of {{SpatialNavigationSearchOptions/container}} attribute of options is not null, * itself, if it is spatial navigation container. * its nearest spatial navigation container ancestor, otherwise. * else the element's nearest spatial navigation container ancestor. 3. Let areas be * the value of {{SpatialNavigationSearchOptions/candidates}} attribute of options if it is not null, * result of finding focusable areas within container otherwise. 4. Return the result of selecting the best candidate among areas within container in direction from the element. Note: When neither a container nor a list of candidates is provided, this only searches through the visible focusable areas of the nearest spatial navigation container ancestor. If there isn't any, this does not climb further up the ancestry chain, and the result will be null.

Navigation Events

Interface NavigationEvent

The {{NavigationEvent}} interface provides specific contextual information associated with spatial navigation. To create an instance of the {{NavigationEvent}} interface, use the {{NavigationEvent}} constructor, passing an optional {{NavigationEventInit}} dictionary.

[Exposed=Window]
interface NavigationEvent : UIEvent {
    constructor(DOMString type,
                optional NavigationEventInit eventInitDict = {});
    readonly attribute SpatialNavigationDirection dir;
    readonly attribute EventTarget? relatedTarget;
};

dictionary NavigationEventInit : UIEventInit {
    SpatialNavigationDirection dir;
    EventTarget? relatedTarget = null;
};

Navigation Event Types

This section and its subsections are not normative. The Navigation event types are summarized below. For full normative details, see [[#processing-model]].

navbeforefocus

This event occurs when there is a valid result of selecting the best candidate.

Type	navbeforefocus
Interface	{{NavigationEvent}}
Bubbles	Yes
Cancelable	Yes
Attributes of the event	{{Event}}.{{Event/target}} The focused element or if no element focused, then the body element if available, otherwise the root element {{NavigationEvent}}.{{NavigationEvent/relatedTarget}} The DOM anchor of the focusable area that will be focused {{NavigationEvent}}.{{NavigationEvent/dir}} The direction of the navigation as requested by the user

The user agent dispatches navbeforefocus event before spatial navigation moves the focus. The event target is the element which has focus and the {{NavigationEvent/relatedTarget}} is the element which is about to receive focus. If navigation-override is disabled in the [=node document=] of eventTarget for the origin of the [=active document=] of the [=top-level browsing context=], this event won't be dispatched.

This example shows the [=event order=] when pressing the ArrowRight key. For the sake of keeping the description simple, this example assumes a user agent where spatial navigation is triggered using arrow keys.

	Event type	{{KeyboardEvent}}.{{KeyboardEvent/key}}	Notes
1	keydown	ArrowRight	MUST be a key which can activate spatial navigation, such as the arrow keys, or spatial navigation is not activated.
2	navbeforefocus		Sent if the candidates for spatial navigation is not null, or this is not generated.
3	focusin		Sent before the target element receives focus.
4	focus		Sent after the target element receives focus.

The following code changes the behavior of spatial navigation so that when a scroll container would get focused, if it has at least one visible focusable descendant, the focus is automatically transferred to it, recursively.

    document.addEventListener('navbeforefocus', e => {
        e.preventDefault();

        let nextTarget = e.relatedTarget;
        if (isSpatialNavigationContainer(nextTarget)) {
            const areas = nextTarget.focusableAreas();

            if (areas.length > 0) {
                nextTarget = nextTarget.spatialNavigationSearch(e.dir, { candidates: areas });
            }
        }
        nextTarget.focus();
    });

    function isSpatialNavigationContainer(element) {
        return (!element.parentElement) ||
            (element.nodeName === 'IFRAME') ||
            (isScrollContainer(element)) ||
            (isCSSSpatNavContain(element));
    }
    

navnotarget

This event occurs before going up the tree to search candidates in the nearest ancestor spatial navigation container when spatial navigation has failed to find any candidate within the current spatial navigation container, and in cases where the spatial navigation container is scrollable, when it cannot be scrolled further.

Type	navnotarget
Interface	{{NavigationEvent}}
Bubbles	Yes
Cancelable	Yes
Attributes of the event	{{Event}}.{{Event/target}} The focused element or if no element focused, then the body element if available, otherwise the root element {{NavigationEvent}}.{{NavigationEvent/relatedTarget}} The spatial navigation container that was searched in. {{NavigationEvent}}.{{NavigationEvent/dir}} The direction of the navigation as requested by the user

The user agent dispatches navnotarget event with initializing the event target as the element which has focus and the {{NavigationEvent/relatedTarget}} as spatial navigation container of the event target. If navigation-override is disabled in the [=node document=] of eventTarget for the origin of the [=active document=] of the [=top-level browsing context=], this event won't be dispatched.

This example shows the [=event order=] when pressing the ArrowDown key in the situation like the following figure. For the sake of keeping the description simple, this example assumes a user agent where spatial navigation is triggered using arrow keys.

	Event type	Event target	relatedTarget	Notes
1	keydown	#box2	N/A	MUST be a key which can activate spatial navigation, such as the arrow keys, otherwise spatial navigation is not triggered.
2	navnotarget	#box2	#scrollContainer	Sent if #scrollContainer doesn't contain any candidate and cannot be scrolled, otherwise this would not be generated.
3	navbeforefocus	#box2	#box3	Sent if the candidates in #container is not null, otherwise this would not be fired.
4	focusin	#box3	#box2	Sent before the target element receives focus.
5	focus	#box3	#box2	Sent after the target element receives focus.

The result of this example is the figure as follows:

This example uses the markup as follows:

        #container {
            width: 900px;
            height: 1400px;
        }

        #scrollContainer {
            width: 700px;
            height: 700px;
            overflow-x: hidden;
            overflow-y: auto;
        }

        .item {
            width: 150px;
            height: 110px;
            background-color: blue;
        }

        .item:focus {
            background-color: red;
        }
    

        <div id="container">
            <div id="scrollContainer">
                <div id="box1" class="item" tabindex="0">Box 1</div>
                <div id="box2" class="item" tabindex="0">Box 2</div>
            </div>
            <div id="box3" class="item" tabindex="0">Box 3</div>
        </div>
   

The following code changes the behavior of spatial navigation to trap the focus within a spatial navigation container which is vertically scrollable. When no further focusable elements can be found in the requested direction and the spatial navigation container cannot be scrolled any further, the focus loops back to the other side instead of moving outside of it. However, the focus can still be moved outside by sequential navigation, mouse interaction, or programmatic calls to {{focus()}}.

    scrollContainer.addEventListener('navnotarget', e => {
        let nextTarget = null;
        const verticalDir = ['up', 'down'];
        const candidates = e.relatedTarget.focusableAreas({'mode': 'all'});

        // Prevent default only when navigation direction is on y-axis
        if (verticalDir.includes(e.dir) && (candidates.length > 0)) {
            e.preventDefault();

            if (e.dir === 'down') {
                nextTarget = candidates[0];
            } else if (e.dir === 'up') {
                nextTarget = candidates[candidates.length-1];
            }
            nextTarget.focus();
        }
    });
    

The navigation-override policy-controlled feature

Processing Model

Glossary

Groupings of elements

Navigation

Focus Navigation Heuristics

    distance = euclidean + displacement - alignment - sqrt(Overlap)

Name: spatial-navigation-contain
Value: auto | contain
Initial: auto
Inherited: no
Animation Type: discrete

        <div>
            <button>Previous Week</button>
            <table>
                <tr><td><th>M<th>T<th>W<th>T<th>F<th>S<th>S
                <tr><td>0-6<td><td><td><td><td><td><td><a href="#">Foo</a>
                <tr><td>6-9<td><a href="#">Bar</a><td><td><td><td><td><td>
                <tr><td>9-12<td><td><a href="#">Bat</a><td><td><td><td><td>
                <tr><td>12-18<td><td><td><td><td><td><td>
                <tr><td>18-21<td><td><td><td><td><td><td><a href="#">Woo</a>
                <tr><td>21-24<td><td><td><td><td><td><a href="#">Baz</a><td>
            </table>
            <button>Next Week</button>
        </div>
    

Controlling the interaction with scrolling: the 'spatial-navigation-action' property

Name: spatial-navigation-action
Value: auto | focus | scroll
Initial: auto
Applies to: scroll containers
Inherited: no
Animation Type: discrete

auto

If there are visible focusable elements within the [=scroll container=] in the direction requested, the closest one becomes focused. Otherwise, the [=scroll container=] is scrolled in the direction requested.

focus

The focus is moved to the nearest focusable element within the [=scroll container=], regardless of whether it is visible. If there are none, the scroll container is not scrolled, and the search continues up the ancestry chain instead. Note: The [=scroll container=] may be scrolled as a side effect of focusing an element which was previously not in view, but it will not be directionally scrolled. Note: If the ''spatial-navigation-action/focus'' value is given to 'spatial-navigation-action', navnotarget event occurs when there isn’t any visible candidate in the given direction within the viewport of the spatial navigation container even if the container can be scrolled more.

scroll

If the currently focused element is not itself a [=scroll container=], this value on an ancestor [=scroll container=] has the same effect as ''spatial-navigation-action/auto''. If the currently focused element is a [=scroll container=], it is scrolled in the direction requested without changing which element is in focus, regardless of the presence of focusable descendants. Note: This means that spatial navigation can be used to move the focus to a [=scroll container=] and to scroll it, but not to move the focus to its descendants. However, if the focus is moved to a descendant by some other mean (such as pressing the Tab key or using the <{{HTMLOrSVGElement/focus()}}> method) spatial navigation can be used to move the focus to other focusable descendants. Note: The ''spatial-navigation-ation/scroll'' value is at-risk.

In this example, a scrollable container is specified with spatial-navigation-action: focus. Inside the container, there is an element which is out of the view within a scrollport. Pressing the down arrow key moves the focus directly to it without scrolling manually.

        <div class='scroller'>
            <button class='item'>Box 1</button>
            <button class='item'>Box 2</button>
            <button class='item'>Box 3</button>
        </div>
    

        .scroller {
            display: grid;
            grid-template-columns: repeat(1, 1fr);
            height: 300px;
            width: 200px;
            overflow-y: scroll;
            spatial-navigation-action: focus;
        }
        .item {
            height: 100px;
            width: 100px;
            margin: 50px auto;
            background-color: blue;
        }
        :focus {
            background-color: red;
        }
    

Selecting the navigation algorithm: the 'spatial-navigation-function' property

Name: spatial-navigation-function
Value: normal | grid
Initial: normal
Applies to: spatial navigation containers
Inherited: no
Animation Type: discrete

normal

Moves the focus with the default focus navigation algorithm defined by UA. In general, the focus moves to the element with the closest distance calculated by finding the shortest distance.

grid

Moves the focus to the element which is aligned most in the navigation direction. * If there are more than one aligned candidates in the navigation direction, select the element with the closest distance along the axis which corresponds to the navigation direction. In case of multiple elements with the same distance, select the element with the minimum amount of alignment. * Else if there isn't any aligned candidate in a given direction, select the element with the closest distance along the axis which corresponds to the navigation direction. In case of multiple elements with the same distance, select the element with the minimum distance along the axis which is orthogonal to the navigation direction.

This example shows how the focus moves differently by the value of spatial-navigation-function.

Let the element which contains "A", "B" and "C" is the spatial navigation container. When the user presses the down arrow key, if normal value is given to spatial-navigation-function of the element, the focus will move to "B". Otherwise, grid value was specified to the element, the focus will move to "C".

Appendix A. Scroll extensions

Appendix B. Privacy and Security Considerations

Does this specification deal with personally-identifiable information?

No.

Does this specification deal with high-value data?

No.

Does this specification introduce new state for an origin that persists across browsing sessions?

No.

Does this specification expose persistent, cross-origin state to the web?

No.

Does this specification expose any other data to an origin that it doesn’t currently have access to?

Mostly, no. The one exception identified would be in the following scenario: if the author uses `window.navigate` while the focus is in a cross origin iframe, if they don't get an event at all it means that either there was something scrollable or focusable within the iframe, as the only case where they'd get an event is when the search didn't find anything at all goes up the tree. This is so limited information that it does not seem it would introduces real a security risk, but it is as far as the editors can tell information that the author could not get could not get otherwise.

Does this specification enable new script execution/loading mechanisms?

No.

Does this specification allow an origin access to a user’s location?

No.

Does this specification allow an origin access to sensors on a user’s device?

No.

Does this specification allow an origin access to aspects of a user’s local computing environment?

No.

Does this specification allow an origin access to other devices?

No.

Does this specification allow an origin some measure of control over a user agent’s native UI?

No control is given over the appearance of the user agent's UI. Some control is given over how the user agent performs spatial navigation, which may be considered part of its user interface. This is intentional, to let the author tailor the behavior of spatial navigation to their pages. To prevent malicious the author to interfere with the users' desire to control focus and navigate the document, this overriding mechanism is disabled by default for cross-origin iframes. See [[#policy-feature]].

Does this specification expose temporary identifiers to the web?

No.

Does this specification distinguish between behavior in first-party and third-party contexts?

No.

How should this specification work in the context of a user agent’s "incognito" mode?

No Difference.

Does this specification persist data to a user’s local device?

No.

Does this specification have a "Security Considerations" and "Privacy Considerations" section?

Yes, this is the section you are reading now.

Does this specification allow downgrading default security characteristics?

It does not allow downgrading any unrelated security mechanism. It **does** allow the author to opt into allowing the events needed to override the default behavior of spatial navigation in cross origin iframes they trust using [[feature-policy]]. See [[#policy-feature]].

Acknowledgements

Changes