# React Native Paper - Component Patterns

> Key component usage patterns. See [SKILL.md](../SKILL.md) for component selection guidance and red flags. See [core.md](core.md) for theming setup.

---

## Pattern 1: Card with Sub-Components

Card supports three modes: `elevated` (default, with shadow), `outlined` (border, no shadow), `contained` (flat, no border or shadow).

```typescript
import { Card, Text, Button, Avatar } from "react-native-paper";

const COVER_HEIGHT = 200;

function ArticleCard({ article, onRead }: ArticleCardProps) {
  return (
    <Card mode="elevated" onPress={() => onRead(article.id)}>
      <Card.Title
        title={article.title}
        subtitle={article.author}
        left={(props) => <Avatar.Icon {...props} icon="account" />}
      />
      <Card.Cover
        source={{ uri: article.imageUrl }}
        style={{ height: COVER_HEIGHT }}
      />
      <Card.Content style={{ paddingTop: 12 }}>
        <Text variant="bodyMedium">{article.summary}</Text>
      </Card.Content>
      <Card.Actions>
        <Button onPress={() => onRead(article.id)}>Read More</Button>
      </Card.Actions>
    </Card>
  );
}
```

**Why good:** Sub-components (Title, Cover, Content, Actions) handle spacing and layout automatically. Avatar in `left` prop renders correctly sized. `mode="elevated"` adds MD3 elevation shadow.

---

## Pattern 2: TextInput with Error State and Adornments

```typescript
import { useState } from "react";
import { TextInput, HelperText } from "react-native-paper";

const MIN_PASSWORD_LENGTH = 8;

function LoginForm() {
  const [email, setEmail] = useState("");
  const [password, setPassword] = useState("");
  const [passwordVisible, setPasswordVisible] = useState(false);

  const emailError = email.length > 0 && !email.includes("@");
  const passwordError = password.length > 0 && password.length < MIN_PASSWORD_LENGTH;

  return (
    <>
      <TextInput
        mode="outlined"
        label="Email"
        value={email}
        onChangeText={setEmail}
        error={emailError}
        keyboardType="email-address"
        autoCapitalize="none"
        left={<TextInput.Icon icon="email" />}
      />
      <HelperText type="error" visible={emailError}>
        Please enter a valid email address
      </HelperText>

      <TextInput
        mode="outlined"
        label="Password"
        value={password}
        onChangeText={setPassword}
        error={passwordError}
        secureTextEntry={!passwordVisible}
        right={
          <TextInput.Icon
            icon={passwordVisible ? "eye-off" : "eye"}
            onPress={() => setPasswordVisible((v) => !v)}
          />
        }
      />
      <HelperText type="error" visible={passwordError}>
        {`Password must be at least ${MIN_PASSWORD_LENGTH} characters`}
      </HelperText>
    </>
  );
}
```

**Why good:** `error` prop applies MD3 error color to outline and label automatically. `HelperText` with `type="error"` renders in error color and animates visibility. `TextInput.Icon` in `right` prop positions the toggle correctly inside the input.

---

## Pattern 3: FAB Variants and FAB.Group

FAB supports sizes (`small`, `medium`, `large`) and variants (`primary`, `secondary`, `tertiary`, `surface`).

```typescript
import { useState } from "react";
import { StyleSheet } from "react-native";
import { FAB, Portal } from "react-native-paper";

const FAB_BOTTOM_OFFSET = 16;
const FAB_RIGHT_OFFSET = 16;

// Simple FAB
function CreateButton({ onPress }: { onPress: () => void }) {
  return (
    <FAB
      icon="plus"
      onPress={onPress}
      style={styles.fab}
    />
  );
}

// Extended FAB with label
function ComposeButton({ onPress }: { onPress: () => void }) {
  return (
    <FAB
      icon="pencil"
      label="Compose"
      onPress={onPress}
      style={styles.fab}
    />
  );
}

// FAB.Group - expandable speed dial
function ActionMenu() {
  const [open, setOpen] = useState(false);

  return (
    <Portal>
      <FAB.Group
        open={open}
        visible
        icon={open ? "close" : "plus"}
        actions={[
          { icon: "camera", label: "Photo", onPress: () => {} },
          { icon: "file-document", label: "Document", onPress: () => {} },
          { icon: "map-marker", label: "Location", onPress: () => {} },
        ]}
        onStateChange={({ open }) => setOpen(open)}
      />
    </Portal>
  );
}

const styles = StyleSheet.create({
  fab: {
    position: "absolute",
    bottom: FAB_BOTTOM_OFFSET,
    right: FAB_RIGHT_OFFSET,
  },
});
```

