boundless-arrow-key-navigation

ArrowKeyNavigation

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:

/** @jsx createElement */

import { createElement, PureComponent } from 'react';
import ArrowKeyNavigation from 'boundless-arrow-key-navigation';

export default class ArrowKeyNavigationDemo extends 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] (https://facebook.github.io/react/docs/tags-and-attributes.html#html-attributes)

  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