React Native External Keyboard

React Native library for enhanced external keyboard support.

• ⚡️ The New Architecture is supported
• ⚡️ Bridgeless

New Release Features

• KeyboardExtendedInput: a new component for handling TextInput focusability. More here
• Performance Optimization: Improved key press handling functionality.
• Renaming: Added aliases for components and modules. More here

| iOS | Android | | ---------------------------------------------------------- | -------------------------------------------------------------- | | | |

Features

• Forcing keyboard focus (moving the keyboard focus to a specific element)
• Key press handling
• View and TextInput focus control

Installation

npm install react-native-external-keyboard

iOS:

cd ios && pod install && cd ..

Usage

KeyboardExtendedInput

The TextInput component with keyboard focus support. This component allows the TextInput to be focused using the keyboard in various scenarios.

import { KeyboardExtendedInput } from 'react-native-external-keyboard';
...
  <KeyboardExtendedInput
    focusType="default"
    blurType="default"
    value={textInput}
    onChangeText={setTextInput}
  />

| Props | Description | Type | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | | canBeFocused?: | Boolean property whether component can be focused by keyboard | boolean \| undefined default true | | onFocusChange?: | Callback for focus change handling | (e:NativeSyntheticEvent<{ isFocused: boolean; }>) => void \| undefined | | focusType?: | Focus type can be default, auto, or press. Based on investigation, Android and iOS typically have different default behaviors. On Android, the TextInput is focused by default, while on iOS, you need to press to focus. auto is used for automatic focusing, while keyboard focus targets the input. With press, you need to press the spacebar to focus an input. | "default" \| "press" \| "auto" | | blurType?: | Only for iOS. This defines the behavior for blurring input when focus moves away from the component. By default, iOS allows typing when the keyboard focus is on another component. You can use disable to blur input when focus moves away. (Further investigation is needed for Android.) | "default"\| "disable" \| "auto" |

KeyboardExtendedPressable: (alias for: Pressable)

The Pressable component with keyboard focus support. This component allows handling the onLongPress event fired by the keyboard.

FYI: iOS has a specific press action that is configured by system settings. Read more

import { KeyboardExtendedPressable } from 'react-native-external-keyboard';

// ...

<KeyboardExtendedPressable
  focusStyle={{ backgroundColor: '#cdf2ef' }}
  onPress={() => console.log('onPress')}
  onPressIn={() => console.log('onPressIn')}
  onPressOut={() => console.log('onPressOut')}
  onLongPress={() => console.log('onLongPress')}
>
  <Text>On Press Check</Text>
</KeyboardExtendedPressable>;

You can pass the default React Native PressableProps as well as additional props for keyboard handling functionality:

| Props | Description | Type | | --------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | canBeFocused?: | Boolean property whether component can be focused by keyboard | boolean \| undefined default true | | onFocusChange?: | Callback for focus change handling | (e:NativeSyntheticEvent<{ isFocused: boolean; }>) => void \| undefined | | focusStyle?: | Style for selected by keyboard component | ((state: { focused: boolean}) => StyleProp<ViewStyle> \| StyleProp<ViewStyle> \| undefined | | onPress?: | Default onPress or keyboard handled onPress | (e: GestureResponderEvent \| OnKeyPress) => void; \| undefined | | onLongPress?: | Default onLongPress or keyboard handled onLongPress | (e: GestureResponderEvent \| OnKeyPress) => void; \| undefined | | withView?: | Android only prop, it is used for wrapping children in <View accessible/> | boolean \| undefined default true |

[!NOTE] You may discover that long press on spacebar does not trigger a long press event on iOS. This is because iOS use a Full Keyboard Access system that provides commands for interacting with the system. Rather than holding down the spacebar, you can use Tab+M (the default action for opening the context menu). You can change Commands in: Full Keyboard Access -> Commands

KeyboardExtendedView: (alias for: KeyboardFocusView)

The KeyboardExtendedView component is styled component for keyboard handling, has a default focus color and preferable for fast start to handling keyboard focus.

import { KeyboardExtendedView } from 'react-native-external-keyboard';
// ...

<KeyboardExtendedView
  focusStyle={{ backgroundColor: '#a0dcbe' }}
  onFocusChange={(e) => console.log(e.nativeEvent.isFocused)}
>
  <Text>Focusable</Text>
</KeyboardExtendedView>;

You can pass the default React Native ViewProps as well as additional props for keyboard handling functionality: | Props | Description | Type | | ------------- | ------------- | ---- | | canBeFocused?: | Boolean property whether component can be focused by keyboard | boolean \| undefined default true | | onFocusChange?: | Callback for focus change handling | (e:NativeSyntheticEvent<{ isFocused: boolean; }>) => void | | onKeyUpPress?: | Callback for handling key up event | (e: OnKeyPress) => void | | onKeyDownPress?: | Callback for handling key down event | (e: OnKeyPress) => void| | focusStyle?: | Style for selected by keyboard component | ((state: { focused: boolean}) => StyleProp<ViewStyle> \| StyleProp<ViewStyle> |

KeyboardExtendedBaseView: (alias for: ExternalKeyboardView)

It's a core component similar to native ones, but it includes a helper for optimizing key presses. Currently, it's recommended to use KeyboardExtendedView if you don't need a custom implementation.

Important: When using KeyboardExtendedBaseView on Android, make sure the children component has the accessible prop.

import { KeyboardExtendedBaseView } from 'react-native-external-keyboard';
// ...
<KeyboardExtendedBaseView
        onKeyDownPress={...}
        onKeyUpPress={...}
        canBeFocused
      >
    <View accessible>
        <Text>Content</Text>
    </View>
</KeyboardExtendedBaseView>

| Props | Description | Type | | ---------------- | ------------------------------------------------------------- | ----------------------------------------------------------- | | canBeFocused?: | Boolean property whether component can be focused by keyboard | boolean \| undefined default true | | onFocusChange?: | Callback for focus change handling | (e:NativeSyntheticEvent<{ isFocused: boolean; }>) => void | | onKeyUpPress?: | Callback for handling key up event | (e: OnKeyPress) => void | | onKeyDownPress?: | Callback for handling key down event | (e: OnKeyPress) => void |

KeyboardExtendedModule (alias for: A11yModule)

The KeyboardExtendedModule API is utilized to shift the keyboard focus to a target component. The component's ref is necessary for this operation. On iOS, proper functionality of keyboard focus is ensured only with KeyboardExtendedView or KeyboardExtendedPressable, as iOS requires specific workarounds for moving keyboard focus."

KeyboardExtendedModule.setKeyboardFocus(ref);

import {
  KeyboardExtendedView,
  KeyboardExtendedModule,
  KeyboardExtendedPressable,
} from 'react-native-external-keyboard';
// ...
 <KeyboardExtendedPressable onPress={() => KeyboardExtendedModule.setKeyboardFocus(ref)}>
   <Text>On Press Check</Text>
 </KeyboardExtendedPressable>
 <KeyboardExtendedView
    onFocusChange={(e) => console.log(e.nativeEvent.isFocused)}
    >
    <Text>Focusable</Text>
 </KeyboardExtendedView>

export interface IA11yModule {
  currentFocusedTag?: number;

  setPreferredKeyboardFocus: (nativeTag: number, nextTag: number) => void;
  setKeyboardFocus: (ref: RefObjType) => void;
}

| Props | Description | Type | | -------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------- | | currentFocusedTag?: | iOS only, it is used for the keyboard focus moving feature | number | | setPreferredKeyboardFocus: | iOS only, you can define default focus redirect from a component to a target | (nativeTag: number, nextTag: number) => void; | | setKeyboardFocus: | Move focus to the target by ref | (ref: RefObjType) => void |

Upgrading

Component aliases

It is believed that good naming can simplify usage and development. Based on this principle and for compatibility with 0.2.x, aliases were added. You can still use the old naming convention, and it will be maintained in future releases.

The map of aliases is provided below: A11yModule -> KeyboardExtendedModule Pressable -> KeyboardExtendedPressable KeyboardFocusView -> KeyboardExtendedView ExternalKeyboardView -> KeyboardExtendedBaseView

API

export type OnKeyPress = NativeSyntheticEvent<{
  keyCode: number;
  unicode: number;
  unicodeChar: string;
  isLongPress: boolean;
  isAltPressed: boolean;
  isShiftPressed: boolean;
  isCtrlPressed: boolean;
  isCapsLockOn: boolean;
  hasNoModifiers: boolean;
}>;

License

MIT

Made with create-react-native-library