**Why good:** FAB.Group wrapped in Portal renders the speed dial above all content. `visible` controls show/hide animation. `onStateChange` manages open state. Extended FAB with `label` provides context for the action.

---

## Pattern 4: Appbar.Header Modes

Appbar supports four modes: `small` (default, 64px), `medium` (112px), `large` (152px), `center-aligned` (64px, centered title).

```typescript
import { Appbar } from "react-native-paper";

// Standard top bar
function ScreenHeader({ navigation, title }: HeaderProps) {
  return (
    <Appbar.Header mode="small">
      <Appbar.BackAction onPress={() => navigation.goBack()} />
      <Appbar.Content title={title} />
      <Appbar.Action icon="magnify" onPress={onSearch} />
      <Appbar.Action icon="dots-vertical" onPress={onMenu} />
    </Appbar.Header>
  );
}

// Large header for home/landing screens
function HomeHeader() {
  return (
    <Appbar.Header mode="large" elevated>
      <Appbar.Content title="Inbox" />
      <Appbar.Action icon="magnify" onPress={onSearch} />
    </Appbar.Header>
  );
}
```

**Why good:** `mode="large"` provides the MD3 large top app bar with animated collapsing behavior. `elevated` adds subtle background tint. `Appbar.BackAction` uses the platform-appropriate back icon.

---

## Pattern 5: Dialog with Portal (Complete Pattern)

```typescript
import { useState } from "react";
import { Portal, Dialog, Button, Text, RadioButton } from "react-native-paper";

function SortDialog({ visible, onDismiss, onSelect, currentSort }: SortDialogProps) {
  const [selected, setSelected] = useState(currentSort);

  return (
    <Portal>
      <Dialog visible={visible} onDismiss={onDismiss}>
        <Dialog.Icon icon="sort" />
        <Dialog.Title style={{ textAlign: "center" }}>Sort By</Dialog.Title>
        <Dialog.Content>
          <RadioButton.Group
            value={selected}
            onValueChange={(value) => setSelected(value)}
          >
            <RadioButton.Item label="Date (newest)" value="date-desc" />
            <RadioButton.Item label="Date (oldest)" value="date-asc" />
            <RadioButton.Item label="Name (A-Z)" value="name-asc" />
          </RadioButton.Group>
        </Dialog.Content>
        <Dialog.Actions>
          <Button onPress={onDismiss}>Cancel</Button>
          <Button onPress={() => onSelect(selected)}>Apply</Button>
        </Dialog.Actions>
      </Dialog>
    </Portal>
  );
}
```

**Why good:** `Dialog.Icon` renders above the title (MD3 pattern). `Dialog.ScrollArea` would replace `Dialog.Content` for long scrollable content. Portal ensures the dialog floats above everything.

---

## Pattern 6: Snackbar with Action and Portal

```typescript
import { useState } from "react";
import { Portal, Snackbar } from "react-native-paper";

const SNACKBAR_DURATION = 4000;

function ItemList() {
  const [snackbarVisible, setSnackbarVisible] = useState(false);
  const [deletedItem, setDeletedItem] = useState<Item | null>(null);

  const handleDelete = (item: Item) => {
    setDeletedItem(item);
    deleteItem(item.id);
    setSnackbarVisible(true);
  };

  const handleUndo = () => {
    if (deletedItem) {
      restoreItem(deletedItem);
    }
    setSnackbarVisible(false);
  };

  return (
    <>
      {/* List content here */}
      <Portal>
        <Snackbar
          visible={snackbarVisible}
          onDismiss={() => setSnackbarVisible(false)}
          duration={SNACKBAR_DURATION}
          action={{ label: "Undo", onPress: handleUndo }}
        >
          Item deleted
        </Snackbar>
      </Portal>
    </>
  );
}
```

