React-native-ios-keyboard-events NPM

react-native-ios-keyboard-events

A react-native library to detect an Apple iOS device's keyboard state.

Especially useful if you need to detect a split keyboard on an iPad (so that you can make UI adjustments to accomodate it)

Works ✨nicely✨ with KeyboardAvoidingView 👍🏻

GIF Demo of library

Example: AppDemo.tsx

Usage (tldr)

Install the library

npm install react-native-ios-keyboard-events

Create an IOSKeyboardEvents instance

import { createIOSKeyboardEvents } from "react-native-ios-keyboard-events";
const IOSKbEvents = createIOSKeyboardEvents();

Listen to keyboard state changes 😀

IOSKbEvents.addListener(
  "some-listener-name",
  (newKeyboardState, previousState) =>
    console.log(`transition: ${previousState} -> ${newKeyboardState}`),
);

Close it when you're done

IOSKbEvents.close();

API

Constructor

`createIOSKeyboardEvents(options)`

Creates an IOSKeyboardEvents instance.

This method will attempt to detect the device model type by checking the device's window resolution (via Dimensions.get). It will error out if it is unable to find a matching device or if the library is run in a non-iOS device.

options:

keyboardEventDebounceTime: (default: 100) Defines the time (in ms) to debounce sending updates to registered listeners. Increase to smoothen out keyboard state changes.

(Note: keyboard state changes may flicker on certain transitions eg. CLOSED -> DOCKED, due to the nature in which Apple sends out keyboard notifications and this library, in turn, interpreting the events)

deviceModel: Passes in a manually-defined IDeviceModel object. Useful when using custom keyboards. (note: if supplied, platform check will be ignored)

Instance Methods

`.addListener(listenerName: string, callback: (newKeyboardState, previousState) => void)`

Adds a listener to the IOSKeyboardEvents instance. Calls the callback on any keyboard state change.

Note: Adding a new listener will override any existing listeners with the same listenerName.

`.removeListener(listenerName: string)`

Removes the listener with the corresponding listenerName.

`.close()`

Gracefully closes the IOSKeyboardEvents instance by unsubscribing from keyboard events, listeners, and timers.

`.getKeyboardState()`

Returns the present keyboard state.

Possible KeyboardStates:

CLOSED
MINIMIZED
DOCKED
UNDOCKED
SPLIT
FLOATING (iOS v13)

`.setKeyboardState(newKeyboardState: KeyboardState)`

Sets the instance's tracked keyboard state. Use it if, for one reason or another, the IOSKeyboardEvents instance's internal state is inconsistent with the actual keyboard state. (eg. Keyboard is MINIMIZED but instance reports as the keyboard being DOCKED). This may occur as this library listens to Keyboard events to determine the keyboard state.

Throws an error if input is not a KeyboardState value.

Note: This method does NOT do keyboard actions (eg. dismissing the keyboard)