diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index c8f3d531b..88f1283f5 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -65,6 +65,9 @@ const config = { "1.10.0": { label: "1.10.0", }, + "1.11.0": { + label: "1.11.0", + }, }, }, blog: { diff --git a/docs/versioned_docs/version-1.11.0/api/_category_.json b/docs/versioned_docs/version-1.11.0/api/_category_.json new file mode 100644 index 000000000..ec554e17c --- /dev/null +++ b/docs/versioned_docs/version-1.11.0/api/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "API Reference", + "position": 4, + "link": { + "type": "generated-index", + "description": "API reference containing information about all public methods and their signatures" + } +} diff --git a/docs/versioned_docs/version-1.11.0/api/components/_category_.json b/docs/versioned_docs/version-1.11.0/api/components/_category_.json new file mode 100644 index 000000000..62ea2b32a --- /dev/null +++ b/docs/versioned_docs/version-1.11.0/api/components/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "📚 Components", + "position": 2 +} diff --git a/docs/versioned_docs/version-1.11.0/api/components/keyboard-avoiding-view.mdx b/docs/versioned_docs/version-1.11.0/api/components/keyboard-avoiding-view.mdx new file mode 100644 index 000000000..d9f9fe189 --- /dev/null +++ b/docs/versioned_docs/version-1.11.0/api/components/keyboard-avoiding-view.mdx @@ -0,0 +1,131 @@ +--- +keywords: + [ + react-native-keyboard-controller, + KeyboardAvoidingView, + keyboard avoiding view, + avoid keyboard, + android, + ] +--- + +# KeyboardAvoidingView + +This component will automatically adjust its height, position, or bottom padding based on the keyboard height to remain visible while the virtual keyboard is displayed. + +## Why another `KeyboardAvoidingView` is needed? + +This new `KeyboardAvoidingView` maintains the familiar React Native [API](https://reactnative.dev/docs/keyboardavoidingview) but ensures consistent behavior and animations on both `iOS` and `Android` platforms. Unlike the existing solution, which primarily caters to `iOS`, this component eliminates platform discrepancies, providing a unified user experience. By reproducing the same animations and behaviors on both platforms, it simplifies cross-platform development, meets user expectations for consistency, and enhances code maintainability. Ultimately, it addresses the need for a reliable and uniform keyboard interaction solution across different devices. + +Below is a visual difference between the implementations (the animation is _**4x**_ times slower for better visual perception). + +import KeyboardAvoidingViewComparison from "@site/src/components/KeyboardAvoidingViewComparison"; + + + +:::info Found a bug? Help the project and report it! + +If you found any bugs or inconsistent behavior comparing to `react-native` implementation - don't hesitate to open an [issue](https://github.com/kirillzyusko/react-native-keyboard-controller/issues/new?assignees=kirillzyusko&labels=bug&template=bug_report.md&title=). It will help the project 🙏 + +Also if there is any well-known problems in original `react-native` implementation which can not be fixed for a long time and they are present in this implementation as well - also feel free to submit an [issue](https://github.com/kirillzyusko/react-native-keyboard-controller/issues/new?assignees=kirillzyusko&labels=bug&template=bug_report.md&title=). Let's make this world better together 😎 + +::: + +## Example + +```tsx +import React from "react"; +import { + Text, + TextInput, + TouchableOpacity, + View, + StyleSheet, +} from "react-native"; +import { KeyboardAvoidingView } from "react-native-keyboard-controller"; + +export default function KeyboardAvoidingViewExample() { + return ( + + + Header + + + + + + Submit + + + + ); +} + +const styles = StyleSheet.create({ + container: { + flex: 1, + }, + content: { + flex: 1, + maxHeight: 600, + }, + heading: { + fontSize: 36, + marginBottom: 48, + fontWeight: "600", + }, + inner: { + padding: 24, + flex: 1, + justifyContent: "space-between", + }, + textInput: { + height: 45, + borderColor: "#000000", + borderWidth: 1, + borderRadius: 10, + marginBottom: 36, + paddingLeft: 10, + }, + button: { + marginTop: 12, + height: 45, + borderRadius: 10, + backgroundColor: "rgb(40, 64, 147)", + justifyContent: "center", + alignItems: "center", + }, + text: { + fontWeight: "500", + fontSize: 16, + color: "white", + }, +}); +``` + +## Props + +### `behavior` + +Specify how to react to the presence of the keyboard. Could be one value of: + +- `position` +- `padding` +- `height` + +### `contentContainerStyle` + +The style of the content container (View) when behavior is `position`. + +### `enabled` + +A boolean prop indicating whether `KeyboardAvoidingView` is enabled or disabled. Default is `true`. + +### `keyboardVerticalOffset` + +This is the distance between the top of the user screen and the react native view, may be non-zero in some use cases. Default is `0`. diff --git a/docs/versioned_docs/version-1.11.0/api/components/keyboard-aware-scroll-view.mdx b/docs/versioned_docs/version-1.11.0/api/components/keyboard-aware-scroll-view.mdx new file mode 100644 index 000000000..f7de074fa --- /dev/null +++ b/docs/versioned_docs/version-1.11.0/api/components/keyboard-aware-scroll-view.mdx @@ -0,0 +1,147 @@ +--- +keywords: + [ + react-native-keyboard-controller, + KeyboardAwareScrollView, + keyboard aware view, + aware scroll view, + ] +--- + +# KeyboardAwareScrollView + +import Lottie from "lottie-react"; +import lottie from "@site/src/components/HomepageFeatures/text-inputs.lottie.json"; + +
+ +
+ +`ScrollView` that effortlessly handles keyboard appearance, automatically scrolls to focused `TextInput` and provides a native-like performance. + +## Comparison + +Current `react-native` ecosystem has a plenty of solutions that solves the problem of focused inputs being covered by keyboard. Each of them has its own advantages and disadvantages. + +Below is a table with the most important functions and their support in various implementations: + +| | [react-native-avoid-soft-input](https://mateusz1913.github.io/react-native-avoid-softinput/) | [react-native-keyboard-aware-scroll-view](https://github.com/APSL/react-native-keyboard-aware-scroll-view) | [react-native-keyboard-manager](https://github.com/douglasjunior/react-native-keyboard-manager) | [react-native-keyboard-controller](./keyboard-aware-scroll-view.mdx) | +| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | +| Respects keyboard animation | 🟠 1 | ❌ | ✅ | ✅ | +| JS implementation | ❌ | ✅ | ❌ | 🟠 2 | +| Reacts on focused input layout changes | ❌ | ❌ | 🟠 3 | ✅ | +| Reacts on focus changes | ✅ | ✅ | ✅ | ✅ | +| Auto-scroll when user is typing and input in non visible area | ❌ | ❌ | 🟠 3 | ✅ | +| Android support | ✅ | ✅ | ❌ | ✅ | +| Maintained | ✅ | ❌ | ✅ | ✅ | +| Support Fabric (new) architecture | ✅ | 🟠 4 | ❌ | ✅ | + +> 1 only on iOS + +> 2 KeyboardAwareScrollView is implemented in JS, but some +> hooks (useKeyboardHandler/useReanimatedFocusedInput/ +> useFocusedInputHandler +> ) exposed from native code + +> 3 achievable with +> KeyboardManager.reloadLayoutIfNeeded() +> usage in appropriate TextInput callbacks ( +> onLayout +> /onChangeText) + +> 4 since it's JS based solution it supports new architecture, but it +> uses deprecated API. + +## Props + +### ScrollView Props + +Inherits [ScrollView Props](https://reactnative.dev/docs/scrollview#props). + +### `bottomOffset` + +The distance between keyboard and focused `TextInput` when keyboard is shown. Default is `0`. + +### `disableScrollOnKeyboardHide` + +Prevents automatic scrolling of the `ScrollView` when the keyboard gets hidden, maintaining the current screen position. Default is `false`. + +### `enabled` + +A boolean prop indicating whether `KeyboardAwareScrollView` is enabled or disabled. Default is `true`. + +## Example + +```tsx +import React from "react"; +import { + StyleSheet, + TextInputProps, + TextInput as TextInputRN, +} from "react-native"; +import { KeyboardAwareScrollView } from "react-native-keyboard-controller"; + +const TextInput = (props: TextInputProps) => { + return ( + + ); +}; + +export default function AwareScrollView() { + return ( + + {new Array(10).fill(0).map((_, i) => ( + + ))} + + ); +} + +const styles = StyleSheet.create({ + container: { + paddingHorizontal: 16, + }, + content: { + paddingTop: 50, + }, + textInput: { + width: "100%", + minHeight: 50, + maxHeight: 200, + marginBottom: 50, + borderColor: "black", + borderWidth: 2, + marginRight: 160, + borderRadius: 10, + color: "black", + paddingHorizontal: 12, + }, +}); +``` + +## Known issues + +- [react-native-reanimated#5567](https://github.com/software-mansion/react-native-reanimated/issues/5567): Resizing content inside `ScrollView` prevents multiline `TextInput` from growing in Fabric diff --git a/docs/versioned_docs/version-1.11.0/api/components/keyboard-sticky-view/index.mdx b/docs/versioned_docs/version-1.11.0/api/components/keyboard-sticky-view/index.mdx new file mode 100644 index 000000000..7a231cc2f --- /dev/null +++ b/docs/versioned_docs/version-1.11.0/api/components/keyboard-sticky-view/index.mdx @@ -0,0 +1,64 @@ +--- +keywords: + [ + react-native-keyboard-controller, + KeyboardStickyView, + keyboard sticky view, + keyboard sticky footer, + sticky view, + sticky footer, + keyboard, + android, + ] +--- + +# KeyboardStickyView + +A `KeyboardStickyView` component seamlessly ensures that a designated view sticks to the keyboard's movements, maintaining visibility and interaction. Use it when you want to enhance the user experience by preventing important UI elements from being obscured by the keyboard, creating a smooth and user-friendly interface in your React Native application. + +:::info `KeyboardAvoidingView` vs `KeyboardStickyView` +Unlike [KeyboardAvoidingView](../keyboard-avoiding-view.mdx) the `KeyboardStickyView` just moves the content along with keyboard and not resizing the inner view. Try to compare animations of `KeyboardStickyView` and `KeyboardAvoidingView` to see a difference in details on how it works and which component is suitable for your needs. +::: + +import ksv from "./ksv.lottie.json"; +import kav from "@site/src/components/KeyboardAvoidingViewComparison/kav-animated.lottie.json"; +import ComparisonTable from "@site/src/components/ComparisonTable"; + + + KeyboardStickyView - only footer is moving (container is not + resized) + + } + rightText={ + + KeyboardAvoidingView - entire container is getting resized + + } +/> + +## Example + +```tsx +const offset = { closed: 0, opened: 20 }; + +const StickyFooter = () => { + return ( + +