**Why good:** Portal wrapping ensures Snackbar renders above bottom tabs and other content. `action` with undo follows MD3 pattern. Named `SNACKBAR_DURATION` constant avoids magic number. `onDismiss` is required and must update the `visible` state.

---

## Pattern 7: SegmentedButtons (Single and Multi-Select)

```typescript
import { useState } from "react";
import { SegmentedButtons } from "react-native-paper";

// Single select (value is a string)
function ViewModeSelector() {
  const [viewMode, setViewMode] = useState("list");

  return (
    <SegmentedButtons
      value={viewMode}
      onValueChange={setViewMode}
      buttons={[
        { value: "list", icon: "view-list", label: "List" },
        { value: "grid", icon: "view-grid", label: "Grid" },
        { value: "compact", icon: "view-compact", label: "Compact" },
      ]}
    />
  );
}

// Multi-select (value is an array of strings)
function FilterSelector() {
  const [filters, setFilters] = useState<string[]>([]);

  return (
    <SegmentedButtons
      multiSelect
      value={filters}
      onValueChange={setFilters}
      buttons={[
        { value: "photos", icon: "image", label: "Photos" },
        { value: "videos", icon: "video", label: "Videos" },
        { value: "audio", icon: "music-note", label: "Audio" },
      ]}
    />
  );
}
```

**Why good:** `multiSelect` toggles between string (single) and string[] (multi) value types. `density` prop (`"regular"` | `"small"` | `"medium"` | `"high"`) controls vertical size for space-constrained UIs.

# React Native Paper - Core Patterns

> PaperProvider setup, theming, custom fonts, dynamic color, babel plugin. See [SKILL.md](../SKILL.md) for decision guidance and red flags.

**Prerequisites**: React Native project with `react-native-paper` and `react-native-safe-area-context` installed.

---

## Pattern 1: PaperProvider with Light/Dark Theme

```typescript
import { useColorScheme } from "react-native";
import {
  MD3LightTheme,
  MD3DarkTheme,
  PaperProvider,
} from "react-native-paper";
import { SafeAreaProvider } from "react-native-safe-area-context";

// Extend the default themes with your brand colors
const lightTheme = {
  ...MD3LightTheme,
  colors: {
    ...MD3LightTheme.colors,
    primary: "#6750A4",
    primaryContainer: "#EADDFF",
    secondary: "#625B71",
    secondaryContainer: "#E8DEF8",
    tertiary: "#7D5260",
    tertiaryContainer: "#FFD8E4",
    surface: "#FFFBFE",
    error: "#B3261E",
  },
};

const darkTheme = {
  ...MD3DarkTheme,
  colors: {
    ...MD3DarkTheme.colors,
    primary: "#D0BCFF",
    primaryContainer: "#4F378B",
    secondary: "#CCC2DC",
    secondaryContainer: "#4A4458",
    tertiary: "#EFB8C8",
    tertiaryContainer: "#633B48",
    surface: "#1C1B1F",
    error: "#F2B8B5",
  },
};

export function AppRoot() {
  const colorScheme = useColorScheme();
  const theme = colorScheme === "dark" ? darkTheme : lightTheme;

  return (
    <SafeAreaProvider>
      <PaperProvider theme={theme}>
        <App />
      </PaperProvider>
    </SafeAreaProvider>
  );
}
```

