@arrow-navigation/react v2.2.0

Arrow Navigation React

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

Installation

npm install --save @arrow-navigation/react @arrow-navigation/core

# or

yarn 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

import React from 'react'
import {
  initArrowNavigation,
  FocusableElement,
  FocusableGroup
} from '@arrow-navigation/react'

initArrowNavigation()

const App = () => {
  return (
    <div>
      <FocusableGroup id="group-1">
        <FocusableElement id="btn-1">
          Button 1
        </FocusableElement>
        <FocusableElement id="btn-2">
          Button 2
        </FocusableElement>
        <FocusableElement id="btn-3">
          Button 3
        </FocusableElement>
      </FocusableGroup>
    </div>
  )
}

ReactDOM.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:

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:

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

import { useFocusableElement } from '@arrow-navigation/react'

const MyButton = ({ id }) => {
  // Is important to pass the id to the hook and to the button
  useFocusableElement({ id })

  return (
    <button id={id}>
      Button 1
    </button>
  )
}

const App = () => {
  return (
    <div>
      <FocusableGroup id="group-1">
        <MyButton id="btn-1" />
        <MyButton id="btn-2" />
        <MyButton id="btn-3" />
      </FocusableGroup>
    </div>
  )
}

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

import { useListenElementFocused } from '@arrow-navigation/react'

const App = () => {
  useListenElementFocused(() => {
    console.log('Button 1 focused')
  }, 'btn-1')

  return (
    <div>
      <FocusableGroup id="group-1">
        <FocusableElement id="btn-1">
          Button 1
        </FocusableElement>
        <FocusableElement id="btn-2">
          Button 2
        </FocusableElement>
      </FocusableGroup>
    </div>
  )
}

ReactDOM.render(<App />, document.getElementById('root'))

Parameters

useListenLastElementReached

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

Usage

import { useListenLastElementReached } from '@arrow-navigation/react'

const App = () => {
  useListenLastElementReached(() => {
    console.log('Last element reached')
  }, 'right')

  return (
    <div>
      <FocusableGroup id="group-1">
        <FocusableElement id="btn-1">
          Button 1
        </FocusableElement>
        <FocusableElement id="btn-2">
          Button 2
        </FocusableElement>
      </FocusableGroup>
    </div>
  )
}

ReactDOM.render(<App />, document.getElementById('root'))

Parameters

useListenLastGroupReached

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

Usage

import { useListenLastGroupReached } from '@arrow-navigation/react'

const App = () => {
  useListenLastGroupReached(() => {
    console.log('Last group reached')
  }, 'right')

  return (
    <div>
      <FocusableGroup id="group-1">
        <FocusableElement id="btn-1">
          Button 1
        </FocusableElement>
        <FocusableElement id="btn-2">
          Button 2
        </FocusableElement>
      </FocusableGroup>
      <FocusableGroup id="group-2">
        <FocusableElement id="btn-3">
          Button 3
        </FocusableElement>
        <FocusableElement id="btn-4">
          Button 4
        </FocusableElement>
      </FocusableGroup>
    </div>
  )
}

ReactDOM.render(<App />, document.getElementById('root'))

Parameters

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

import { useWatchElementFocused } from '@arrow-navigation/react'

const App = () => {
  const isBtn1Focused = useWatchElementFocused('btn-1')

  return (
    <div>
      <FocusableGroup id="group-1">
        <FocusableElement id="btn-1">
          Button 1
        </FocusableElement>
        <FocusableElement id="btn-2">
          Button 2
        </FocusableElement>
      </FocusableGroup>
      <div>
        {isBtn1Focused && <span>Button 1 is focused</span>}
      </div>
    </div>
  )
}

ReactDOM.render(<App />, document.getElementById('root'))

Parameters