Skip to content

Latest commit

 

History

History
316 lines (238 loc) · 10.5 KB

README.md

File metadata and controls

316 lines (238 loc) · 10.5 KB

Arrow Navigation React

install size License: MIT

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

Installation

npm install --save @arrow-navigation/react

# or

yarn add @arrow-navigation/react

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.

useArrowNavigation

This hook returns the Arrow Navigation instance. It can be used to access the Arrow Navigation API from any part of your application.

Syntax

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

const navigationApi = useArrowNavigation()

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

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

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

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

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

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

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

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

Name Type Default Description
id string - The element id