⌨️ React Keyboard Navigator

A suite of React components and hook for selecting sibling components through the keyboard.

🧩 Installation

yarn add react-keyboard-navigator (or npm/pnpm)

💡 Concept

import{KeyboardNavigatorBoard,KeyboardNavigatorElement,useKeyboardNavigator}from'react-keyboard-navigator'

This suite contains two polymorphic higher-order component: KeyboardNavigatorBoard and KeyboardNavigatorElement, the former scopes the control zone, and the latter wraps your selectable component. They both receive a special prop as, which indicates what's the component ultimately rendered as.

There is another necessary React hook in this suite -- useKeyboardNavigator. It returns a marker which adheres to the KeyboardNavigatorBoard and KeyboardNavigatorElement for connecting them.

const{ markRef }=useKeyboardNavigator()

<KeyboardNavigatorBoardas="div"markRef={markRef}active={boardActive}>{children}<KeyboardNavigatorBoard/>

<KeyboardNavigatorElementas="span"markRef={markRef}active={elementActive}onActiveChange={handleElementActiveChange}>{children}</KeyboardNavigatorElement>

💫 Signature

KeyboardNavigatorBoard's active state can be driven by an external prop or internal automatic detecting. An explicitly passed active prop forces this detection disabled. If you let this active prop be omitted, the autoActive detecting mechanism will be enabled with an initial active state initialActive. It is also a polymorphic higher-order component, so you can pass any props which the as one takes and the base type definition.

