|
| 1 | +--- |
| 2 | +sidebar_position: 4 |
| 3 | +description: Overview and comparison of view and components available in this package |
| 4 | +keywords: |
| 5 | + [ |
| 6 | + react-native-keyboard-controller, |
| 7 | + components, |
| 8 | + views, |
| 9 | + over keyboard view, |
| 10 | + keyboard toolbar, |
| 11 | + keyboard avoiding view, |
| 12 | + keyboard sticky view, |
| 13 | + keyboard aware scroll view, |
| 14 | + KeyboardAvoidingView, |
| 15 | + KeyboardStickyView, |
| 16 | + KeyboardAwareScrollView, |
| 17 | + KeyboardToolbar, |
| 18 | + OverKeyboardView, |
| 19 | + ] |
| 20 | +--- |
| 21 | + |
| 22 | +# Components Overview |
| 23 | + |
| 24 | +This guide provides a concise overview of the main UI components in `react-native-keyboard-controller`. Choose the right component to handle keyboard interactions smoothly and consistently across platforms. |
| 25 | + |
| 26 | +## [`KeyboardAvoidingView`](../api/components/keyboard-avoiding-view) |
| 27 | + |
| 28 | +import Lottie from "lottie-react"; |
| 29 | + |
| 30 | +import KeyboardAvoidingView from "@site/src/components/KeyboardAvoidingViewComparison/kav-animated.lottie.json"; |
| 31 | +import KeyboardAwareScrollView from "@site/src/components/HomepageFeatures/text-inputs.lottie.json"; |
| 32 | + |
| 33 | +import KeyboardStickyView from "../api/components/keyboard-sticky-view/ksv.lottie.json"; |
| 34 | +import KeyboardToolbar from "../api/components/keyboard-toolbar/toolbar.lottie.json"; |
| 35 | +import OverKeyboardView from "../api/over-keyboard-view/over-keyboard-view.lottie.json"; |
| 36 | + |
| 37 | +<div style={{ display: "flex", justifyContent: "center", marginBottom: 20 }}> |
| 38 | + <Lottie |
| 39 | + className="lottie" |
| 40 | + animationData={KeyboardAvoidingView} |
| 41 | + style={{ width: 400, height: 400 }} |
| 42 | + loop |
| 43 | + /> |
| 44 | +</div> |
| 45 | + |
| 46 | +Use `KeyboardAvoidingView` when you need to prevent the keyboard from hiding important UI elements, especially `TextInput` components. It automatically adjusts its layout—by changing its height, position, or padding—when the keyboard appears. A key advantage over the standard React Native component is its focus on _consistent behavior and smoother animations_ across both iOS and Android, simplifying cross-platform development. It's ideal for general screens like forms or chat interfaces. |
| 47 | + |
| 48 | +You can control how it adjusts using the `behavior` prop (`padding`, `height`, `position`, `translate-with-padding`), and remember to set `keyboardVerticalOffset` if your view is positioned below a header or navigation bar. |
| 49 | + |
| 50 | +## [`KeyboardStickyView`](../api/components/keyboard-sticky-view) |
| 51 | + |
| 52 | +`KeyboardStickyView` is designed specifically to make a view "sticky" to the top edge of the keyboard, moving perfectly in sync with it as it animates. |
| 53 | + |
| 54 | +import ComparisonTable from "@site/src/components/ComparisonTable"; |
| 55 | +import ComparableLottie from "@site/src/components/Lottie"; |
| 56 | + |
| 57 | +<ComparisonTable |
| 58 | + left={<ComparableLottie src={KeyboardStickyView} />} |
| 59 | + right={<ComparableLottie src={KeyboardAvoidingView} />} |
| 60 | + leftText={ |
| 61 | + <i> |
| 62 | + <code>KeyboardStickyView</code> - only footer is moving (container is not |
| 63 | + resized) |
| 64 | + </i> |
| 65 | + } |
| 66 | + rightText={ |
| 67 | + <i> |
| 68 | + <code>KeyboardAvoidingView</code> - entire container is getting resized |
| 69 | + </i> |
| 70 | + } |
| 71 | +/> |
| 72 | + |
| 73 | +Unlike `KeyboardAvoidingView`, it achieves this using only _vertical translation_, meaning it moves the child view up and down without resizing the surrounding layout. This makes it the perfect choice for elements like custom input toolbars, action buttons, or footers that need to remain visually attached just above the keyboard during text input. |
| 74 | + |
| 75 | +You can use the `offset` prop to fine-tune its vertical position relative to the keyboard's edge. |
| 76 | + |
| 77 | +## [`KeyboardAwareScrollView`](../api/components/keyboard-aware-scroll-view) |
| 78 | + |
| 79 | +<div style={{ display: "flex", justifyContent: "center", marginBottom: 20 }}> |
| 80 | + <Lottie |
| 81 | + className="lottie" |
| 82 | + animationData={KeyboardAwareScrollView} |
| 83 | + style={{ width: 400, height: 400 }} |
| 84 | + loop |
| 85 | + /> |
| 86 | +</div> |
| 87 | + |
| 88 | +For screens with scrollable content and multiple inputs, such as forms or long lists, `KeyboardAwareScrollView` is the component to use. It's a specialized `ScrollView` that automatically scrolls its content to ensure the currently focused `TextInput` remains visible and isn't hidden by the keyboard. It stands out by providing smoother scrolling that respects native keyboard animations on both platforms and reacting reliably to layout changes, often proving more robust than older libraries or manual setups. |
| 89 | + |
| 90 | +Key props like `bottomOffset` help control the spacing below the focused input, while `extraKeyboardSpace` can add padding at the bottom when needed. |
| 91 | + |
| 92 | +## [`KeyboardToolbar`](../api/components/keyboard-toolbar) |
| 93 | + |
| 94 | +<div style={{ display: "flex", justifyContent: "center", marginBottom: 20 }}> |
| 95 | + <Lottie |
| 96 | + className="lottie" |
| 97 | + animationData={KeyboardToolbar} |
| 98 | + style={{ width: 400, height: 400 }} |
| 99 | + loop |
| 100 | + /> |
| 101 | +</div> |
| 102 | + |
| 103 | +To enhance the usability of forms with multiple `TextInput` fields, consider `KeyboardToolbar`. It provides a ready-made, customizable toolbar designed to stick to the top of the keyboard, typically featuring "Previous" and "Next" buttons for easy input navigation, and a "Done" button for dismissing the keyboard. |
| 104 | + |
| 105 | +A major benefit is its use of the library's native focus control logic (`KeyboardController.setFocusTo`), simplifying development by handling the complexities of switching focus between inputs for you. It's highly customizable in appearance and behavior, allowing seamless integration into your app's design. |
| 106 | + |
| 107 | +## [`OverKeyboardView`](../api/over-keyboard-view) |
| 108 | + |
| 109 | +<div style={{ display: "flex", justifyContent: "center", marginBottom: 20 }}> |
| 110 | + <Lottie |
| 111 | + className="lottie" |
| 112 | + animationData={OverKeyboardView} |
| 113 | + style={{ width: 400, height: 400 }} |
| 114 | + loop |
| 115 | + /> |
| 116 | +</div> |
| 117 | + |
| 118 | +`OverKeyboardView` offers a unique capability: it allows you to render any React Native view _on top_ of both your application UI _and_ the virtual keyboard, crucially _without_ causing the keyboard to be dismissed. This is ideal for creating experiences where supplementary UI elements, like context menu can appear. |
| 119 | + |
| 120 | +Its key difference from a standard `Modal` is precisely this ability to keep the keyboard open and active, enabling more seamless keyboard-centric interactions. Its usage is straightforward, primarily controlled via the `visible` boolean prop. |
| 121 | + |
| 122 | +## Quick Reference Table |
| 123 | + |
| 124 | +| Component | Primary Action When Keyboard Appears | Container Resizes/Adjusts? | Typical Use Case | Key Distinction vs. Others | |
| 125 | +| ------------------------- | ------------------------------------------ | -------------------------- | ---------------------------- | --------------------------------------------------------- | |
| 126 | +| `KeyboardAvoidingView` | Adjusts layout (padding, position, height) | ✅ | Small Forms, Chat Screens | Consistent cross-platform avoidance, layout adjustment | |
| 127 | +| `KeyboardStickyView` | Moves/Translates view with keyboard | ❌ (moves child only) | Sticky Footer/Toolbar | Moves element without resizing layout | |
| 128 | +| `KeyboardAwareScrollView` | Scrolls content to focused input | ✅ (scroll position) | Large Scrollable Forms/Lists | Auto-scrolls within ScrollView, respects native animation | |
| 129 | +| `KeyboardToolbar` | Adds Nav/Done buttons, sticks to keyboard | ❌ (it's sticky) | Multi-Input Forms | Provides UI + native logic for input navigation/dismissal | |
| 130 | +| `OverKeyboardView` | Displays content _over_ the keyboard | ❌ (overlays content) | Menus, Modals over keyboard | Keeps keyboard open while showing overlay content | |
| 131 | + |
| 132 | +## Which Component Should You Use? |
| 133 | + |
| 134 | +Here's a simple guide to choosing: |
| 135 | + |
| 136 | +- If your primary goal is to **prevent the keyboard from hiding inputs** on a standard screen, start with `KeyboardAvoidingView`. |
| 137 | +- If you need a specific element like a **footer or toolbar to move smoothly with the keyboard**, `KeyboardStickyView` is designed for that task. |
| 138 | +- For **scrollable screens containing multiple inputs** (like forms or long lists), `KeyboardAwareScrollView` will handle keeping the focused input visible automatically. |
| 139 | +- To add standard **"Previous/Next/Done" navigation buttons** to your forms, `KeyboardToolbar` offers a convenient and customizable solution. |
| 140 | +- When you need to display **contextual content like suggestions or menus over an active keyboard** without dismissing it, `OverKeyboardView` provides this unique capability. |
| 141 | + |
| 142 | +This library offers specialized tools for common keyboard challenges in React Native. Choose the one that best fits your UI need. |
0 commit comments