docs: explain keyboard avoidance with native bottom tabs on iOS

docs/docs/docs/guides/handling-scrollview-insets.md

@@ -7,3 +7,43 @@ If you expirence issues with ScrollView content being below the tab bar, add `co
   {/* content */}
 </ScrollView>
 ```
+
+## Keyboard-avoiding fixed content on iOS
+
+On iPhone, tab scenes extend behind the tab bar, including the Liquid Glass tab
+bar on iOS 26+. A bottom-aligned control inside `KeyboardAvoidingView` therefore
+needs to reserve the tab bar height while the keyboard is closed. Keep the
+full-screen background on an outer view and apply the offset only to the
+keyboard-avoiding content. The following pattern is for a visible native bottom
+bar without a bottom accessory or `minimizeBehavior`:
+
+```tsx
+import { useBottomTabBarHeight } from 'react-native-bottom-tabs';
+import { KeyboardAvoidingView, Platform, View } from 'react-native';
+
+function Screen() {
+  const tabBarHeight = useBottomTabBarHeight();
+  const hasNativeBottomTabBar =
+    Platform.OS === 'ios' && !Platform.isPad && !Platform.isTV;
+
+  return (
+    <View style={{ flex: 1, backgroundColor: 'white' }}>
+      <KeyboardAvoidingView
+        behavior="padding"
+        style={{
+          flex: 1,
+          marginBottom: hasNativeBottomTabBar ? tabBarHeight : 0,
+        }}
+      >
+        {/* Bottom-aligned content */}
+      </KeyboardAvoidingView>
+    </View>
+  );
+}
+```
+
+Do not apply this offset to the entire tab scene: scenes intentionally extend
+behind translucent tab bars, and globally shortening them would also double
+offsets already based on `useBottomTabBarHeight`. Custom, hidden, minimized,
+sidebar, and accessory layouts should use spacing derived from their own visible
+bottom element instead of this fixed-content pattern.

packages/example-shared/src/App.tsx

@@ -46,6 +46,7 @@ import CustomTabBar from './Examples/CustomTabBar';
 import NativeBottomTabsTabBarHidden from './Examples/NativeBottomTabsTabBarHidden';
 import OriginalIconColors from './Examples/OriginalIconColors';
 import NativeBottomTabsOriginalIcons from './Examples/NativeBottomTabsOriginalIcons';
+import KeyboardAvoidingViewExample from './Examples/KeyboardAvoidingView';
 import { useLogger } from '@react-navigation/devtools';
 import LazyTabs from './Examples/LazyTabs';
 import { LogBox } from 'react-native';
@@ -198,6 +199,11 @@ const examples = [
     component: NativeBottomTabsOriginalIcons,
     name: 'Native Bottom Tabs with original icons',
   },
+  {
+    component: KeyboardAvoidingViewExample,
+    name: 'Keyboard Avoiding View',
+    screenOptions: { headerShown: false },
+  },
   { component: NativeBottomTabs, name: 'Native Bottom Tabs' },
   { component: JSBottomTabs, name: 'JS Bottom Tabs' },
   {

packages/example-shared/src/Examples/KeyboardAvoidingView.tsx

@@ -0,0 +1,102 @@
+import { createNativeBottomTabNavigator } from '@bottom-tabs/react-navigation';
+import {
+  KeyboardAvoidingView,
+  Platform,
+  StyleSheet,
+  Text,
+  TextInput,
+  View,
+} from 'react-native';
+import { useBottomTabBarHeight } from 'react-native-bottom-tabs';
+
+const Tab = createNativeBottomTabNavigator();
+
+function HomeScreen() {
+  const tabBarHeight = useBottomTabBarHeight();
+  const hasNativeBottomTabBar =
+    Platform.OS === 'ios' && !Platform.isPad && !Platform.isTV;
+
+  return (
+    <View style={styles.container}>
+      <KeyboardAvoidingView
+        behavior="padding"
+        style={[
+          styles.keyboardAvoidingView,
+          hasNativeBottomTabBar && { marginBottom: tabBarHeight },
+        ]}
+      >
+        <View style={styles.content}>
+          <Text style={styles.title}>KeyboardAvoidingView + Bottom Tabs</Text>
+          <View style={styles.spacer} />
+          <TextInput
+            testID="keyboard-avoiding-input"
+            style={styles.input}
+            placeholder="Tap here to open keyboard"
+            placeholderTextColor="#666"
+          />
+        </View>
+      </KeyboardAvoidingView>
+    </View>
+  );
+}
+
+function SettingsScreen() {
+  return (
+    <View style={styles.container}>
+      <Text>Settings</Text>
+    </View>
+  );
+}
+
+export default function KeyboardAvoidingViewExample() {
+  return (
+    <Tab.Navigator initialRouteName="Home">
+      <Tab.Screen
+        name="Home"
+        component={HomeScreen}
+        options={{
+          tabBarButtonTestID: 'keyboard-avoiding-home-tab',
+          tabBarIcon: () => require('../../assets/icons/article_dark.png'),
+        }}
+      />
+      <Tab.Screen
+        name="Settings"
+        component={SettingsScreen}
+        options={{
+          tabBarButtonTestID: 'keyboard-avoiding-settings-tab',
+          tabBarIcon: () => require('../../assets/icons/grid_dark.png'),
+        }}
+      />
+    </Tab.Navigator>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    backgroundColor: '#fff',
+  },
+  keyboardAvoidingView: {
+    flex: 1,
+  },
+  content: {
+    flex: 1,
+    padding: 20,
+    justifyContent: 'flex-end',
+  },
+  title: {
+    fontSize: 20,
+    fontWeight: 'bold',
+    marginBottom: 10,
+  },
+  spacer: {
+    flex: 1,
+  },
+  input: {
+    borderWidth: 1,
+    borderColor: '#555',
+    borderRadius: 8,
+    padding: 15,
+    fontSize: 16,
+  },
+});