mobile-ui-components-react-native-paper
React Native Paper v5+ - Material Design 3 theming, PaperProvider, key components, dynamic color, accessibility, tree-shaking, custom fonts, navigation integration
Install
npx skills add https://github.com/agents-inc/skills/tree/main/dist/plugins/mobile-ui-components-react-native-paper/skills/mobile-ui-components-react-native-paper
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install agents-inc-skills@llmmart
git clone https://github.com/agents-inc/skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole agents-inc/skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
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). UseuseTheme()to access colors/fonts. Wrap Dialogs inPortal. Use the babel plugin for production bundle optimization. For BottomNavigation with React Navigation, useBottomNavigation.Baras a customtabBar(the oldcreateMaterialBottomTabNavigatoris deprecated). On Android 12+, useexpo-material3-themefor 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
configureFontsfor 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
configureFontsand TypeScript custom text variants - Bundle optimization with
react-native-paper/babelplugin - 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 - PaperProvider setup, theming, custom fonts, babel plugin, dynamic color
- examples/components.md - Button, Card, TextInput, FAB, Appbar, Dialog, Snackbar, SegmentedButtons
- examples/navigation-integration.md - BottomNavigation.Bar with React Navigation, adaptNavigationTheme, Drawer integration
- reference.md - Component decision framework, theme color roles, MD3 typography scale
<decision_framework>
Decision Framework
Component Selection
What type of action does the user perform?
├─ Primary action on screen → FAB (icon="plus" or extended with label)
├─ High-emphasis button → Button mode="contained"
├─ Medium-emphasis button → Button mode="outlined" or "contained-tonal"
├─ Low-emphasis button → Button mode="text"
└─ Segmented choice → SegmentedButtons
What type of content container?
├─ Tappable entry point → Card mode="elevated" with onPress
├─ Informational group → Card mode="outlined" (non-interactive)
├─ Elevated surface → Surface elevation={2}
└─ Dismissable message → Snackbar (with optional action)
What type of text input?
├─ Dense form (many fields) → TextInput mode="flat"
├─ Prominent input (few fields) → TextInput mode="outlined"
└─ Search → Searchbar component
What type of navigation bar?
├─ Top of screen → Appbar.Header with Appbar.Content + Appbar.Action
├─ Bottom tabs (with React Navigation) → BottomNavigation.Bar as tabBar
└─ Screen header with back → Appbar.Header with Appbar.BackAction
Theming Decision
Do you need custom brand colors?
├─ YES → Extend MD3LightTheme/MD3DarkTheme with your colors
└─ NO → Use default PaperProvider (MD3 applied automatically)
Do you need Android 12+ system colors?
├─ YES → Use expo-material3-theme's useMaterial3Theme hook
└─ NO → Use your static custom theme
Do you need custom fonts?
├─ YES → Use configureFonts({ config: fontConfig })
│ └─ Need custom text variants? → Use customText<'myVariant'>()
└─ NO → Default MD3 typography (Roboto/System/sans-serif) is applied
Do you need to bridge Paper + React Navigation themes?
├─ YES → Use adaptNavigationTheme() to unify color schemes
└─ NO → Configure each provider's theme independently
</decision_framework>
<red_flags>
RED FLAGS
High Priority Issues:
- Missing
PaperProviderat app root - All Paper components silently fall back to unstyled defaults without the provider. Symptoms: wrong colors, missing ripples, broken Dialogs. - Dialog without
Portalwrapper - Dialog renders inline in the component tree and gets clipped by parent containers or hidden behind navigation headers. - Hardcoding MD3 color values - Use
theme.colors.primary,theme.colors.surface, etc. viauseTheme(). Hardcoded hex values break when the theme changes (dark mode, dynamic color, brand update). - Missing babel plugin in production - Without
react-native-paper/babel, the entire library is bundled regardless of which components you import. - Using deprecated
createMaterialBottomTabNavigator- Deprecated since v5.14. Use@react-navigation/bottom-tabswithBottomNavigation.Baras customtabBarinstead.
Medium Priority Issues:
- Using
require()instead of ES2015importfor Paper components - the babel plugin only optimizesimportstatements - Not providing
onDismisscallback on Dialog - users cannot close the dialog with back button or outside tap - Overriding component
accessibilityRolewithout reason - Paper components have correct roles by default - Using
mode="contained"for all buttons - use appropriate emphasis levels (text, outlined, contained-tonal, contained) - Not switching theme based on system color scheme - leads to always-light or always-dark UI regardless of user preference
Gotchas & Edge Cases:
useTheme()returns the default theme if called outsidePaperProvider- no error thrown, just wrong colors- TextInput label floats over outline in some edge cases (known issue) - apply
outlineStylepadding workaround Snackbarrenders at bottom of its parent by default - wrap inPortalto display as a true overlay above tab barsDialogdoes not support scrollable content by default - useDialog.ScrollAreafor long content instead of wrapping in ScrollViewCard.Coverimages have no default aspect ratio - set explicit height or useresizeMode- Android
StatusBardoes not automatically adapt to Paper theme - manually setStatusBarbackgroundColor/barStyle - Variable fonts may not render correctly on all platforms - install each weight as a separate
.ttffile FAB.Groupvisibility: setvisible={true}explicitly - it defaults totruebut can silently becomefalseif parent re-renders with stale props- MD2 mode (
version: 2) and MD3 cannot coexist in the same provider - choose one perPaperProvider react-native-safe-area-contextis a required peer dependency since v5 - install it even if not using SafeAreaView directly
</red_flags>
<critical_reminders>
CRITICAL REMINDERS
(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)
Failure to follow these rules will cause unstyled components, invisible dialogs, broken dark mode, and bloated bundles.
</critical_reminders>
Files (skills)
-
examples
-
components.md 9.4 KB
Loading… -
core.md 8 KB
Loading… -
navigation-integration.md 6.8 KB
Loading…
-
-
reference.md 7.9 KB
Loading… -
SKILL.md 15.3 KB
--- 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. ```typescript 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/core.md). --- ### Pattern 2: Portal for Overlay Components Dialog, Menu, and overlay components must be wrapped in `Portal` to render above all other content. `Portal` teleports children to the nearest `Portal.Host` (which `PaperProvider` includes by default). ```typescript import { Portal, Dialog, Button, Text } from "react-native-paper"; // Inside a component: <Portal> <Dialog visible={visible} onDismiss={hideDialog}> <Dialog.Title>Confirm</Dialog.Title> <Dialog.Content> <Text variant="bodyMedium">Are you sure?</Text> </Dialog.Content> <Dialog.Actions> <Button onPress={hideDialog}>Cancel</Button> <Button onPress={handleConfirm}>OK</Button> </Dialog.Actions> </Dialog> </Portal> ``` **Why good:** Portal ensures the dialog renders above all screen content including headers and tabs. Without Portal, the dialog renders inline in the component tree and may be clipped or hidden behind other elements. --- ### Pattern 3: Button Modes Paper's Button supports five modes with increasing visual emphasis: `text`, `outlined`, `contained`, `elevated`, and `contained-tonal`. ```typescript import { Button } from "react-native-paper"; <Button mode="text" onPress={onCancel}>Cancel</Button> <Button mode="outlined" onPress={onEdit}>Edit</Button> <Button mode="contained-tonal" onPress={onSave}>Save Draft</Button> <Button mode="contained" onPress={onSubmit}>Submit</Button> <Button mode="elevated" onPress={onAction}>Elevated</Button> // With icon and loading state: <Button mode="contained" icon="camera" loading={isUploading} onPress={onUpload}> Upload Photo </Button> ``` **Why good:** Modes map directly to MD3 emphasis levels (low to high: text < outlined < contained-tonal < contained). Use the right mode for the action's importance. See [examples/components.md](examples/components.md) for all component patterns. --- ### Pattern 4: TextInput with Validation TextInput supports `flat` and `outlined` modes, error state, and adornments (icons/affixes) via `TextInput.Icon` and `TextInput.Affix`. ```typescript import { TextInput } from "react-native-paper"; <TextInput mode="outlined" label="Email" value={email} onChangeText={setEmail} error={!!emailError} keyboardType="email-address" autoCapitalize="none" left={<TextInput.Icon icon="email" />} /> ``` **Why good:** `error` prop automatically applies MD3 error color to outline and label. Adornments via `TextInput.Icon` and `TextInput.Affix` are positioned correctly by the component. --- ### Pattern 5: BottomNavigation.Bar with React Navigation The old `createMaterialBottomTabNavigator` is deprecated since v5.14. Use `@react-navigation/bottom-tabs` with `BottomNavigation.Bar` as a custom `tabBar` renderer instead. ```typescript import { createBottomTabNavigator } from "@react-navigation/bottom-tabs"; import { BottomNavigation } from "react-native-paper"; const Tab = createBottomTabNavigator(); // Pass BottomNavigation.Bar as the tabBar prop: <Tab.Navigator tabBar={({ navigation, state, descriptors, insets }) => ( <BottomNavigation.Bar navigationState={state} safeAreaInsets={insets} onTabPress={({ route, preventDefault }) => { /* emit tabPress, navigate */ }} renderIcon={({ route, focused, color }) => { /* render tabBarIcon */ }} getLabelText={({ route }) => { /* return label */ }} /> )} > ``` **Why good:** Uses React Navigation's latest bottom-tabs API with Paper's MD3-styled bar. Handles tab press events correctly (with `canPreventDefault` for listeners). Deprecated `createMaterialBottomTabNavigator` is no longer maintained. See [examples/navigation-integration.md](examples/navigation-integration.md) for full implementation including `adaptNavigationTheme` and drawer integration. --- ### Pattern 6: Bundle Optimization with Babel Plugin Add `react-native-paper/babel` to `env.production.plugins` in `babel.config.js`. Without it, importing `{ Button }` from `react-native-paper` includes the entire library. The plugin rewrites imports to per-component paths, reducing bundle size significantly. **Important:** Only works with ES2015 `import` syntax, not `require()`. See [examples/core.md](examples/core.md) for the babel config snippet. </patterns> --- <decision_framework> ## Decision Framework ### Component Selection ``` What type of action does the user perform? ├─ Primary action on screen → FAB (icon="plus" or extended with label) ├─ High-emphasis button → Button mode="contained" ├─ Medium-emphasis button → Button mode="outlined" or "contained-tonal" ├─ Low-emphasis button → Button mode="text" └─ Segmented choice → SegmentedButtons What type of content container? ├─ Tappable entry point → Card mode="elevated" with onPress ├─ Informational group → Card mode="outlined" (non-interactive) ├─ Elevated surface → Surface elevation={2} └─ Dismissable message → Snackbar (with optional action) What type of text input? ├─ Dense form (many fields) → TextInput mode="flat" ├─ Prominent input (few fields) → TextInput mode="outlined" └─ Search → Searchbar component What type of navigation bar? ├─ Top of screen → Appbar.Header with Appbar.Content + Appbar.Action ├─ Bottom tabs (with React Navigation) → BottomNavigation.Bar as tabBar └─ Screen header with back → Appbar.Header with Appbar.BackAction ``` ### Theming Decision ``` Do you need custom brand colors? ├─ YES → Extend MD3LightTheme/MD3DarkTheme with your colors └─ NO → Use default PaperProvider (MD3 applied automatically) Do you need Android 12+ system colors? ├─ YES → Use expo-material3-theme's useMaterial3Theme hook └─ NO → Use your static custom theme Do you need custom fonts? ├─ YES → Use configureFonts({ config: fontConfig }) │ └─ Need custom text variants? → Use customText<'myVariant'>() └─ NO → Default MD3 typography (Roboto/System/sans-serif) is applied Do you need to bridge Paper + React Navigation themes? ├─ YES → Use adaptNavigationTheme() to unify color schemes └─ NO → Configure each provider's theme independently ``` </decision_framework> --- <red_flags> ## RED FLAGS **High Priority Issues:** - **Missing `PaperProvider` at app root** - All Paper components silently fall back to unstyled defaults without the provider. Symptoms: wrong colors, missing ripples, broken Dialogs. - **Dialog without `Portal` wrapper** - Dialog renders inline in the component tree and gets clipped by parent containers or hidden behind navigation headers. - **Hardcoding MD3 color values** - Use `theme.colors.primary`, `theme.colors.surface`, etc. via `useTheme()`. Hardcoded hex values break when the theme changes (dark mode, dynamic color, brand update). - **Missing babel plugin in production** - Without `react-native-paper/babel`, the entire library is bundled regardless of which components you import. - **Using deprecated `createMaterialBottomTabNavigator`** - Deprecated since v5.14. Use `@react-navigation/bottom-tabs` with `BottomNavigation.Bar` as custom `tabBar` instead. **Medium Priority Issues:** - Using `require()` instead of ES2015 `import` for Paper components - the babel plugin only optimizes `import` statements - Not providing `onDismiss` callback on Dialog - users cannot close the dialog with back button or outside tap - Overriding component `accessibilityRole` without reason - Paper components have correct roles by default - Using `mode="contained"` for all buttons - use appropriate emphasis levels (text, outlined, contained-tonal, contained) - Not switching theme based on system color scheme - leads to always-light or always-dark UI regardless of user preference **Gotchas & Edge Cases:** - `useTheme()` returns the default theme if called outside `PaperProvider` - no error thrown, just wrong colors - TextInput label floats over outline in some edge cases (known issue) - apply `outlineStyle` padding workaround - `Snackbar` renders at bottom of its parent by default - wrap in `Portal` to display as a true overlay above tab bars - `Dialog` does not support scrollable content by default - use `Dialog.ScrollArea` for long content instead of wrapping in ScrollView - `Card.Cover` images have no default aspect ratio - set explicit height or use `resizeMode` - Android `StatusBar` does not automatically adapt to Paper theme - manually set `StatusBar` `backgroundColor` / `barStyle` - Variable fonts may not render correctly on all platforms - install each weight as a separate `.ttf` file - `FAB.Group` visibility: set `visible={true}` explicitly - it defaults to `true` but can silently become `false` if parent re-renders with stale props - MD2 mode (`version: 2`) and MD3 cannot coexist in the same provider - choose one per `PaperProvider` - `react-native-safe-area-context` is a required peer dependency since v5 - install it even if not using SafeAreaView directly </red_flags> --- <critical_reminders> ## CRITICAL REMINDERS **(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)** **Failure to follow these rules will cause unstyled components, invisible dialogs, broken dark mode, and bloated bundles.** </critical_reminders>
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.