README.md

use-keyboard-list-navigation

What is this?

A React hook to navigate through lists with your keyboard.

Installation

yarn add use-keyboard-list-navigation

Usage

import React from "react";
import { useKeyboardListNavigation } from "use-keyboard-list-navigation";

const App: React.FC = () => {
  const list = ["one", "two", "three"];

  const { index, cursor, interactive, selected } = useKeyboardListNavigation({
    list,
    onEnter: console.log.bind(console),
  });

  return (
    <pre>
      <code>{JSON.stringify({ index, cursor, interactive, selected })}</code>
    </pre>
  );
};

Interface

type UseKeyboardListNavigationProps<T> = {
  ref?: React.MutableRefObject<any> | undefined;
  list: T[];
  waitForInteractive?: boolean | undefined;
  defaultValue?: T | undefined;
  bindAxis?: "vertical" | "horizontal" | "both" | undefined;
  onEnter({
    event,
    element,
    state,
    index,
  }: {
    event: KeyboardEvent;
    element: T;
    state: UseKeyboardListNavigationState;
    index: number;
  }): void;
  extractValue?(item: T): string;
};

const useKeyboardListNavigation: <T>({
  ref,
  list,
  waitForInteractive,
  defaultValue,
  onEnter,
  extractValue,
}: UseKeyboardListNavigationProps<T>) => {
  index: number;
  selected: T;
  cursor: number;
  length: number;
  interactive: boolean;
};