React Native Keyboard Handling

Make the keyboard feel native on both platforms by mapping two fundamentally
different OS keyboard models onto one animated value that your UI binds to.

The core mental model (read this first)

iOS and Android expose the keyboard in incompatible ways. Most "broken keyboard"
bugs come from ignoring this asymmetry.

• iOS = scheduled animation. The OS tells you up front: "the keyboard will
  slide from A to B over 0.25s with this easing curve." You get two snapshots
  (start/end) plus duration and curve — not intermediate frames. UIKit
  interpolates for you.
• Android (modern, edge-to-edge) = per-frame insets. The IME is just another
  system window. You get a firehose of frames, one inset value per frame, and
  you drive the animation yourself.

Anything that ignores this asymmetry will feel broken. The fix is to map both
models onto a single shared animated value, then have every consumer (padded
container, translated footer, scroll offset) bind to that one value and stop
caring which platform feeds it.

Decision guide — which tool to reach for

Situation	Use
Whole screen / single input should stay above keyboard	KeyboardAvoidingView (from react-native-keyboard-controller)
Scrollable form with multiple inputs	KeyboardAwareScrollView
One element pinned above the keyboard (footer, send bar, toolbar)	KeyboardStickyView
Fully custom animation tied to keyboard position	useReanimatedKeyboardAnimation() / useKeyboardHandler() + Reanimated SharedValue

Default recommendation: use
`react-native-keyboard-controller`,
not React Native's built-in KeyboardAvoidingView. The built-in version relies
on LayoutAnimation and the late keyboardDidShow event, which has no per-frame
Android primitive — so Android content snaps instead of sliding and the timing
never matches the keyboard curve.

Setup

1. Install the library and its peer deps:

   npm install react-native-keyboard-controller react-native-reanimated

2. Wrap your app root once in KeyboardProvider. This installs the native
   WindowInsetsAnimationCallback subscription on Android and handles
   edge-to-edge automatically:

   import { KeyboardProvider } from "react-native-keyboard-controller";
   
   export default function App() {
     return (
       <KeyboardProvider>
         {/* ...rest of the app */}
       </KeyboardProvider>
     );
   }

Patterns

Single input / simple screen — drop-in replacement

Same API as RN's KeyboardAvoidingView; swapping the import alone fixes the
Android timing/snap problems.

import { KeyboardAvoidingView } from "react-native-keyboard-controller";

<KeyboardAvoidingView behavior="padding" style={{ flex: 1 }}>
  {/* input(s) */}
</KeyboardAvoidingView>

Scrollable form — track the focused input

Auto-scrolls the minimum distance to keep the focused input (and caret/selection)
above the keyboard, using the same curve as the keyboard motion. bottomOffset
adds breathing room between the input and the keyboard top.

import { KeyboardAwareScrollView } from "react-native-keyboard-controller";

<KeyboardAwareScrollView bottomOffset={50} style={{ flex: 1 }}>
  <TextInput placeholder="Field 1" />
  <TextInput placeholder="Field 2" />
  {/* more inputs */}
</KeyboardAwareScrollView>

Sticky footer / send bar — translate one element only

Translates a single element instead of recomputing flex layout for the whole
screen. offset controls the gap when the keyboard is open vs closed.

import { KeyboardStickyView } from "react-native-keyboard-controller";

<KeyboardStickyView offset={{ closed: 0, opened: 20 }}>
  <Footer />
</KeyboardStickyView>

Custom animation — bind to the shared keyboard value

For fully bespoke motion, read the keyboard height as a Reanimated SharedValue
and drive any style from it. Works identically on both platforms because the
library already merged the two OS models into this one value.

import { useReanimatedKeyboardAnimation } from "react-native-keyboard-controller";
import Animated, { useAnimatedStyle } from "react-native-reanimated";

const { height } = useReanimatedKeyboardAnimation(); // SharedValue, per-frame
const style = useAnimatedStyle(() => ({
  transform: [{ translateY: height.value }],
}));

<Animated.View style={style}>{/* ... */}</Animated.View>;

Pitfalls & gotchas

• Android 15 / SDK 35 covers your inputs. Edge-to-edge is forced by default
  from Android 15 (API 35). The system no longer resizes the window when the
  keyboard appears, so the old adjustResize / windowSoftInputMode contract
  silently breaks — inputs get covered even though the exact same code worked on
  Android 14. KeyboardProvider handles edge-to-edge for you; don't rely on
  adjustResize.
• will* events never fire on Android. keyboardWillShow / keyboardWillHide
  have no underlying Android primitive, and keyboardDidShow fires after the
  animation finishes — too late to animate in sync. Don't build animations on
  the raw Keyboard event listeners for Android.
• Stock KeyboardAvoidingView + Android = snap, not slide. It uses
  LayoutAnimation, whose timing doesn't match the keyboard curve on Android, so
  motion looks janky. Prefer the keyboard-controller version.
• Version fragmentation is real. Behavior that "works" on Android 10 can break
  differently on Android 11 and again on Android 15. Use a library that abstracts
  the OS differences instead of hand-rolling per-version logic.
• Wrong component for the job. Using KeyboardAvoidingView for a multi-input
  form won't track which input is focused, so the caret can stay hidden — use
  KeyboardAwareScrollView. Using it to move a single footer forces an
  unnecessary full-screen layout recompute — use KeyboardStickyView.

Why the asymmetry exists (native reference)

Useful when debugging at the native layer or explaining the design.

• iOS surface: NotificationCenter keyboard notifications carry
  keyboardFrameEndUserInfoKey (final frame), keyboardAnimationDurationUserInfoKey
  (timing), and keyboardAnimationCurveUserInfoKey (a private curve,
  UIView.AnimationCurve(rawValue: 7)). Two snapshots, not frames.
• Android surface: WindowInsetsAnimationCallback with four hooks —
  onPrepare(), onStart(insets), onProgress(insets, runningAnimations) (fires
  every frame), onEnd(). The library subscribes here and writes each frame's
  inset into the shared value; on Android 11 it polyfills the per-frame stream
  where native support is missing.

Source

Based on Margelo's The Go-To Guide for Understanding Keyboards in React Native (Part 1):
https://blog.margelo.com/deep-dive-in-keyboard-handling