Material Design for React Native

Common errors

• Menu briefly flashes on first open

  cause An intermittent rendering issue affecting the `Menu` component's initial appearance.
  fix Upgrade to `react-native-paper@5.15.1` or newer, as this bug was addressed in that release.

• Error on width change of AnimatedFAB when label is empty string

  cause A specific bug where the `AnimatedFAB` component would throw an error when its `label` prop was an empty string and its width changed.
  fix Update to `react-native-paper@5.14.2` or later, which contains a fix for this issue.

• TextInput label not animating or incorrectly positioned (especially 'outlined' or 'flat' variants)

  cause Issues with `transformOrigin` internally applied to `TextInput` components were causing label rendering glitches.
  fix Ensure you are using `react-native-paper@5.14.3` or newer, where the problematic `transformOrigin` usage was reverted to resolve these issues.

• Surface component styling incorrect when `flex` property is set

  cause A bug in `Surface` component's styling where the `flex` prop was not correctly applied or interfered with other styles.
  fix Upgrade to `react-native-paper@5.14.1` or later, as this specific issue regarding `Surface` styling with `flex` was resolved.

Warnings

• deprecated The `createMaterialBottomTabNavigator` utility has been deprecated in `react-native-paper@5.14.0`. It is no longer actively maintained or recommended for new projects.
  Fix: Migrate to `@react-navigation/bottom-tabs` version `7.x` or later, combined with `BottomNavigation.Bar` for Material Design styling. Refer to the official documentation example for details.
• gotcha Support for `transformOrigin` on `TextInput` components was temporarily unstable and removed in `v5.14.3` due to various label rendering issues. This might affect custom animations or styling that relied on `transformOrigin`.
  Fix: If you experienced issues with TextInput labels, ensure you are on `v5.14.3` or higher where the problematic `transformOrigin` usage was reverted. Avoid using `transformOrigin` directly on `TextInput` components.
• gotcha The internal use of `findNodeHandle` was removed in `v5.14.2`. While this typically affects library internals, it might indicate changes in how certain components interact with the native view hierarchy, potentially impacting highly customized or native-module-integrated components.
  Fix: Ensure your project is compatible with `react-native` versions supported by `react-native-paper v5.14.2+`. Review any custom components or native module integrations that might implicitly rely on `findNodeHandle`.
• gotcha Version `5.14.1` introduced explicit support for `react-native` 0.77.0 and `@react-native-vector-icons` 12.x. Using significantly older or newer versions of these peer dependencies may lead to unexpected visual glitches or runtime errors.
  Fix: Always align your `react-native` and `@react-native-vector-icons` versions with those recommended or explicitly supported by the current `react-native-paper` version to ensure stability and correct rendering.

Install

• npm install react-native-paper npm
• yarn add react-native-paper yarn
• pnpm add react-native-paper pnpm

Imports

• Provider
  wrong:

  const { Provider } = require('react-native-paper')

  correct:

  import { Provider } from 'react-native-paper'

  The top-level component that should wrap your entire app to enable theming and context.
• Button
  wrong:

  import Button from 'react-native-paper/lib/components/Button'

  correct:

  import { Button } from 'react-native-paper'

  Most components are named exports. Direct path imports are generally discouraged and prone to breaking changes.
• MD3LightTheme, useTheme
  wrong:

  import { DefaultTheme } from 'react-native-paper' // Deprecated for MD3

  correct:

  import { MD3LightTheme, Provider, Text, useTheme } from 'react-native-paper'

  Since v5, MD3LightTheme/DarkTheme are the recommended theme objects. `useTheme` is the hook for accessing theme context.

Quickstart

Demonstrates a basic React Native Paper application with theming using PaperProvider, Appbar, Text, and Button components.

import * as React from 'react';
import { View, StyleSheet } from 'react-native';
import { Button, MD3LightTheme, PaperProvider, Text, Appbar } from 'react-native-paper';

const theme = {
  ...MD3LightTheme,
  colors: {
    ...MD3LightTheme.colors,
    primary: '#673ab7',
    accent: '#ff4081',
  },
};

export default function App() {
  const [count, setCount] = React.useState(0);

  return (
    <PaperProvider theme={theme}>
      <Appbar.Header>
        <Appbar.Content title="My Paper App" />
      </Appbar.Header>
      <View style={styles.container}>
        <Text variant="headlineMedium">Count: {count}</Text>
        <Button 
          mode="contained"
          onPress={() => setCount(c => c + 1)}
          style={styles.button}
        >
          Increment
        </Button>
        <Button 
          mode="outlined"
          onPress={() => setCount(0)}
          style={styles.button}
        >
          Reset
        </Button>
      </View>
    </PaperProvider>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    padding: 16,
    backgroundColor: theme.colors.background,
  },
  button: {
    marginVertical: 8,
    width: 200,
  },
});