typeKeyboardNavigatorBoardProps={markRef: RegistrySymbol,as: React.ElementType,active?: boolean,// if we explicitly passed the `active` prop, it means the `active` state of KeyboardNavigatorBoard is controlled by external, the `autoActive` prop is forced to `false`.// Otherwise, the `autoActive` fallbacks to enabled.autoActive?: boolean,onAutoActiveChange?: (active: boolean)=>void,// if the `autoActive` feature is enabled, the initial is used to determine the initial active state, it has the default value of `false`initialActive?: boolean,}

KeyboardNavigatorElement is a active-state-controlled component (see the controlled component explanation), and it is polymorphic higher-order-component, also receives any props which the as one takes. Therefore it mixes the base type definition with the as one's props:

typeKeyboardNavigatorElementProps={markRef: RegistrySymbol,active?: boolean,onActiveChange?: (active: boolean)=>void,as: React.ElementType,}

useKeyboardNavigator receives:

directionMap for customize keyboard mapping. See the Customization section for details.
eventCallback for catching the active state transition, if the caller explicitly returns a false value means manually to prevent this pass-by happening. See the Signature section for more about built-in event callback presets.
didChange for catching the next tick of active state pass-by, it is convenient to manipulate the relevant elements, e.g. trigger focus, blur, etc.
rootContainer for set a always existed and active KeyboardNavigatorBoard, e.g. document.body. If this option is provided, you don't have to always mark a selectable element through wrapped itself by KeyboardNavigatorBoard.

typeUseKeyboardNavigatorOption={directionMap?: DirectionKeyMap|DirectionMapeventCallback?: (e: KeyboardEvent,eventInfo: {fromElement: HTMLElement,toElement?: HTMLElement})=>void|falsedidChange?: (fromElement: HTMLElement,toElement: HTMLElement)=>voidrootContainer?: HTMLElement}

📎 Example

import{KeyboardNavigatorBoard,KeyboardNavigatorElement,useKeyboardNavigator}from'react-keyboard-navigator'constDemo=({ blocks }: Props)=>{const{ markRef }=useKeyboardNavigator({// prevent the default page scrolling behavior when we are using the keyboard to switch the active state between componentseventCallback: evt=>evt.preventDefault()})const[highlightBlockIndex,setHighlightBockIndex]=useState(0)const[boardActive,setBoardActive]=useState(true)return(<div><divonClick={()=>setBoardActive(!boardActive)}style={{cursor: 'pointer'}}>Active controlled: {boardActive ? '✅' : '❌'}</div><hr/><KeyboardNavigatorBoardas="main"markRef={markRef}active={boardActive}>{blocks.map((word,index)=>(<KeyboardNavigatorElementkey={word.key}as="span"className="block"style={{top: word.y,left: word.x,borderColor: index===highlightBlockIndex ? 'orange' : 'lightblue'}}onClick={()=>setHighlightBockIndex(index)}markRef={markRef}active={index===highlightBlockIndex}onActiveChange={()=>setHighlightBockIndex(index)}>{word.text}{' '}</KeyboardNavigatorElement>))}</KeyboardNavigatorBoard></div>)}

You can see the live preview here: Random Placement, and other examples: Interest Gallery, MacOS Finder

Customization 👇

There are two customizable stuff in keyboard navigation: distance calculation strategy and direction mapping.

distance calculation strategy determines how to calculate the distance between the start point and the specified direction. It support Distance、Secant、Cosine、Sine、Tangent、custom calculation method (distance: number, angleDegree: number) => number.
direction mapping binds the keyboard key to the direction. There are total 8 directions and some built-in direction-keyboard mapping has been defined:

Group Name	Direction	Keyboard Key
ArrowDirectionMap	UP	ArrowUp
	DOWN	ArrowDown
	LEFT	ArrowLeft
	RIGHT	ArrowRight
WASDDirectionMap	UP	W
	DOWN	S
	LEFT	A
	RIGHT	D
IJKLDirectionMap	UP	I
	DOWN	K
	LEFT	J
	RIGHT	L
HJKLDirectionMap	UP	K
	DOWN	H
	LEFT	J
	RIGHT	L
NumPadDirectionMap	UP_LEFT	7
	UP	8
	UP_RIGHT	9
	LEFT	4
	RIGHT	6
	DOWN_LEFT	1
	DOWN	2
	DOWN_RIGHT	3

By default we use the ArrowDirectionMap.

An valid custom direction could be mapping from direction to key:

constArrowDirectionKeyMap: DirectionKeyMap={UP: 'ArrowUp',DOWN: 'ArrowDown',LEFT: 'ArrowLeft',RIGHT: 'ArrowRight',}

or mapping from direction to key and strategy:

constArrowDirectionMap: DirectionMap={UP: {key: 'ArrowUp',strategy: 'Cosine',},DOWN: {key: 'ArrowDown',strategy: 'Cosine',},LEFT: {key: 'ArrowLeft',strategy: 'Distance',},RIGHT: {key: 'ArrowRight',strategy: 'Distance',}}

We exported all the built-in direction-keyboard mapping presets. They are grouped by preferences, and there all have subgroups with different strategies.

import{useKeyboardNavigator,DirectionMapPresets}from'react-keyboard-navigator'// execute in A Functional React ComponentuseKeyboardNavigator({directionMap: DirectionMapPresets.WASDDirectionMap.secant})

Create your own direction mapping

You can create your own mapping with fallback strategy Cosine. e.g.

constMyDirectionMapping: DirectionKeyMap={UP: 'U',DOWN: 'D',LEFT: 'L',RIGHT: 'R',}

Or use the StrategiesHelper to create a DirectionMap which defined with specific strategy:

import{StrategiesHelper}from 'react-keyboard-navigator
constMyDirectionMapping: DirectionMap=StrategiesHelper.secant({UP: 'U',DOWN: 'D',LEFT: 'L',RIGHT: 'R',})

If this StrategiesHelper doesn't satisfy your needs, feel free to use your own calculation.

constYourOwnDirection: DirectionMap={UP: {key: 'U',strategy: 'Cosine',},DOWN: {key: 'D',strategy: 'Cosine',},LEFT: {key: 'L',strategy: (distance: number,angleDegree: number)=>angleDegree<10 ? 0 : distance*Math.log(angleDegree)/Math.log(10),},RIGHT: {key: 'R',strategy: (distance: number,angleDegree: number)=>angleDegree<10 ? 0 : distance*Math.log(angleDegree)/Math.log(10),}}

Signature of Customization stuff

EventCallbackPresets

This presets includes some common event callbacks.

import{EventCallbackPresets}from'react-keyboard-navigator'

DirectionMapPresets.preventDefault: prevent the default behavior of the event, usually is used for prevent from page scrolling when navigating.
DirectionMapPresets.stopPropagation: stop propagation of the event, usually is used for prevent conflicts with topper DOM's listeners.
DirectionMapPresets.stopImmediatePropagation: same to stopPropagation, but stop the event propagation immediately.
DirectionMapPresets.stopOnActiveInputElement: stop navigating when the current active element is an input element.
DirectionMapPresets.stopOnActiveInputElementAndPreventDefault: same to stopOnActiveInputElement, but also prevent the default behavior of the event.

DirectionMapPresets

import{DirectionMapPresets}from'react-keyboard-navigator'

See its structure

Object {"ArrowDirectionMap": Object {"cosine": Object {"DOWN": Object {"key": "ArrowDown",
"strategy": "Cosine",
},"LEFT": Object {"key": "ArrowLeft",
"strategy": "Cosine",
},"RIGHT": Object {"key": "ArrowRight",
"strategy": "Cosine",
},"UP": Object {"key": "ArrowUp",
"strategy": "Cosine",
},},"distance": Object {"DOWN": Object {"key": "ArrowDown",
"strategy": "Distance",
},"LEFT": Object {"key": "ArrowLeft",
"strategy": "Distance",
},"RIGHT": Object {"key": "ArrowRight",
"strategy": "Distance",
},"UP": Object {"key": "ArrowUp",
"strategy": "Distance",
},},"secant": Object {"DOWN": Object {"key": "ArrowDown",
"strategy": "Secant",
},"LEFT": Object {"key": "ArrowLeft",
"strategy": "Secant",
},"RIGHT": Object {"key": "ArrowRight",
"strategy": "Secant",
},"UP": Object {"key": "ArrowUp",
"strategy": "Secant",
},},"sine": Object {"DOWN": Object {"key": "ArrowDown",
"strategy": "Sine",
},"LEFT": Object {"key": "ArrowLeft",
"strategy": "Sine",
},"RIGHT": Object {"key": "ArrowRight",
"strategy": "Sine",
},"UP": Object {"key": "ArrowUp",
"strategy": "Sine",
},},"tangent": Object {"DOWN": Object {"key": "ArrowDown",
"strategy": "Tangent",
},"LEFT": Object {"key": "ArrowLeft",
"strategy": "Tangent",
},"RIGHT": Object {"key": "ArrowRight",
"strategy": "Tangent",
},"UP": Object {"key": "ArrowUp",
"strategy": "Tangent",
},},},"HJKLDirectionMap": Object {"cosine": Object {"DOWN": Object {"key": "J",
"strategy": "Cosine",
},"LEFT": Object {"key": "H",
"strategy": "Cosine",
},"RIGHT": Object {"key": "L",
"strategy": "Cosine",
},"UP": Object {"key": "K",
"strategy": "Cosine",
},},"distance": Object {"DOWN": Object {"key": "J",
"strategy": "Distance",
},"LEFT": Object {"key": "H",
"strategy": "Distance",
},"RIGHT": Object {"key": "L",
"strategy": "Distance",
},"UP": Object {"key": "K",
"strategy": "Distance",
},},"secant": Object {"DOWN": Object {"key": "J",
"strategy": "Secant",
},"LEFT": Object {"key": "H",
"strategy": "Secant",
},"RIGHT": Object {"key": "L",
"strategy": "Secant",
},"UP": Object {"key": "K",
"strategy": "Secant",
},},"sine": Object {"DOWN": Object {"key": "J",
"strategy": "Sine",
},"LEFT": Object {"key": "H",
"strategy": "Sine",
},"RIGHT": Object {"key": "L",
"strategy": "Sine",
},"UP": Object {"key": "K",
"strategy": "Sine",
},},"tangent": Object {"DOWN": Object {"key": "J",
"strategy": "Tangent",
},"LEFT": Object {"key": "H",
"strategy": "Tangent",
},"RIGHT": Object {"key": "L",
"strategy": "Tangent",
},"UP": Object {"key": "K",
"strategy": "Tangent",
},},},"IJKLDirectionMap": Object {"cosine": Object {"DOWN": Object {"key": "k",
"strategy": "Cosine",
},"LEFT": Object {"key": "J",
"strategy": "Cosine",
},"RIGHT": Object {"key": "L",
"strategy": "Cosine",
},"UP": Object {"key": "I",
"strategy": "Cosine",
},},"distance": Object {"DOWN": Object {"key": "k",
"strategy": "Distance",
},"LEFT": Object {"key": "J",
"strategy": "Distance",
},"RIGHT": Object {"key": "L",
"strategy": "Distance",
},"UP": Object {"key": "I",
"strategy": "Distance",
},},"secant": Object {"DOWN": Object {"key": "k",
"strategy": "Secant",
},"LEFT": Object {"key": "J",
"strategy": "Secant",
},"RIGHT": Object {"key": "L",
"strategy": "Secant",
},"UP": Object {"key": "I",
"strategy": "Secant",
},},"sine": Object {"DOWN": Object {"key": "k",
"strategy": "Sine",
},"LEFT": Object {"key": "J",
"strategy": "Sine",
},"RIGHT": Object {"key": "L",
"strategy": "Sine",
},"UP": Object {"key": "I",
"strategy": "Sine",
},},"tangent": Object {"DOWN": Object {"key": "k",
"strategy": "Tangent",
},"LEFT": Object {"key": "J",
"strategy": "Tangent",
},"RIGHT": Object {"key": "L",
"strategy": "Tangent",
},"UP": Object {"key": "I",
"strategy": "Tangent",
},},},"NumPadDirectionMap": Object {"cosine": Object {"DOWN": Object {"key": "2",
"strategy": "Cosine",
},"DOWN_LEFT": Object {"key": "1",
"strategy": "Cosine",
},"DOWN_RIGHT": Object {"key": "3",
"strategy": "Cosine",
},"LEFT": Object {"key": "4",
"strategy": "Cosine",
},"RIGHT": Object {"key": "6",
"strategy": "Cosine",
},"UP": Object {"key": "8",
"strategy": "Cosine",
},"UP_LEFT": Object {"key": "7",
"strategy": "Cosine",
},"UP_RIGHT": Object {"key": "9",
"strategy": "Cosine",
},},"distance": Object {"DOWN": Object {"key": "2",
"strategy": "Distance",
},"DOWN_LEFT": Object {"key": "1",
"strategy": "Distance",
},"DOWN_RIGHT": Object {"key": "3",
"strategy": "Distance",
},"LEFT": Object {"key": "4",
"strategy": "Distance",
},"RIGHT": Object {"key": "6",
"strategy": "Distance",
},"UP": Object {"key": "8",
"strategy": "Distance",
},"UP_LEFT": Object {"key": "7",
"strategy": "Distance",
},"UP_RIGHT": Object {"key": "9",
"strategy": "Distance",
},},"secant": Object {"DOWN": Object {"key": "2",
"strategy": "Secant",
},"DOWN_LEFT": Object {"key": "1",
"strategy": "Secant",
},"DOWN_RIGHT": Object {"key": "3",
"strategy": "Secant",
},"LEFT": Object {"key": "4",
"strategy": "Secant",
},"RIGHT": Object {"key": "6",
"strategy": "Secant",
},"UP": Object {"key": "8",
"strategy": "Secant",
},"UP_LEFT": Object {"key": "7",
"strategy": "Secant",
},"UP_RIGHT": Object {"key": "9",
"strategy": "Secant",
},},"sine": Object {"DOWN": Object {"key": "2",
"strategy": "Sine",
},"DOWN_LEFT": Object {"key": "1",
"strategy": "Sine",
},"DOWN_RIGHT": Object {"key": "3",
"strategy": "Sine",
},"LEFT": Object {"key": "4",
"strategy": "Sine",
},"RIGHT": Object {"key": "6",
"strategy": "Sine",
},"UP": Object {"key": "8",
"strategy": "Sine",
},"UP_LEFT": Object {"key": "7",
"strategy": "Sine",
},"UP_RIGHT": Object {"key": "9",
"strategy": "Sine",
},},"tangent": Object {"DOWN": Object {"key": "2",
"strategy": "Tangent",
},"DOWN_LEFT": Object {"key": "1",
"strategy": "Tangent",
},"DOWN_RIGHT": Object {"key": "3",
"strategy": "Tangent",
},"LEFT": Object {"key": "4",
"strategy": "Tangent",
},"RIGHT": Object {"key": "6",
"strategy": "Tangent",
},"UP": Object {"key": "8",
"strategy": "Tangent",
},"UP_LEFT": Object {"key": "7",
"strategy": "Tangent",
},"UP_RIGHT": Object {"key": "9",
"strategy": "Tangent",
},},},"WASDDirectionMap": Object {"cosine": Object {"DOWN": Object {"key": "S",
"strategy": "Cosine",
},"LEFT": Object {"key": "A",
"strategy": "Cosine",
},"RIGHT": Object {"key": "D",
"strategy": "Cosine",
},"UP": Object {"key": "W",
"strategy": "Cosine",
},},"distance": Object {"DOWN": Object {"key": "S",
"strategy": "Distance",
},"LEFT": Object {"key": "A",
"strategy": "Distance",
},"RIGHT": Object {"key": "D",
"strategy": "Distance",
},"UP": Object {"key": "W",
"strategy": "Distance",
},},"secant": Object {"DOWN": Object {"key": "S",
"strategy": "Secant",
},"LEFT": Object {"key": "A",
"strategy": "Secant",
},"RIGHT": Object {"key": "D",
"strategy": "Secant",
},"UP": Object {"key": "W",
"strategy": "Secant",
},},"sine": Object {"DOWN": Object {"key": "S",
"strategy": "Sine",
},"LEFT": Object {"key": "A",
"strategy": "Sine",
},"RIGHT": Object {"key": "D",
"strategy": "Sine",
},"UP": Object {"key": "W",
"strategy": "Sine",
},},"tangent": Object {"DOWN": Object {"key": "S",
"strategy": "Tangent",
},"LEFT": Object {"key": "A",
"strategy": "Tangent",
},"RIGHT": Object {"key": "D",
"strategy": "Tangent",
},"UP": Object {"key": "W",
"strategy": "Tangent",
},},},}

StrategiesHelper

import{StrategiesHelper}from'react-keyboard-navigator'

See its structure

{distance: (directionMap: DirectionKeyMap|DirectionMap,keepOrigin?: boolean)=>DirectionMap,secant: (directionMap: DirectionKeyMap|DirectionMap,keepOrigin?: boolean)=>DirectionMap,cosine: (directionMap: DirectionKeyMap|DirectionMap,keepOrigin?: boolean)=>DirectionMap,sine: (directionMap: DirectionKeyMap|DirectionMap,keepOrigin?: boolean)=>DirectionMap,tangent: (directionMap: DirectionKeyMap|DirectionMap,keepOrigin?: boolean)=>DirectionMap,}

Name		Name	Last commit message	Last commit date
Latest commit History 38 Commits
.github		.github
.vscode		.vscode
packages		packages
.eslintrc.js		.eslintrc.js
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json

Navigation Menu

Repository files navigation

⌨️ React Keyboard Navigator

🧩 Installation

💡 Concept

💫 Signature

📎 Example

Customization 👇

Create your own direction mapping

Signature of Customization stuff

EventCallbackPresets

DirectionMapPresets

StrategiesHelper

About

Releases

Packages

Used by

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

⌨️ React Keyboard Navigator

🧩 Installation

💡 Concept

💫 Signature

📎 Example

Customization 👇

Create your own direction mapping

Signature of Customization stuff

EventCallbackPresets

DirectionMapPresets

StrategiesHelper

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages