0.0.3 • Public • Published

    Welcome to react-keyboard-navigation 👋

    Version License: MIT

    A React component to manage the navigation declaratively, such as on smart feature phone applications, e.g., KaiOS.

    🏠 Homepage

    Navigation is the key "battlefield" when developing a non-touch mobile application, as on KaiOS smart feature phones.
    The preferred method of app navigation for the user is to interact with the D-pad. In this context, it is necessary to identify the navigation elements (clickable elements), to make every element focusable (tabIndex="0"), to handle the keydown or keyup event and to apply the focus to the desired DOM element (element.focus()).

    Proposals to tag all navigation items with a particular CSS class, then browse the complete DOM for each event (up or down) and set the focus on the next or previous focusable DOM element exist.
    These solutions are simple and sufficient in some cases, but they have weak points:

    • Browse the entire DOM every time is expensive and inefficient.
    • The order of elements in the DOM does not always reflect the position in the UI.
    • It is impossible to impose an order between the focusable elements.
    • It is difficult to manage the case of modal windows.
    • And finally, they are not virtual DOM friendly… and I love React 😋

    react-keyboard-navigation is a React component that helps to manage the navigation using a declarative and component-based approach.
    It is based on the HOC (Higher Order Component) pattern: principle of composition, with a wrapper that simply add the functionality to the wrapped component.
    It is a very lightweight JavaScript library without dependencies : only 6.1 KB (.js) and 2.6 KB for the minified version (.min.js).


    react-keyboard-navigation is available in several builds:

    • as CommonJS which is the primary way it will be used when installed via npm
    • as ES modules (ECMAScript Modules) which is the way it will be used with module bundlers like Webpack or Rollup with import and export statements.
    • as UMD (Universal Module Definition) for the use via a global variable by dropping it into a <script> tag.

    Install via npm

    yarn add react-keyboard-navigation (or npm install react-keyboard-navigation)

    Add a script tag

    You can also include it directly in your index.html like below:

    <script src=""></script>

    The exposed global variable name is ReactKeyboardNavigation.


    At the root of your application, add the navigation context thanks to the NavigationProvider wrapper component like this:

    import React from 'react';
    import ReactDOM from 'react-dom';
    import App from './App';
    import { NavigationProvider } from 'react-keyboard-navigation';
    ReactDOM.render(<NavigationProvider><App /></NavigationProvider>, document.getElementById("root"));

    Now you can use the 2 HOCs (Higher Order Components) included in react-keyboard-navigation:

    • withFocus to wrap an HTML element (required to use element.focus()) and transform it in a focusable element.
    • withNavigation to wrap a React component or an HTML element and transform it in a container.

    The use of withNavigation is optional, it allows to organize the interface more easily, for example with a header, a content and a footer.
    It also allows to define a modal window.


    import { withFocus } from 'react-keyboard-navigation';
    const InputWithFocus = withFocus(
      ({ forwardedRef, ...props }) => <input ref={forwardedRef} {...props} />
    const App = () => (
      <InputWithFocus id="input" position={0} defaultActive />

    withFocus properties

    • id: PropTypes.string.isRequired
      A unique identifier (inside a container).
    • parentId: PropTypes.string
      The id of the container, parent of the element. Default to 'default'.
    • position: PropTypes.number
      The position (order) of the element in the UI. If not specified, take the order of the mounting in the DOM (componentDidMount).
    • defaultActive: PropTypes.bool
      Take the focus by default. Default to false.


    import { withFocus, withNavigation } from 'react-keyboard-navigation';
    const InputWithFocus = withFocus(
      ({ forwardedRef, ...props }) => <input ref={forwardedRef} {...props} />
    const HeaderWithNavigation = withNavigation(({ parentId }) => (
          parentId={parentId} // parentId can be retrieved from the container or filled manually with "header"
    const App = () => (
      <Header id="header" position={0} />

    withNavigation properties

    • id: PropTypes.string.isRequired
      A unique identifier (inside the whole context). Do not use 'default' which is a container created by default.
    • position: PropTypes.number
      The position (order) of the container in the UI. If not specified, take the order of the mounting in the DOM (componentDidMount).
    • isModal: PropTypes.bool
      The behavior of the container (is it a modal window or not ?). Default to false.

    Check demo/* for usage and these 2 examples below. The demonstrations are based on the code provided by KaiOS in the sample-react repository.

    Simple UI

    UI example without container and with 2 focusable elements (1 input and 1 span): Simple UI

    See the CodeSandbox example for a simple UI :
    Edit Simple UI

    More complex UI

    UI example with 2 containers (Input and Todos) and with 3 focusable elements (1 input and 2 span): Comple UI

    See the CodeSandbox example for a more complex UI :
    Edit More complex UI

    Getting the navigation context

    If you need to retrieve the navigation context in your application, to know which element has the focus, you can use the NavigationContext like this:

    import { NavigationContext } from 'react-keyboard-navigation';
    const App = () => {
      const { state: {activeElement} } = useContext(NavigationContext);
      return (


    👤 Yannick Cornaille

    🤝 Contributing

    Contributions, issues and feature requests are welcome!

    Feel free to read contributing documentation and to check issues page.

    The next features will be the unit tests and the use of the React hooks. Feel free to contribute !

    Show your support

    Give a ⭐️ if this project helped you!

    📝 License

    Copyright © 2019 Orange.

    This project is MIT licensed.

    This README was generated with ❤️ by readme-md-generator


    npm i react-keyboard-navigation

    DownloadsWeekly Downloads






    Unpacked Size

    1.14 MB

    Total Files


    Last publish


    • yannickcornaille