Provides an interface for reading key events such as from external bluetooth keyboards on Android, iOS and Web.
npm install expo-key-event
Interface for reading key events from external devices such as Bluetooth keyboards/gamepads.
Getting started
·
Report Bug
iOS ![]() | Android ![]() | Web ![]() |
- iOS
- Android
- Web
- macOS (Mac Catalyst & react-native-macos)
Expo SDK >= 52
npm i expo-key-event
#### Basic
Automatic listening: Key events are listened to as soon as MyComponent is mounted.
``tsx
import { useKeyEvent } from "expo-key-event";
import { Text } from "react-native";
export function MyComponent() {
const { keyEvent } = useKeyEvent();
return
}
`
#### Control listening
Manual listening: Key events are listened to when startListening is called.
`tsx
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 (
);
}
`
#### 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.
`tsx
import { KeyPressEvent, useKeyEventListener } from "expo-key-event";
import { Text, View } from "react-native";
export function MyComponent() {
const [keyEvent, setKeyEvent] = useState
// deprecated way
// const { startListening, stopListening } = useKeyEventListener((event) => {
// setKeyEvent(event);
// }, automaticControl);
// new way
const { startListening, stopListening } = useKeyEventListener(
(event) => {
setKeyEvent(event);
},
{
listenOnMount: automaticControl,
}
);
return (
);
}
`
#### Modifier keys
Using modifier keys: Key events include modifier key states (shift, ctrl, alt, meta) and repeat information when captureModifiers is enabled.
`tsx
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 (
);
}
`
#### Modifier key combinations
Checking for specific key combinations:
`tsx
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
}
`
cd example
npm run ios / npm run android / npm run web
This is most likely due to using Expo SDK lower than 52. useEvent was introduced in SDK 52.
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).
Make sure that hardware keyboard is connected to the simulator.
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`
This module translates the Apple UIKit and Android KeyEvent constants to a common set of key event types matching the ones from Web.