expo-key-event

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.

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

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

return {keyEvent?.key};
}
`

#### 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 (

{keyEvent?.key}
startListening()} />
stopListening()} />

);
}
`

#### 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 (

{keyEvent?.key}


startListening()} />
stopListening()} />

);
}
`

#### 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 (

Key: {keyEvent?.key}
Shift: {keyEvent?.shiftKey ? "Yes" : "No"}
Ctrl: {keyEvent?.ctrlKey ? "Yes" : "No"}
Alt: {keyEvent?.altKey ? "Yes" : "No"}
Meta: {keyEvent?.metaKey ? "Yes" : "No"}
Repeat: {keyEvent?.repeat ? "Yes" : "No"}

);
}
`

#### 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 {message};
}
`




Run example app

cd example

npm run ios / npm run android / npm run web




Troubleshooting

$3

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

$3

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).

$3

Make sure that hardware keyboard is connected to the simulator.


$3

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.