docs: provide static and dynamic examples

lukewalczak · lukewalczak · commit f9a7703ae846 · 2025-04-30T11:05:55.000+02:00
diff --git a/docs/component-docs-plugin/generatePageMDX.js b/docs/component-docs-plugin/generatePageMDX.js
@@ -166,6 +166,22 @@ function generateExtendsAttributes(doc) {
   return extendsAttributes;
 }
 
+function generateExtendedExamples(usage, extendedExamplesData) {
+  if (!extendedExamplesData) {
+    return usage;
+  }
+
+  const data = JSON.parse(extendedExamplesData);
+  const exampleHeader = Object.keys(data)[0];
+
+  return `
+  ${usage}
+
+  ### ${exampleHeader}
+  <ExtendedExample extendedExamplesData={${extendedExamplesData}} />
+  `;
+}
+
 function generatePageMDX(doc, link) {
   const summaryRegex = /([\s\S]*?)## Usage/;
 
@@ -182,6 +198,9 @@ function generatePageMDX(doc, link) {
 
   const themeColorsData = JSON.stringify(customFields.themeColors[doc.title]);
   const screenshotData = JSON.stringify(customFields.screenshots[doc.title]);
+  const extendedExamplesData = JSON.stringify(
+    customFields.extendedExamples[doc.title]
+  );
 
   const extendsAttributes = generateExtendsAttributes(doc);
 
@@ -194,12 +213,13 @@ import PropTable from '@site/src/components/PropTable.tsx';
 import ExtendsLink from '@site/src/components/ExtendsLink.tsx';
 import ThemeColorsTable from '@site/src/components/ThemeColorsTable.tsx';
 import ScreenshotTabs from '@site/src/components/ScreenshotTabs.tsx';
+import ExtendedExample from '@site/src/components/ExtendedExample.tsx';
 
 ${summary}
 
 ${generateScreenshots(doc.title, screenshotData)}
 
-${usage}
+${generateExtendedExamples(usage, extendedExamplesData)}
 
 ${generatePropsTable(doc.data.props, link, extendsAttributes)}
 
diff --git a/docs/docs/guides/09-bottom-navigation.md b/docs/docs/guides/09-bottom-navigation.md
@@ -3,38 +3,11 @@ title: Using BottomNavigation with React Navigation
 ---
 
 :::caution
-`createMaterialBottomTabNavigator` has been deprecated since `react-native-paper@5.14.0`. Please use `@react-navigation/bottom-tabs` version `7.x` or higher and combine it with `BottomNavigation.Bar` for a Material Design look.
-
-```js
-import { createBottomTabNavigator } from '@react-navigation/bottom-tabs';
-import { BottomNavigation } from 'react-native-paper';
-
-const Tab = createBottomTabNavigator();
-
-function MyTabs() {
-  return (
-    <Tab.Navigator
-      tabBar={({ navigation, state, descriptors, insets }) => (
-        <BottomNavigation.Bar
-          ...
-        />
-      )}
-    >
-      <Tab.Screen name="Home" component={HomeScreen} />
-      <Tab.Screen name="Profile" component={ProfileScreen} />
-    </Tab.Navigator>
-  );
-}
-```
+The `createMaterialBottomTabNavigator` has been deprecated as of `react-native-paper@5.14.0`. Instead, use `@react-navigation/bottom-tabs` version `7.x` or later, combined with `BottomNavigation.Bar` to achieve a Material Design look.
 
+For implementation details, see the [dedicated example](https://callstack.github.io/react-native-paper/docs/components/BottomNavigation/BottomNavigationBar#with-react-navigation).
 :::
 
-> 👉 For a complete example please visit `createBottomTabNavigator` [snack](https://snack.expo.dev/@react-native-paper/createbottomtabnavigator-with-bottomnavigationbar).
-
----
-
-_For projects using `react-native-paper` < `5.14.0` and `react-navigation` < `7.x`, proceed as follows:_
-
 A material-design themed tab bar on the bottom of the screen that lets you switch between different routes with animation. Routes are lazily initialized - their screen components are not mounted until they are first focused.
 
 This wraps the [`BottomNavigation`](https://callstack.github.io/react-native-paper/docs/components/BottomNavigation/) component from `react-native-paper`, however if you [configure the Babel plugin](https://callstack.github.io/react-native-paper/docs/guides/getting-started/), it won't include the whole library in your bundle.
diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js
@@ -5,6 +5,7 @@ const path = require('path');
 const darkCodeTheme = require('prism-react-renderer/themes/dracula');
 const lightCodeTheme = require('prism-react-renderer/themes/github');
 
+const { extendedExamples } = require('./src/data/extendedExamples.js');
 const { screenshots } = require('./src/data/screenshots.js');
 const { themeColors } = require('./src/data/themeColors.js');
 
@@ -336,6 +337,7 @@ const config = {
     },
     themeColors,
     screenshots,
+    extendedExamples,
   },
 };
 
diff --git a/docs/src/components/ExtendedExample.tsx b/docs/src/components/ExtendedExample.tsx
@@ -0,0 +1,36 @@
+import React from 'react';
+
+//@ts-ignore
+import CodeBlock from '@theme/CodeBlock';
+//@ts-ignore
+import TabItem from '@theme/TabItem';
+//@ts-ignore
+import Tabs from '@theme/Tabs';
+
+interface ExtendedExampleProps {
+  extendedExamplesData: {
+    [key: string]: {
+      [key: string]: string;
+    };
+  };
+}
+
+const ExtendedExample = ({ extendedExamplesData }: ExtendedExampleProps) => {
+  const example = Object.values(extendedExamplesData)[0];
+
+  if (!example) return null;
+
+  const keys = Object.keys(example);
+
+  return (
+    <Tabs>
+      {keys.map((key) => (
+        <TabItem value={key} label={key} key={key}>
+          <CodeBlock language="jsx">{example[key]}</CodeBlock>
+        </TabItem>
+      ))}
+    </Tabs>
+  );
+};
+
+export default ExtendedExample;
diff --git a/docs/src/data/extendedExamples.js b/docs/src/data/extendedExamples.js
@@ -0,0 +1,17 @@
+const {
+  staticCode,
+  dynamicCode,
+} = require('./extendedExamples/BottomNavigationBar');
+
+const extendedExamples = {
+  'BottomNavigation.Bar': {
+    'with React Navigation': {
+      static: staticCode,
+      dynamic: dynamicCode,
+    },
+  },
+};
+
+module.exports = {
+  extendedExamples,
+};
diff --git a/docs/src/data/extendedExamples/BottomNavigationBar.js b/docs/src/data/extendedExamples/BottomNavigationBar.js
@@ -0,0 +1,202 @@
+const staticCode = `import { Text, View } from 'react-native';
+import { createBottomTabNavigator } from '@react-navigation/bottom-tabs';
+import { Provider, BottomNavigation } from 'react-native-paper';
+import MaterialCommunityIcons from '@expo/vector-icons/MaterialCommunityIcons';
+import {
+  CommonActions,
+  createStaticNavigation,
+} from '@react-navigation/native';
+
+function HomeScreen() {
+  return (
+    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
+      <Text>Home!</Text>
+    </View>
+  );
+}
+
+function SettingsScreen() {
+  return (
+    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
+      <Text>Settings!</Text>
+    </View>
+  );
+}
+
+const MyTabs = createBottomTabNavigator({
+  screenOptions: {
+    animation: 'shift',
+  },
+  tabBar: ({ navigation, state, descriptors, insets }) => (
+    <BottomNavigation.Bar
+      navigationState={state}
+      safeAreaInsets={insets}
+      onTabPress={({ route, preventDefault }) => {
+        const event = navigation.emit({
+          type: 'tabPress',
+          target: route.key,
+          canPreventDefault: true,
+        });
+
+        if (event.defaultPrevented) {
+          preventDefault();
+        } else {
+          navigation.dispatch({
+            ...CommonActions.navigate(route.name, route.params),
+            target: state.key,
+          });
+        }
+      }}
+      renderIcon={({ route, focused, color }) =>
+        descriptors[route.key].options.tabBarIcon?.({
+          focused,
+          color,
+          size: 24,
+        }) || null
+      }
+      getLabelText={({ route }) => {
+        const { options } = descriptors[route.key];
+        const label =
+          typeof options.tabBarLabel === 'string'
+            ? options.tabBarLabel
+            : typeof options.title === 'string'
+            ? options.title
+            : route.name;
+
+        return label;
+      }}
+    />
+  ),
+  screens: {
+    Home: {
+      screen: HomeScreen,
+      options: {
+        tabBarIcon: ({ color }) => (
+          <MaterialCommunityIcons name="home" color={color} size={26} />
+        ),
+      },
+    },
+    Profile: {
+      screen: SettingsScreen,
+      options: {
+        tabBarIcon: ({ color }) => (
+          <MaterialCommunityIcons name="cog" color={color} size={26} />
+        ),
+      },
+    },
+  },
+});
+
+const Navigation = createStaticNavigation(MyTabs);
+
+export default function App() {
+  return (
+    <Provider>
+      <Navigation>
+        <MyTabs />
+      </Navigation>
+    </Provider>
+  );
+}`;
+
+const dynamicCode = `import { Text, View } from 'react-native';
+import { NavigationContainer, CommonActions } from '@react-navigation/native';
+import { createBottomTabNavigator } from '@react-navigation/bottom-tabs';
+import { Provider, BottomNavigation } from 'react-native-paper';
+import MaterialCommunityIcons from '@expo/vector-icons/MaterialCommunityIcons';
+
+function HomeScreen() {
+  return (
+    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
+      <Text>Home!</Text>
+    </View>
+  );
+}
+
+function SettingsScreen() {
+  return (
+    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
+      <Text>Settings!</Text>
+    </View>
+  );
+}
+
+const Tab = createBottomTabNavigator();
+
+export default function App() {
+  return (
+    <Provider>
+      <NavigationContainer>
+        <Tab.Navigator
+          screenOptions={{
+            animation: 'shift',
+          }}
+          tabBar={({ navigation, state, descriptors, insets }) => (
+            <BottomNavigation.Bar
+              navigationState={state}
+              safeAreaInsets={insets}
+              onTabPress={({ route, preventDefault }) => {
+                const event = navigation.emit({
+                  type: 'tabPress',
+                  target: route.key,
+                  canPreventDefault: true,
+                });
+
+                if (event.defaultPrevented) {
+                  preventDefault();
+                } else {
+                  navigation.dispatch({
+                    ...CommonActions.navigate(route.name, route.params),
+                    target: state.key,
+                  });
+                }
+              }}
+              renderIcon={({ route, focused, color }) =>
+                descriptors[route.key].options.tabBarIcon?.({
+                  focused,
+                  color,
+                  size: 24,
+                }) || null
+              }
+              getLabelText={({ route }) => {
+                const { options } = descriptors[route.key];
+                const label =
+                  typeof options.tabBarLabel === 'string'
+                    ? options.tabBarLabel
+                    : typeof options.title === 'string'
+                    ? options.title
+                    : route.name;
+
+                return label;
+              }}
+            />
+          )}>
+          <Tab.Screen
+            name="Home"
+            component={HomeScreen}
+            options={{
+              tabBarIcon: ({ color }) => (
+                <MaterialCommunityIcons name="home" color={color} size={26} />
+              ),
+            }}
+          />
+          <Tab.Screen
+            name="Settings"
+            component={SettingsScreen}
+            options={{
+              tabBarIcon: ({ color }) => (
+                <MaterialCommunityIcons name="cog" color={color} size={26} />
+              ),
+            }}
+          />
+        </Tab.Navigator>
+      </NavigationContainer>
+    </Provider>
+  );
+}
+`;
+
+module.exports = {
+  staticCode,
+  dynamicCode,
+};
diff --git a/src/components/BottomNavigation/BottomNavigationBar.tsx b/src/components/BottomNavigation/BottomNavigationBar.tsx
