NavigableContainer

NavigableContainer is a React component to render a container navigable using the keyboard. Only things that are focusable can be navigated to. It will currently always be a div.

NavigableContainer is exported as two components: NavigableMenu and TabbableContainer. NavigableContainer itself is not exported. NavigableMenu and TabbableContainer have the props listed below. Any other props will be passed through to the div.

Props

These are the props that NavigableMenu and TabbableContainer. Any props which are specific to one component are labelled appropriately.

cycle: boolean

A boolean which tells the component whether or not to cycle from the end back to the beginning and vice versa.

• Required: No
• default: true

eventToOffset: ( event: KeyboardEvent ) => -1 | 0 | 1 | undefined

(TabbableContainer only)
Gets an offset, given an event.

• Required: No

onKeyDown: ( event: KeyboardEvent ) => void

A callback invoked on the keydown event.

• Required: No

onNavigate: ( index: number, focusable: HTMLElement ) => void

A callback invoked when the menu navigates to one of its children passing the index and child as an argument

• Required: No

orientation: 'vertical' | 'horizontal' | 'both'

(NavigableMenu only)
The orientation of the menu. It could be “vertical”, “horizontal”, or “both”.

• Required: No
• Default: "vertical"

Components

NavigableMenu

A NavigableMenu allows movement up and down (or left and right) the component via the arrow keys. The tab key is not handled. The orientation prop is used to determine whether the arrow keys used are vertical, horizontal or both.

The NavigableMenu by default has a menu role and therefore, in order to function as expected, the component expects its children elements to have one of the following roles: 'menuitem' | 'menuitemradio' | 'menuitemcheckbox'.

TabbableContainer

This component is deprecated. For focus trapping, consider the useConstrainedTabbing hook from @wordpress/compose.

A TabbableContainer will only be navigated using the tab key. Every intended tabstop must have a tabIndex 0.

Usage

import {
    NavigableMenu,
    TabbableContainer,
    Button,
} from '@wordpress/components';

function onNavigate( index, target ) {
    console.log( `Navigates to ${ index }`, target );
}

const MyNavigableContainer = () => (
    <div>
        <span>Navigable Menu:</span>
        <NavigableMenu onNavigate={ onNavigate } orientation="horizontal">
            <Button variant="secondary">Item 1</Button>
            <Button variant="secondary">Item 2</Button>
            <Button variant="secondary">Item 3</Button>
        </NavigableMenu>

        <span>Tabbable Container:</span>
        <TabbableContainer onNavigate={ onNavigate }>
            <Button variant="secondary" tabIndex="0">
                Section 1
            </Button>
            <Button variant="secondary" tabIndex="0">
                Section 2
            </Button>
            <Button variant="secondary" tabIndex="0">
                Section 3
            </Button>
            <Button variant="secondary" tabIndex="0">
                Section 4
            </Button>
        </TabbableContainer>
    </div>
);