feat: add navigation rail

docs/6.x/docs/guides/migration.md

@@ -135,6 +135,25 @@ The `style` props for `Appbar` and `Appbar.Header` no longer accept `Animated.Va
 
 The `style.elevation` property is no longer supported. Use the `elevated` prop to control Appbar elevation.
 
+### Drawer
+
+`NavigationRail` is the Material Design 3 replacement for `Drawer.CollapsedItem` and the drawer-based side navigation. It supports a collapsed (96dp) and expanded (220–360dp) layout, a header slot for a menu button and `FAB`, and a modal variant.
+
+```diff
+- <View>
+-   <Drawer.CollapsedItem focusedIcon="inbox" unfocusedIcon="inbox-outline" label="Inbox" active />
+-   <Drawer.CollapsedItem focusedIcon="send" unfocusedIcon="send-outline" label="Sent" />
+- </View>
++ <NavigationRail expanded={expanded}>
++   <NavigationRail.Item icon="inbox-outline" activeIcon="inbox" label="Inbox" active />
++   <NavigationRail.Item icon="send-outline" activeIcon="send" label="Sent" />
++ </NavigationRail>
+```
+
+- **`focusedIcon` / `unfocusedIcon`** → **`activeIcon` / `icon`**
+- Expanded rows replace `Drawer.Item`; toggle them with the `expanded` prop instead of rendering a different component.
+- Use `NavigationRail.Modal` inside a `Portal` where a temporary drawer was used before.
+
 ### Surface
 
 - The `elevation` prop no longer accepts a React Native `Animated.Value`. Any `elevation` changes are animated automatically.

docs/component-docs.config.ts

@@ -115,6 +115,11 @@ const pages = {
     MenuItem: 'Menu/MenuItem',
   },
   Modal: 'Modal',
+  NavigationRail: {
+    NavigationRail: 'NavigationRail/NavigationRail',
+    NavigationRailItem: 'NavigationRail/NavigationRailItem',
+    NavigationRailModal: 'NavigationRail/NavigationRailModal',
+  },
   Portal: {
     Portal: {
       source: 'Portal/Portal',

docs/src/data/themeColors.ts

@@ -264,6 +264,31 @@ export const themeColors = {
       backgroundColor: 'theme.colors.backdrop',
     },
   },
+  NavigationRail: {
+    collapsed: {
+      backgroundColor: 'theme.colors.surface',
+    },
+    expanded: {
+      backgroundColor: 'theme.colors.surfaceContainer',
+    },
+  },
+  'NavigationRail.Item': {
+    active: {
+      indicatorColor: 'theme.colors.secondaryContainer',
+      iconColor: 'theme.colors.onSecondaryContainer',
+      'textColor (collapsed)': 'theme.colors.secondary',
+      'textColor (expanded)': 'theme.colors.onSecondaryContainer',
+    },
+    inactive: {
+      'iconColor/textColor': 'theme.colors.onSurfaceVariant',
+    },
+  },
+  'NavigationRail.Modal': {
+    '-': {
+      backgroundColor: 'theme.colors.surfaceContainer',
+      scrimColor: 'theme.colors.scrim',
+    },
+  },
   ProgressBar: {
     '-': {
       tintColor: 'theme.colors.primary',

example/src/ExampleList.tsx

@@ -27,6 +27,7 @@ import ListAccordionExampleGroup from './Examples/ListAccordionGroupExample';
 import ListItemExample from './Examples/ListItemExample';
 import ListSectionExample from './Examples/ListSectionExample';
 import MenuExample from './Examples/MenuExample';
+import NavigationRailExample from './Examples/NavigationRailExample';
 import ProgressBarExample from './Examples/ProgressBarExample';
 import RadioButtonExample from './Examples/RadioButtonExample';
 import RadioButtonGroupExample from './Examples/RadioButtonGroupExample';
@@ -72,6 +73,7 @@ export const mainExamples = {
   ListSection: ListSectionExample,
   ListItem: ListItemExample,
   Menu: MenuExample,
+  NavigationRail: NavigationRailExample,
   Progressbar: ProgressBarExample,
   Radio: RadioButtonExample,
   RadioGroup: RadioButtonGroupExample,

example/src/Examples/NavigationRailExample.tsx

@@ -0,0 +1,201 @@
+import * as React from 'react';
+import { StyleSheet, View } from 'react-native';
+import type { ViewStyle } from 'react-native';
+
+import {
+  Button,
+  Chip,
+  FAB,
+  IconButton,
+  List,
+  NavigationRail,
+  Portal,
+  Switch,
+  Text,
+  useTheme,
+} from 'react-native-paper';
+import type { NavigationRailProps } from 'react-native-paper';
+import Animated, { cubicBezier } from 'react-native-reanimated';
+import type { AnimatedStyle } from 'react-native-reanimated';
+
+type Alignment = NonNullable<NavigationRailProps['alignment']>;
+
+const destinations = [
+  { key: 'inbox', label: 'Inbox', icon: 'inbox-outline', activeIcon: 'inbox' },
+  {
+    key: 'starred',
+    label: 'Starred',
+    icon: 'star-outline',
+    activeIcon: 'star',
+  },
+  { key: 'sent', label: 'Sent', icon: 'send-outline', activeIcon: 'send' },
+  {
+    key: 'drafts',
+    label: 'Drafts',
+    icon: 'file-outline',
+    activeIcon: 'file',
+  },
+  {
+    key: 'trash',
+    label: 'Trash',
+    icon: 'delete-outline',
+    activeIcon: 'delete',
+  },
+];
+
+const alignments: Alignment[] = ['top', 'center', 'bottom'];
+
+const NavigationRailExample = () => {
+  const { colors, motion } = useTheme();
+  const [active, setActive] = React.useState('inbox');
+  const [expanded, setExpanded] = React.useState(false);
+  const [alignment, setAlignment] = React.useState<Alignment>('top');
+  const [labeled, setLabeled] = React.useState(true);
+  const [overlay, setOverlay] = React.useState(false);
+  const [animated, setAnimated] = React.useState(true);
+  const [modalVisible, setModalVisible] = React.useState(false);
+
+  const toggleStyle: AnimatedStyle<ViewStyle> = {
+    transform: [{ rotate: expanded ? '0deg' : '180deg' }],
+    transitionProperty: 'transform',
+    transitionDuration: animated ? motion.duration.medium2 : 0,
+    transitionTimingFunction: cubicBezier(...motion.easing.emphasized),
+  };
+
+  const renderItems = () =>
+    destinations.map(({ key, label, ...rest }) => (
+      <NavigationRail.Item
+        key={key}
+        {...rest}
+        label={labeled ? label : undefined}
+        badge={key === 'inbox' ? 12 : key === 'starred' ? true : undefined}
+        disabled={key === 'trash'}
+        active={active === key}
+        onPress={() => setActive(key)}
+      />
+    ));
+
+  return (
+    <View style={[styles.screen, { backgroundColor: colors.background }]}>
+      <NavigationRail
+        expanded={expanded}
+        alignment={alignment}
+        overlay={overlay}
+        animated={animated}
+        onDismiss={() => setExpanded(false)}
+        header={
+          <>
+            <Animated.View style={toggleStyle}>
+              <IconButton
+                icon="menu-open"
+                aria-label="Toggle rail"
+                onPress={() => setExpanded((value) => !value)}
+              />
+            </Animated.View>
+            <FAB.Extended
+              icon="pencil"
+              label="Compose"
+              expanded={expanded}
+              onPress={() => {}}
+            />
+          </>
+        }
+      >
+        {renderItems()}
+      </NavigationRail>
+
+      <View style={styles.content}>
+        <Text variant="headlineSmall">{active}</Text>
+        <List.Item
+          title="Expanded"
+          right={() => (
+            <View pointerEvents="none">
+              <Switch value={expanded} />
+            </View>
+          )}
+          onPress={() => setExpanded((value) => !value)}
+        />
+        <List.Item
+          title="Animated"
+          right={() => (
+            <View pointerEvents="none">
+              <Switch value={animated} />
+            </View>
+          )}
+          onPress={() => setAnimated((value) => !value)}
+        />
+        <List.Item
+          title="Overlay"
+          right={() => (
+            <View pointerEvents="none">
+              <Switch value={overlay} />
+            </View>
+          )}
+          onPress={() => setOverlay((value) => !value)}
+        />
+        <List.Item
+          title="Labels"
+          right={() => (
+            <View pointerEvents="none">
+              <Switch value={labeled} />
+            </View>
+          )}
+          onPress={() => setLabeled((value) => !value)}
+        />
+        <View style={styles.chips}>
+          {alignments.map((option) => (
+            <Chip
+              key={option}
+              selected={option === alignment}
+              showSelectedOverlay
+              onPress={() => setAlignment(option)}
+            >
+              {option}
+            </Chip>
+          ))}
+        </View>
+        <Button mode="outlined" onPress={() => setModalVisible(true)}>
+          Open modal rail
+        </Button>
+      </View>
+
+      <Portal>
+        <NavigationRail.Modal
+          visible={modalVisible}
+          onDismiss={() => setModalVisible(false)}
+          alignment={alignment}
+          animated={animated}
+          header={
+            <IconButton
+              icon="menu-open"
+              aria-label="Close rail"
+              onPress={() => setModalVisible(false)}
+            />
+          }
+        >
+          {renderItems()}
+        </NavigationRail.Modal>
+      </Portal>
+    </View>
+  );
+};
+
+NavigationRailExample.title = 'Navigation Rail';
+
+const styles = StyleSheet.create({
+  screen: {
+    flex: 1,
+    flexDirection: 'row',
+  },
+  content: {
+    flex: 1,
+    padding: 16,
+    gap: 16,
+  },
+  chips: {
+    flexDirection: 'row',
+    gap: 8,
+  },
+});
+
+export default NavigationRailExample;