boundless-arrow-key-navigation

ArrowKeyNavigation

A higher-order component for arrow key navigation on a grouping of children.

ArrowKeyNavigation is designed not to care about the component types it is wrapping. Due to this, you can pass whatever HTML tag you like into props.component or even a React component you've made elsewhere. Additional props passed to <ArrowKeyNavigation ...> will be forwarded on to the component or HTML tag name you've supplied.

The children, similarly, can be any type of component.

Installation

npm i boundless-arrow-key-navigation --save

Then use it like:

import React from 'react';
import ArrowKeyNavigation from 'boundless-arrow-key-navigation';

export default class ArrowKeyNavigationDemo extends React.PureComponent {
    state = {
        items: ['lorem', 'ipsum', 'dolor'],
    }

    render() {
        return (
            <div className='spread'>
                <section>
                    <h6>Horizontal-only</h6>
                    <ArrowKeyNavigation className='demo-loose-list' mode={ArrowKeyNavigation.mode.HORIZONTAL}>
                        {this.state.items.map((item) => <span key={item}>{item}</span>)}
                    </ArrowKeyNavigation>
                </section>

                <section>
                    <h6>Vertical-only</h6>
                    <ArrowKeyNavigation component='ul' mode={ArrowKeyNavigation.mode.VERTICAL}>
                        {this.state.items.map((item) => <li key={item}>{item}</li>)}
                    </ArrowKeyNavigation>
                </section>

                <section>
                    <h6>Both directions</h6>
                    <ArrowKeyNavigation component='ol' mode={ArrowKeyNavigation.mode.BOTH}>
                        {this.state.items.map((item) => <li key={item}>{item}</li>)}
                    </ArrowKeyNavigation>
                </section>

                <section>
                    <h6>Second child active by default</h6>
                    <ArrowKeyNavigation component='ul' mode={ArrowKeyNavigation.mode.VERTICAL} defaultActiveChildIndex={1}>
                        {this.state.items.map((item) => <li key={item}>{item}</li>)}
                    </ArrowKeyNavigation>
                </section>

                <section>
                    <h6>Ignored child (horizontal rule)</h6>
                    <ArrowKeyNavigation>
                        <div>lorem</div>
                        <hr tabIndex='-1' />
                        <div>dolor</div>
                    </ArrowKeyNavigation>
                </section>
            </div>
        );
    }
}

ArrowKeyNavigation can also just be directly used from the main Boundless library. This is recommended when you're getting started to avoid maintaining the package versions of several components:

npm i boundless --save

the ES6 import statement then becomes like:

import { ArrowKeyNavigation } from 'boundless';

Props

Note: only top-level props are in the README, for the full list check out the website.

Required Props

There are no required props.

Optional Props

• * ・ any React-supported attribute

  Expects | Default Value

  •   | -
    

  any | n/a

• component ・ any valid HTML tag name or a React component factory, anything that can be passed as the first argument to React.createElement

  Expects | Default Value

  •   | -
    

  string or function | 'div'

• defaultActiveChildIndex ・ allows for a particular child to be initially reachable via tabbing; only applied during first render

  Expects | Default Value

  •   | -
    

  number | 0

• mode ・ controls which arrow key events are captured to move active focus within the list:

  Mode	Keys
  ArrowKeyNavigation.mode.BOTH	⬅️ ➡️ ⬆️ ⬇️
  ArrowKeyNavigation.mode.HORIZONTAL	⬅️ ➡️
  ArrowKeyNavigation.mode.VERTICAL	⬆️ ⬇️

  Note: focus loops when arrowing past one of the boundaries; tabbing moves the user away from the list.

  Expects | Default Value

  •   | -
    

  ArrowKeyNavigation.mode.BOTH or ArrowKeyNavigation.mode.HORIZONTAL or ArrowKeyNavigation.mode.VERTICAL | ArrowKeyNavigation.mode.BOTH