React Native library for enhanced external keyboard support.
KeyboardExtendedInput
: a new component for handling TextInput focusability. More hereiOS | Android |
---|---|
npm install react-native-external-keyboard
iOS:
cd ios && pod install && cd ..
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" |
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 oniOS
. This is becauseiOS
use aFull Keyboard Access
system that provides commands for interacting with the system. Rather than holding down the spacebar, you can useTab+M
(the default action for opening the context menu). You can changeCommands
in:Full Keyboard Access
->Commands
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> |
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 |
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 |
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
export type OnKeyPress = NativeSyntheticEvent<{
keyCode: number;
unicode: number;
unicodeChar: string;
isLongPress: boolean;
isAltPressed: boolean;
isShiftPressed: boolean;
isCtrlPressed: boolean;
isCapsLockOn: boolean;
hasNoModifiers: boolean;
}>;
MIT
Made with create-react-native-library