**Why good:** Extends default themes (preserves all ~50 MD3 color roles you didn't override), switches automatically on system preference, SafeAreaProvider wraps PaperProvider for proper inset handling

---

## Pattern 2: Typed Custom Theme with useAppTheme

When adding custom properties to the theme, create a typed hook to preserve TypeScript inference throughout your app.

```typescript
import {
  MD3LightTheme,
  useTheme,
  type MD3Theme,
} from "react-native-paper";

// Add custom properties to the theme
const theme = {
  ...MD3LightTheme,
  colors: {
    ...MD3LightTheme.colors,
    brandPrimary: "#1A73E8",
    brandSecondary: "#174EA6",
    success: "#0F9D58",
    warning: "#F9AB00",
  },
};

// Derive the type from the actual theme object
export type AppTheme = typeof theme;

// Create a typed hook - use this instead of useTheme() throughout the app
export function useAppTheme() {
  return useTheme<AppTheme>();
}

// Usage in components:
function StatusBadge({ status }: { status: "success" | "warning" | "error" }) {
  const { colors } = useAppTheme();
  // colors.brandPrimary, colors.success, colors.warning are all typed
  const backgroundColor = colors[status]; // TypeScript-safe lookup
  return <View style={{ backgroundColor }} />;
}
```

**Why good:** Custom color properties are type-checked at every call site. Adding `brandPrimary` to the theme means `useAppTheme().colors.brandPrimary` auto-completes and type-checks.

---

## Pattern 3: Dynamic Color with Android 12+ System Theme

Use `expo-material3-theme` to pull the user's wallpaper-derived Material You colors on Android 12+. Falls back gracefully on iOS and older Android.

```typescript
import { useColorScheme } from "react-native";
import { MD3LightTheme, MD3DarkTheme, PaperProvider } from "react-native-paper";
import { useMaterial3Theme } from "@pchmn/expo-material3-theme";

export function AppRoot() {
  const colorScheme = useColorScheme();
  const { theme: material3Theme } = useMaterial3Theme();

  // material3Theme.light and material3Theme.dark contain system-derived colors
  // On iOS / older Android, a sensible fallback palette is returned
  const paperTheme =
    colorScheme === "dark"
      ? { ...MD3DarkTheme, colors: material3Theme.dark }
      : { ...MD3LightTheme, colors: material3Theme.light };

  return (
    <PaperProvider theme={paperTheme}>
      <App />
    </PaperProvider>
  );
}
```

**Why good:** Users on Android 12+ see their wallpaper-derived colors automatically. The library provides a complete fallback palette for iOS and older Android, so no conditional logic is needed. Material3Theme colors follow the same structure as Paper's MD3 color roles.

---

## Pattern 4: Custom Fonts with configureFonts

Use `configureFonts` to apply custom font families across all MD3 typography variants (display, headline, title, label, body).

```typescript
import {
  configureFonts,
  MD3LightTheme,
  PaperProvider,
} from "react-native-paper";
import { Platform } from "react-native";

// Global font override - applies to ALL MD3 variants
const fontConfig = {
  fontFamily: Platform.select({
    ios: "Inter",
    android: "Inter",
    web: "Inter, sans-serif",
    default: "Inter",
  }),
};

const theme = {
  ...MD3LightTheme,
  fonts: configureFonts({ config: fontConfig }),
};

// Override specific variants if needed:
const headlineConfig = {
  headlineLarge: {
    fontFamily: "PlayfairDisplay-Bold",
    fontWeight: "700" as const,
    fontSize: 32,
    lineHeight: 40,
    letterSpacing: 0,
  },
};

const themeWithCustomHeadline = {
  ...MD3LightTheme,
  fonts: configureFonts({ config: headlineConfig }),
};
```

**Why good:** `configureFonts` applies your font family to all 15 MD3 variants (displaySmall through bodyLarge) in one call. Override individual variants only when their specific typography needs to differ.

**Important:** Install each font weight as a separate `.ttf` file. Variable fonts cause rendering issues on some platforms (especially Android).

---

## Pattern 5: Custom Text Variants with TypeScript

When you need typography variants beyond MD3's built-in 15 (like "caption" or "overline"), use `customText` for type-safe custom variants.

```typescript
import { customText } from "react-native-paper";

// Create a typed Text component that accepts your custom variants
export const Text = customText<"caption" | "overline">();

// Usage:
<Text variant="caption">Small helper text</Text>
<Text variant="headlineMedium">Standard MD3 variant still works</Text>
```

**Why good:** Custom variants are type-checked. Using an undefined variant (e.g., `variant="foo"`) is a compile error. Built-in MD3 variants remain available.

---

## Pattern 6: Bridging Paper and React Navigation Themes

Use `adaptNavigationTheme` to unify Paper and React Navigation color schemes so both systems use the same palette.

```typescript
import {
  MD3LightTheme,
  MD3DarkTheme,
  adaptNavigationTheme,
  PaperProvider,
} from "react-native-paper";
import {
  NavigationContainer,
  DefaultTheme as NavigationDefaultTheme,
  DarkTheme as NavigationDarkTheme,
} from "@react-navigation/native";
import { useColorScheme } from "react-native";

const { LightTheme: adaptedLight, DarkTheme: adaptedDark } = adaptNavigationTheme({
  reactNavigationLight: NavigationDefaultTheme,
  reactNavigationDark: NavigationDarkTheme,
  materialLight: MD3LightTheme,
  materialDark: MD3DarkTheme,
});

export function AppRoot() {
  const colorScheme = useColorScheme();
  const paperTheme = colorScheme === "dark" ? MD3DarkTheme : MD3LightTheme;
  const navTheme = colorScheme === "dark" ? adaptedDark : adaptedLight;

  return (
    <PaperProvider theme={paperTheme}>
      <NavigationContainer theme={navTheme}>
        <App />
      </NavigationContainer>
    </PaperProvider>
  );
}
```

**Why good:** Without `adaptNavigationTheme`, Paper components and React Navigation headers/tabs use different color palettes. The adapter maps Paper's MD3 color roles to React Navigation's theme structure, ensuring consistent colors across both systems.

**Note:** React Navigation 7.0.0+ automatically picks up Paper's typography when both themes are adapted.

---

## Pattern 7: Babel Plugin for Bundle Optimization

```javascript
// babel.config.js
module.exports = {
  presets: ["module:metro-react-native-babel-preset"],
  env: {
    production: {
      plugins: ["react-native-paper/babel"],
    },
  },
};
```

**Why good:** Without the plugin, `import { Button } from "react-native-paper"` bundles the entire library. The plugin rewrites to per-component paths. Only works with ES2015 `import` syntax, not `require()`.

# React Native Paper - Navigation Integration

> BottomNavigation.Bar with React Navigation, adaptNavigationTheme, Drawer integration. See [SKILL.md](../SKILL.md) for decision guidance. See [core.md](core.md) for theme bridging setup.

---

## Pattern 1: BottomNavigation.Bar with React Navigation v7

The old `createMaterialBottomTabNavigator` is deprecated since v5.14. Use `@react-navigation/bottom-tabs` with `BottomNavigation.Bar` as a custom `tabBar`.

```typescript
import { createBottomTabNavigator } from "@react-navigation/bottom-tabs";
import { CommonActions } from "@react-navigation/native";
import { BottomNavigation } from "react-native-paper";
import Icon from "@react-native-vector-icons/material-design-icons";

const ICON_SIZE = 24;

const Tab = createBottomTabNavigator();

export function MainTabs() {
  return (
    <Tab.Navigator
      screenOptions={{ headerShown: false }}
      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 }) => {
            const { options } = descriptors[route.key];
            if (options.tabBarIcon) {
              return options.tabBarIcon({ focused, color, size: ICON_SIZE });
            }
            return null;
          }}
          getLabelText={({ route }) => {
            const { options } = descriptors[route.key];
            const label =
              typeof options.tabBarLabel === "string"
                ? options.tabBarLabel
                : options.title ?? route.name;
            return label;
          }}
        />
      )}
    >
      <Tab.Screen
        name="Home"
        component={HomeScreen}
        options={{
          tabBarLabel: "Home",
          tabBarIcon: ({ color }) => (
            <Icon name="home" color={color} size={ICON_SIZE} />
          ),
        }}
      />
      <Tab.Screen
        name="Search"
        component={SearchScreen}
        options={{
          tabBarLabel: "Search",
          tabBarIcon: ({ color }) => (
            <Icon name="magnify" color={color} size={ICON_SIZE} />
          ),
        }}
      />
      <Tab.Screen
        name="Profile"
        component={ProfileScreen}
        options={{
          tabBarLabel: "Profile",
          tabBarIcon: ({ color }) => (
            <Icon name="account" color={color} size={ICON_SIZE} />
          ),
          tabBarBadge: 3, // Shows badge with number
        }}
      />
    </Tab.Navigator>
  );
}
```

**Why good:** Uses React Navigation's native bottom-tabs API (latest, maintained) with Paper's MD3-styled bar. `CommonActions.navigate` ensures the correct tab reset behavior. `canPreventDefault` allows listeners to intercept tab presses (e.g., unsaved changes confirmation). Badge support via `tabBarBadge` in screen options.

---

## Pattern 2: Drawer Content with Paper Components

Use Paper's `Drawer.Item`, `Drawer.Section`, and `Drawer.CollapsedItem` inside React Navigation's drawer for MD3-styled drawer content.

```typescript
import { View, StyleSheet } from "react-native";
import {
  DrawerContentScrollView,
  type DrawerContentComponentProps,
} from "@react-navigation/drawer";
import { Drawer, Avatar, Text, Switch, useTheme } from "react-native-paper";
import { useState } from "react";

const AVATAR_SIZE = 48;
const DRAWER_PADDING = 16;

export function CustomDrawerContent(props: DrawerContentComponentProps) {
  const theme = useTheme();
  const [isDarkMode, setIsDarkMode] = useState(false);

  return (
    <DrawerContentScrollView {...props}>
      {/* User info header */}
      <View style={styles.header}>
        <Avatar.Image size={AVATAR_SIZE} source={{ uri: user.avatarUrl }} />
        <Text variant="titleMedium" style={styles.userName}>
          {user.name}
        </Text>
        <Text variant="bodySmall" style={{ color: theme.colors.onSurfaceVariant }}>
          {user.email}
        </Text>
      </View>

      {/* Main navigation */}
      <Drawer.Section title="Navigation">
        <Drawer.Item
          label="Home"
          icon="home"
          active={props.state.index === 0}
          onPress={() => props.navigation.navigate("Home")}
        />
        <Drawer.Item
          label="Settings"
          icon="cog"
          active={props.state.index === 1}
          onPress={() => props.navigation.navigate("Settings")}
        />
      </Drawer.Section>

      {/* Preferences section */}
      <Drawer.Section title="Preferences">
        <View style={styles.preference}>
          <Text variant="bodyLarge">Dark Mode</Text>
          <Switch value={isDarkMode} onValueChange={setIsDarkMode} />
        </View>
      </Drawer.Section>
    </DrawerContentScrollView>
  );
}

const styles = StyleSheet.create({
  header: {
    paddingHorizontal: DRAWER_PADDING,
    paddingVertical: DRAWER_PADDING,
  },
  userName: {
    marginTop: 8,
  },
  preference: {
    flexDirection: "row",
    justifyContent: "space-between",
    alignItems: "center",
    paddingHorizontal: DRAWER_PADDING,
    paddingVertical: 12,
  },
});
```

**Why good:** `DrawerContentScrollView` handles safe area insets. `Drawer.Section` with `title` groups items with an MD3 divider. `Drawer.Item` with `active` prop shows the MD3 active indicator. Paper's `Switch` and `Avatar` integrate seamlessly.

---

## Pattern 3: Appbar.Header as Navigation Header

Replace React Navigation's default header with Paper's Appbar.Header for MD3 styling.

```typescript
import { Appbar } from "react-native-paper";
import type { NativeStackHeaderProps } from "@react-navigation/native-stack";

export function CustomNavigationBar({
  navigation,
  route,
  options,
  back,
}: NativeStackHeaderProps) {
  const title = options.headerTitle ?? options.title ?? route.name;

  return (
    <Appbar.Header elevated>
      {back ? <Appbar.BackAction onPress={navigation.goBack} /> : null}
      <Appbar.Content title={typeof title === "string" ? title : route.name} />
      {options.headerRight
        ? options.headerRight({ canGoBack: !!back })
        : null}
    </Appbar.Header>
  );
}

// Usage in navigator:
// <Stack.Navigator screenOptions={{ header: (props) => <CustomNavigationBar {...props} /> }}>
```

**Why good:** Replaces React Navigation's default header with MD3-styled Appbar. `elevated` adds the MD3 surface tint. Respects `headerTitle`, `title`, and `headerRight` from screen options. `Appbar.BackAction` uses the correct platform back icon.