/mobile-ui-components-react-native-paper

name: mobile-ui-components-react-native-paper
description: React Native Paper v5+ - Material Design 3 theming, PaperProvider, key components, dynamic color, accessibility, tree-shaking, custom fonts, navigation integration

React Native Paper Patterns

> **Quick Guide:** React Native Paper v5+ provides Material Design 3 (Material You) components for React Native. Wrap your app in `PaperProvider` (MD3 is the default). Use `useTheme()` to access colors/fonts. Wrap Dialogs in `Portal`. Use the babel plugin for production bundle optimization. For BottomNavigation with React Navigation, use `BottomNavigation.Bar` as a custom `tabBar` (the old `createMaterialBottomTabNavigator` is deprecated). On Android 12+, use `expo-material3-theme` for system dynamic colors.

---

<critical_requirements>

CRITICAL: Before Using This Skill

**(You MUST wrap your app root in `PaperProvider` - all Paper components require the provider context to function)**

**(You MUST wrap Dialog, Menu, and similar overlay components in `Portal` - without it they render inline instead of above other content)**

**(You MUST use `useTheme()` to access theme colors and fonts in components - never hardcode Material Design color values)**

**(You MUST add `react-native-paper/babel` to production plugins for bundle optimization - without it the entire library is included)**

</critical_requirements>

---

**Auto-detection:** React Native Paper, react-native-paper, PaperProvider, MD3LightTheme, MD3DarkTheme, useTheme, Portal, FAB, Appbar, BottomNavigation, SegmentedButtons, configureFonts, adaptNavigationTheme, Card, Dialog, Snackbar, TextInput, Button mode, Surface, Chip, Searchbar, ActivityIndicator, Banner, Divider, ProgressBar, Switch, RadioButton, Checkbox, DataTable, Tooltip, Badge, Menu, Drawer.Item

**When to use:**

• Setting up PaperProvider with custom MD3 themes (light, dark, dynamic color)
• Using Paper components (Button, Card, TextInput, FAB, Appbar, Dialog, Snackbar, SegmentedButtons)
• Integrating Paper's BottomNavigation.Bar with React Navigation bottom tabs
• Configuring custom fonts with `configureFonts` for MD3 typography
• Implementing Android 12+ dynamic color theming
• Bridging Paper and React Navigation themes with `adaptNavigationTheme`

**Key patterns covered:**

• PaperProvider setup and MD3 theming (light, dark, custom, dynamic color)
• Component usage: Button modes, Card variants, TextInput modes, FAB sizes/variants, Dialog with Portal
• BottomNavigation.Bar integration with React Navigation v7 bottom tabs
• Custom fonts with `configureFonts` and TypeScript custom text variants
• Bundle optimization with `react-native-paper/babel` plugin
• Accessibility patterns (built-in a11y props, screen reader support)

**When NOT to use:**

• General React Native component architecture (not Paper-specific)
• Navigation patterns beyond BottomNavigation integration (not Paper-specific)
• Custom animations or gestures (not a UI component library concern)

**Detailed Resources:**

• [examples/core.md](examples/core.md) - PaperProvider setup, theming, custom fonts, babel plugin, dynamic color
• [examples/components.md](examples/components.md) - Button, Card, TextInput, FAB, Appbar, Dialog, Snackbar, SegmentedButtons
• [examples/navigation-integration.md](examples/navigation-integration.md) - BottomNavigation.Bar with React Navigation, adaptNavigationTheme, Drawer integration
• [reference.md](reference.md) - Component decision framework, theme color roles, MD3 typography scale

---

<philosophy>

Philosophy

React Native Paper is a **Material Design 3 component library** for React Native. It provides pre-built, accessible, and themeable components that follow the Material You design system. The library is maintained by Callstack and is one of the most mature UI libraries in the React Native ecosystem.

**Core principles:**

1. **Theme-driven styling** - All components read colors, fonts, and roundness from the theme. Override the theme, not individual component styles, for consistent branding. 2. **MD3 by default** - v5+ applies Material Design 3 automatically. MD2 is still supported via `{ version: 2 }` but is legacy. 3. **Portal for overlays** - Dialog, Menu, and similar overlay components must be wrapped in `Portal` to render above other content. 4. **Accessibility built-in** - Components include proper `accessibilityRole`, `accessibilityState`, and screen reader support out of the box. Don't override these without reason. 5. **Bundle optimization required** - Add the babel plugin in production to exclude unused components from the bundle.

**Mental model:** Paper provides the Material Design visual layer. Your app's component architecture, state management, and navigation structure are separate concerns handled by their respective skills.

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: PaperProvider and Theming

Wrap your app root in `PaperProvider`. MD3 is applied by default. Extend `MD3LightTheme` or `MD3DarkTheme` for custom branding. Use `useTheme()` to access theme values in components.

import {
  MD3LightTheme,
  MD3DarkTheme,
  PaperProvider,
  useTheme,
} from "react-native-paper";
import { useColorScheme } from "react-native";

const lightTheme = {
  ...MD3LightTheme,
  colors: {
    ...MD3LightTheme.colors,
    primary: "#6750A4",
    secondary: "#625B71",
  },
};

const darkTheme = {
  ...MD3DarkTheme,
  colors: {
    ...MD3DarkTheme.colors,
    primary: "#D0BCFF",
    secondary: "#CCC2DC",
  },
};

// In your root component:
const colorScheme = useColorScheme();
const theme = colorScheme === "dark" ? darkTheme : lightTheme;
// <PaperProvider theme={theme}>...</PaperProvider>

**Why good:** Extends default themes (preserves all MD3 color roles), dynamically switches on system preference, all Paper components pick up the overrides

For typed custom themes, dynamic color with `expo-material3-theme`, and `configureFonts`, see [examples/core.md](examples/c