Arrow Navigation React

A light and performant React implementation for @arrow-navigation/core package.

Installation

1npm install --save @arrow-navigation/react @arrow-navigation/core
2
3# or
4
5yarn add @arrow-navigation/react @arrow-navigation/core

Disclaimer

The @arrow-navigation/react package is a wrapper for the @arrow-navigation/core package. It is not a replacement for the @arrow-navigation/core package. You must install both packages to use the @arrow-navigation/react package.

Check peer dependencies for more information about the @arrow-navigation/core package and versions.

Usage

1import React from 'react'
2import {
3  initArrowNavigation,
4  FocusableElement,
5  FocusableGroup
6} from '@arrow-navigation/react'
7
8initArrowNavigation()
9
10const App = () => {
11  return (
12    <div>
13      <FocusableGroup id="group-1">
14        <FocusableElement id="btn-1">
15          Button 1
16        </FocusableElement>
17        <FocusableElement id="btn-2">
18          Button 2
19        </FocusableElement>
20        <FocusableElement id="btn-3">
21          Button 3
22        </FocusableElement>
23      </FocusableGroup>
24    </div>
25  )
26}
27
28ReactDOM.render(<App />, document.getElementById('root'))

API

initArrowNavigation()

Initializes the arrow navigation. This function should be called only once in your application.

FocusableGroup

A wrapper component that groups a set of focusable elements.

Props

The FocusableGroup component will receive all HTML attributes and events for the HTML tag used as wrapper. Some important props are:

Name	Type	Default	Description
id	string	-	The group id. Must be unique
as	string	div	The HTML tag to be used as wrapper
onFocus	function	-	Callback function to be called when the group receives focus. It returns a object with focus result that includes prev, current and direction
onBlur	function	-	Callback function to be called when the group loses focus. It returns a object with focus result that includes next, current and direction
firstElement	string	-	The id of the first element to receive focus when the group receives focus
nextUp / nextDown / nextRight / nextLeft	string	-	The next group id by direction.
saveLast	boolean	false	If true, the last focused element will be saved and used as firstElement
viewportSafe	boolean	true	If true, the navigation will be limited to the viewport
threshold	number	0	The threshold to intersection discriminator
keepFocus	boolean	false	If true, the focus will be kept in the group when the last element receives focus
byOrder	ORDER	'horizontal'	Navigate by order setted on elements. Can be 'horizontal', 'vertical' or 'grid', this enum comes with ArrowNavigationOrder constant object. Take care with this option, because this will change the id of the elements, for example, for group-0, the element in order 1 will be group-0-1. It includes a utility function getElementIdByOrder(groupId, order): string. Keep this in mind if you are using the id of the elements for firstElement or nextByDirection options.
cols	number - { number: number }	1	The number of columns to navigate when the byOrder is 'grid'. The default value is 1 and you can set a object with the number of columns for each breakpoint. For example: { 0: 1, 768: 2, 1024: 3 }

FocusableElement

A wrapper component that makes an element focusable. The element must be a child of a FocusableGroup component and the HTML tag used as wrapper must be focusable, for example, input, button, a, select, textarea, etc.

Props

The FocusableElement component will receive all HTML attributes and events for the HTML tag used as wrapper. Some important props are:

