React Native Physical Keyboard

Cross-platform React Native + Expo module for detecting physical keyboards on mobile devices. This library can be useful for detecting external keyboards when implementing accessibility features.

Features

🎯 Core Functionality

• 🔌 Real-time Detection - Detect when physical keyboards are connected or disconnected
• ⌨️ Key Event Monitoring - Listen to key press and release events
• 📊 Hardware Information - Get keyboard details like vendor, model, and type

🚀 Developer Experience

• TypeScript Support - Full type definitions included
• 🎣 React Hooks API - Simple hooks for easy integration
• ⚡ Zero Configuration - Works without additional setup
• 🔄 Reactive State - Components update when keyboard state changes
• Expo Compatible - Supports managed workflow (SDK 50+)
• 🍎🤖 Cross-Platform - iOS and Android support

🎨 Additional Features

• 📈 Connection History - Track connection timestamps
• 🏷️ Device Classification - Identify keyboard types and vendors
• ⚡ Performance - Lightweight native implementation
• 🛡️ Error Handling - Handles edge cases and platform differences

Installation

npm install react-native-physical-keyboard-detector

bun add react-native-physical-keyboard-detector

⚠️ Requires native rebuild - run expo prebuild after installation.

📱 Testing Note - For best results, test on physical devices. iOS Simulator may not properly detect key press events, though keyboard connection detection should work correctly.

Usage

Basic Setup

import { PhysicalKeyboardProvider } from 'react-native-physical-keyboard-detector';

export default function App() {
  return (
    <PhysicalKeyboardProvider>
      <YourApp />
    </PhysicalKeyboardProvider>
  );
}

Detect Connection

function MyComponent() {
  const isConnected = usePhysicalKeyboardConnected();
  
  return (
    <Text>
      Keyboard: {isConnected ? 'Connected' : 'Not Connected'}
    </Text>
  );
}

Get Keyboard Details

function KeyboardInfo() {
  const keyboard = usePhysicalKeyboardDetails();
  
  if (!keyboard) return <Text>No external hardware keyboard</Text>;
  
  return (
    <View>
      <Text>Name: {keyboard.name}</Text>
      <Text>Connected: {new Date(keyboard.connectedAt).toLocaleString()}</Text>
      {/* iOS specific */}
      {keyboard.vendorName && <Text>Vendor: {keyboard.vendorName}</Text>}
      {/* Android specific */}
      {keyboard.keyboardType && <Text>Type: {keyboard.keyboardTypeName}</Text>}
    </View>
  );
}

Listen to Key Events

function KeyListener() {
  const keyEvent = usePhysicalKeyboardEvents();
  
  if (!keyEvent) return null;
  
  return (
    <Text>
      Last key: {keyEvent.keyCode} ({keyEvent.action})
    </Text>
  );
}

API

Provider

• <PhysicalKeyboardProvider> - Wrap your app to enable keyboard detection

Hooks

• usePhysicalKeyboardConnected() - Returns boolean
• usePhysicalKeyboardDetails() - Returns keyboard info or null
• usePhysicalKeyboardEvents() - Returns last key event or null

Note: All hooks must be used within PhysicalKeyboardProvider

Types

// iOS Keyboard Info
interface IOSPhysicalKeyboardInfo {
  name: string;
  connectedAt: number;
  vendorName?: string;
  productCategory?: string;
  availableButtonKeys?: string[];
  buttonCount?: number;
}

// Android Keyboard Info
interface AndroidPhysicalKeyboardInfo {
  name: string;
  connectedAt: number;
  id?: number;
  vendorId?: number;
  productId?: number;
  keyboardType?: number;
  keyboardTypeName?: string;
  isExternal?: boolean;
}

// Key Event
interface KeyPressEventPayload {
  keyCode: number;
  timestamp: number;
  action: 'up' | 'down';
}

Platform Support

• iOS: Uses GameController framework
• Android: Uses InputDevice API
• Expo: SDK 50+

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT