React Native Keyboard Composer

The example application showcases three primary components/concepts from the library:

1. KeyboardComposer: A native text input component designed for smooth keyboard tracking and animations.
2. KeyboardAwareWrapper: A wrapper for scroll views that manages intelligent keyboard behavior:
   • If the view is at the bottom when the keyboard opens, it stays at the bottom.
   • If the view is scrolled up when the keyboard opens, the keyboard opens over the content without forcing a scroll.
3. LegendList: Used in the example as a high-performance list for rendering chat messages.

If you are contributing to the @launchhq/react-native-keyboard-composer library and want the example app to use your local unreleased code instead of the npm package, use the local development commands.

Note: If you need TypeScript path mapping to point to the local ../src directory, temporarily copy tsconfig.local.json to tsconfig.json.

After making changes to the native Android or iOS code within the package, you must re-run the local prebuild and run commands.

pnpm use:local
pnpm prebuild:local
pnpm android:local
# or
pnpm ios:local

To run the provided chat application example, follow these steps to install dependencies, generate native projects, and launch the app on your device or emulator.

# Install dependencies
pnpm install

# Generate native projects
pnpm prebuild

# Run on iOS
pnpm ios

# Run on Android
pnpm android

When developing the react-native-keyboard-composer package itself or making native changes that you want to test immediately in the example app, you can use the USE_LOCAL_KEYBOARD_COMPOSER environment variable.

Setting USE_LOCAL_KEYBOARD_COMPOSER=1 configures Expo autolinking to look for the module in the parent directory (../). This allows native Android and iOS changes made within the package source to be picked up by the example app after performing a clean prebuild.

USE_LOCAL_KEYBOARD_COMPOSER=1 npx expo prebuild

The example project supports two modes of operation via the USE_LOCAL_KEYBOARD_COMPOSER environment variable. This allows developers to switch between using the published package from node_modules or developing against the local package source in a workspace.

• Default mode: If USE_LOCAL_KEYBOARD_COMPOSER is not set to "1", Metro behaves like a standard consumer, resolving the package from node_modules.
• Local mode: If USE_LOCAL_KEYBOARD_COMPOSER is set to "1", Metro uses a local configuration (metro.config.local.js) to resolve the package from the parent workspace, enabling real-time library development.

# To run the example using the local package source:
USE_LOCAL_KEYBOARD_COMPOSER=1 npx expo start

The expo-module.config.json file defines the native module entry points for the react-native-keyboard-composer package, enabling autolinking for both iOS (Apple) and Android platforms within an Expo environment.

• Apple (iOS): Uses the KeyboardComposerModule class.
• Android: Uses the expo.modules.launchhq.reactnativekeyboardcomposer.KeyboardComposerModule class.

{
  "platforms": ["apple", "android"],
  "apple": {
    "modules": ["KeyboardComposerModule"]
  },
  "android": {
    "modules": [
      "expo.modules.launchhq.reactnativekeyboardcomposer.KeyboardComposerModule"
    ]
  }
}

The KeyboardAwareWrapper is a native component used to wrap content (typically a ScrollView) to ensure it responds correctly to keyboard visibility.

Behavior (matching iOS):

• When scrolled to bottom + keyboard opens: The component automatically scrolls to keep content at the bottom.
• When NOT at bottom + keyboard opens: The keyboard opens over the content without triggering an automatic scroll.

Use extraBottomInset to account for the height of a composer/input bar and any additional gaps, as the keyboard height itself is handled natively.

<KeyboardAwareWrapper extraBottomInset={composerHeight + gap}>
  <ScrollView>...</ScrollView>
</KeyboardAwareWrapper>

If you are interacting with the underlying native view directly, use KeyboardComposerViewProps. Unlike the wrapper component, callbacks in this interface return event objects containing nativeEvent payloads.

Event Payloads

• TextEventPayload: { text: string }
• HeightEventPayload: { height: number }

Callback Signatures

• onChangeText: (event: { nativeEvent: TextEventPayload }) => void
• onSend: (event: { nativeEvent: TextEventPayload }) => void
• onHeightChange: (event: { nativeEvent: HeightEventPayload }) => void
• onKeyboardHeightChange: (event: { nativeEvent: HeightEventPayload }) => void

The constants object provides access to the native configuration values for the keyboard composer. These values define the default sizing and spacing behavior used by the native implementation.

Available constants:

• defaultMinHeight: The default minimum height for the composer.
• defaultMaxHeight: The default maximum height for the composer.
• contentGap: The default spacing/gap between content elements.

import { constants } from '@launchhq/react-native-keyboard-composer';

console.log(constants.defaultMinHeight);
console.log(constants.defaultMaxHeight);
console.log(constants.contentGap);

The KeyboardAwareWrapper accepts the following props to control its behavior and layout:

The library exports several TypeScript types for strict typing of props, refs, and event payloads:

• KeyboardComposerProps: Props for the main component.
• KeyboardComposerRef: The ref type for accessing the KeyboardComposer instance.
• KeyboardComposerViewProps: Props for the underlying view.
• KeyboardComposerConstants: The shape of the constants object.
• TextEventPayload: The data structure emitted during text events.
• HeightEventPayload: The data structure emitted during height change events.