Expo-key-event

Interface for reading key events from external devices such as Bluetooth keyboards/gamepads.
Getting started · Report Bug

iOS

Android

Web

Supported platforms

• iOS
• Android
• Web
• macOS (Mac Catalyst & react-native-macos)

Requirements

Expo SDK >= 52

Getting started

npm i expo-key-event

Usage

Basic

Automatic listening: Key events are listened to as soon as MyComponent is mounted.

import { useKeyEvent } from "expo-key-event";
import { Text } from "react-native";

export function MyComponent() {
  const { keyEvent } = useKeyEvent();

  return <Text>{keyEvent?.key}</Text>;
}

Control listening

Manual listening: Key events are listened to when startListening is called.

import { useKeyEvent } from "expo-key-event";
import { Text, View } from "react-native";

export function MyComponent() {
  // deprecated way
  // const { keyEvent, startListening, stopListening } = useKeyEvent(false);
  // new way
  const { keyEvent, keyReleaseEvent, startListening, stopListening } =
    useKeyEvent({ listenOnMount: false });

  return (
    <View>
      <Text>{keyEvent?.key}</Text>
      <Button title="Start listening" onPress={() => startListening()} />
      <Button title="Stop listening" onPress={() => stopListening()} />
    </View>
  );
}

Using event listener

Handling state yourself: If you want to handle the state yourself or don't need the state at all, you can use the useKeyEventListener hook instead of the useKeyEvent hook.

import { KeyPressEvent, useKeyEventListener } from "expo-key-event";
import { Text, View } from "react-native";

export function MyComponent() {
  const [keyEvent, setKeyEvent] = useState<KeyPressEvent>();
  // deprecated way
  // const { startListening, stopListening } = useKeyEventListener((event) => {
  //   setKeyEvent(event);
  // }, automaticControl);
  // new way
  const { startListening, stopListening } = useKeyEventListener(
    (event) => {
      setKeyEvent(event);
    },
    {
      listenOnMount: automaticControl,
    }
  );

  return (
    <View>
      <Text>{keyEvent?.key}</Text>
      <Button title="Start listening" onPress={() => startListening()} />
      <Button title="Stop listening" onPress={() => stopListening()} />
    </View>
  );
}

Modifier keys

Using modifier keys: Key events include modifier key states (shift, ctrl, alt, meta) and repeat information when captureModifiers is enabled.

import { useKeyEvent } from "expo-key-event";
import { Text, View } from "react-native";

export function MyComponent() {
  const { keyEvent } = useKeyEvent({
    listenOnMount: true,
    captureModifiers: true, // Enable modifier key capture
  });

  return (
    <View>
      <Text>Key: {keyEvent?.key}</Text>
      <Text>Shift: {keyEvent?.shiftKey ? "Yes" : "No"}</Text>
      <Text>Ctrl: {keyEvent?.ctrlKey ? "Yes" : "No"}</Text>
      <Text>Alt: {keyEvent?.altKey ? "Yes" : "No"}</Text>
      <Text>Meta: {keyEvent?.metaKey ? "Yes" : "No"}</Text>
      <Text>Repeat: {keyEvent?.repeat ? "Yes" : "No"}</Text>
    </View>
  );
}

Modifier key combinations

Checking for specific key combinations:

import { useState } from "react";
import { KeyPressEvent, useKeyEventListener } from "expo-key-event";
import { Text } from "react-native";

export function MyComponent() {
  const [message, setMessage] = useState("");

  useKeyEventListener(
    (event: KeyPressEvent) => {
      // Check for Cmd+S (macOS) or Ctrl+S (Windows/Linux)
      if (event.key === "KeyS" && (event.metaKey || event.ctrlKey)) {
        setMessage("Save shortcut pressed!");
      }
      // Check for Shift+Enter
      else if (event.key === "Enter" && event.shiftKey) {
        setMessage("New line!");
      }
      // Check for Alt+Arrow
      else if (event.key === "ArrowRight" && event.altKey) {
        setMessage("Navigate forward!");
      }
    },
    {
      listenOnMount: true,
      captureModifiers: true, // Required to receive modifier key states
    }
  );

  return <Text>{message}</Text>;
}

Run example app

cd example

npm run ios / npm run android / npm run web

Troubleshooting

_expo.useEvent is not a function

This is most likely due to using Expo SDK lower than 52. useEvent was introduced in SDK 52.

Error: Cannot find native module 'ExpoKeyEvent'

Make sure to use a development build and not Expo Go. See https://docs.expo.dev/guides/local-app-development/ for more details.

In short: Use npx expo run:ios instead of npx expo start (make sure bundleIdentifier is set in app.json).

Key events are not registered in iOS simulator

Make sure that hardware keyboard is connected to the simulator.

Key events are not registered in Android emulator

Since the Android emulator does not support USB or Bluetooth, you need to use a physical device so that key events can be registered.

Another option is to use adb to send key events to the emulator.

e.g. adb shell input keyevent 10

How it works

This module translates the Apple UIKit and Android KeyEvent constants to a common set of key event types matching the ones from Web.