Name	Type	Default	Description
id	string	-	The element id. Must be unique
as	string	div	The HTML tag to be used as wrapper
onFocus	function	-	Callback function to be called when the element receives focus. It returns a object with focus result that includes prev, current and direction
onBlur	function	-	Callback function to be called when the element loses focus. It returns a object with focus result that includes next, current and direction
nextUp / nextDown / nextRight / nextLeft	string	NextFocusable	The next element or group by direction. In the case of group, must be an object { kind: 'group', id: 'group-0 }
order	number	-	The order of the element. No default value. This is needed when the group is setted to navigate byOrder. If no setted, byOrder will be ignored.

useFocusableElement

Hook to make an element focusable. The element must be a child of a FocusableGroup component and the HTML tag used as wrapper must be focusable, for example, input, button, a, select, textarea, etc. The hook props are the same as FocusableElement component.

Usage

1import { useFocusableElement } from '@arrow-navigation/react'
2
3const MyButton = ({ id }) => {
4  // Is important to pass the id to the hook and to the button
5  useFocusableElement({ id })
6
7  return (
8    <button id={id}>
9      Button 1
10    </button>
11  )
12}
13
14const App = () => {
15  return (
16    <div>
17      <FocusableGroup id="group-1">
18        <MyButton id="btn-1" />
19        <MyButton id="btn-2" />
20        <MyButton id="btn-3" />
21      </FocusableGroup>
22    </div>
23  )
24}

Listeners

The @arrow-navigation/react package also provides some listeners to help you to implement your own navigation and complex behaviors.

useListenElementFocused

Hook to listen when an element receives focus and trigger a callback function.

Usage

1import { useListenElementFocused } from '@arrow-navigation/react'
2
3const App = () => {
4  useListenElementFocused(() => {
5    console.log('Button 1 focused')
6  }, 'btn-1')
7
8  return (
9    <div>
10      <FocusableGroup id="group-1">
11        <FocusableElement id="btn-1">
12          Button 1
13        </FocusableElement>
14        <FocusableElement id="btn-2">
15          Button 2
16        </FocusableElement>
17      </FocusableGroup>
18    </div>
19  )
20}
21
22ReactDOM.render(<App />, document.getElementById('root'))

Parameters

Name	Type	Default	Description
callback	function	-	Callback function to be called when the element receives focus
id	string	-	The element id

useListenLastElementReached

Hook to listen when the last element of a group receives focus and trigger a callback function.

Usage

1import { useListenLastElementReached } from '@arrow-navigation/react'
2
3const App = () => {
4  useListenLastElementReached(() => {
5    console.log('Last element reached')
6  }, 'right')
7
8  return (
9    <div>
10      <FocusableGroup id="group-1">
11        <FocusableElement id="btn-1">
12          Button 1
13        </FocusableElement>
14        <FocusableElement id="btn-2">
15          Button 2
16        </FocusableElement>
17      </FocusableGroup>
18    </div>
19  )
20}
21
22ReactDOM.render(<App />, document.getElementById('root'))

Parameters

Name	Type	Default	Description
callback	function	-	Callback function to be called when the last element of a group receives focus
direction	string	-	The direction to navigate when the last element of a group receives focus. Possible values are: 'up', 'down', 'left' and 'right'
options	object	-	The options for the listener.
options.group	string	-	The group id. If not provided, the listener will be triggered for all groups
options.inGroup	boolean	false	If true, the listener will be triggered only when the last element of the group receives focus
options.elementPattern	RegExp	-	The pattern to match the element id. If not provided, the listener will be triggered for all elements

useListenLastGroupReached

Hook to listen when the last group of a group receives focus and trigger a callback function.

Usage

1import { useListenLastGroupReached } from '@arrow-navigation/react'
2
3const App = () => {
4  useListenLastGroupReached(() => {
5    console.log('Last group reached')
6  }, 'right')
7
8  return (
9    <div>
10      <FocusableGroup id="group-1">
11        <FocusableElement id="btn-1">
12          Button 1
13        </FocusableElement>
14        <FocusableElement id="btn-2">
15          Button 2
16        </FocusableElement>
17      </FocusableGroup>
18      <FocusableGroup id="group-2">
19        <FocusableElement id="btn-3">
20          Button 3
21        </FocusableElement>
22        <FocusableElement id="btn-4">
23          Button 4
24        </FocusableElement>
25      </FocusableGroup>
26    </div>
27  )
28}
29
30ReactDOM.render(<App />, document.getElementById('root'))

Parameters

Name	Type	Default	Description
callback	function	-	Callback function to be called when the last group of a group receives focus
direction	string	-	The direction to navigate when the last group of a group receives focus. Possible values are: 'up', 'down', 'left' and 'right'
options	object	-	The options for the listener.
options.groupPattern	RegExp	-	The pattern to match the group id. If not provided, the listener will be triggered for all groups

Watchers

The @arrow-navigation/react package also provides some watchers to help you to implement your own navigation and complex behaviors. The watchers are similar to the listeners, but they will subscribe a state and make it available to be used in your application. Take care will the watchers, because they can cause multiple renders and performance issues if not used properly.

useWatchElementFocused

Hook to watch when an element receives focus and return a boolean state.

Usage

1import { useWatchElementFocused } from '@arrow-navigation/react'
2
3const App = () => {
4  const isBtn1Focused = useWatchElementFocused('btn-1')
5
6  return (
7    <div>
8      <FocusableGroup id="group-1">
9        <FocusableElement id="btn-1">
10          Button 1
11        </FocusableElement>
12        <FocusableElement id="btn-2">
13          Button 2
14        </FocusableElement>
15      </FocusableGroup>
16      <div>
17        {isBtn1Focused && <span>Button 1 is focused</span>}
18      </div>
19    </div>
20  )
21}
22
23ReactDOM.render(<App />, document.getElementById('root'))

Parameters

Name	Type	Default	Description
id	string	-	The element id