boundless-arrow-key-navigation/README.md

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

<!---
THIS IS AN AUTOGENERATED FILE. EDIT PACKAGES/BOUNDLESS-ARROW-KEY-NAVIGATION/INDEX.JS INSTEAD.
-->
# 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

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

Then use it like:


```jsx
/** @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](https://www.npmjs.com/package/boundless). This is recommended when you're getting started to avoid maintaining the package versions of several components:

```bash
npm i boundless --save
```

the ES6 `import` statement then becomes like:

```js
import { ArrowKeyNavigation } from 'boundless';
```



## Props

> Note: only top-level props are in the README, for the full list check out the [website](https://boundless.js.org/ArrowKeyNavigation).

### Required Props

There are no required props.


### Optional Props

- __`*`__ &middot; any [React-supported attribute]
  (https://facebook.github.io/react/docs/tags-and-attributes.html#html-attributes)

  Expects | Default Value
  ---     | ---
  `any` | `n/a`

- __`component`__ &middot; 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`__ &middot; allows for a particular child to be initially reachable via tabbing; only applied during first render

  Expects | Default Value
  ---     | ---
  `number` | `0`

- __`mode`__ &middot; 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`