React Native Paper: Complete Guide With Examples (2026)

Set up React Native Paper 5.15.3: install, MD3 theming, dark mode, and the core components with code examples, plus the sharp edges to know first.

0
React native paper guide

React Native Paper is the most complete Material Design component library for React Native: 30+ production-ready components, full Material Design 3 theming, dark mode out of the box, and accessibility handled for you. It is maintained by Callstack, one of Meta’s core React Native partners, and it has been around long enough to survive three major design-language migrations. That history shows in the API, mostly in good ways.

This guide covers everything you need to actually ship with it: setup, theming, the components you will use daily, and the sharp edges nobody mentions until you hit them. All examples are against react-native-paper 5.15.3, the current stable release as of this writing. A 6.0 alpha exists on npm, but you should not be on it for production work.

What React Native Paper is (and is not)

Paper implements Google’s Material Design 3 spec as React Native components. If your app should look at home on Android, or you want one coherent design system on both platforms without building it yourself, Paper is one of the two or three serious options. If your designers hand you custom Figma files that look nothing like Material, Paper will fight you: you would spend more time overriding styles than you save. In that case a headless or utility-first approach fits better.

What you get: buttons, text inputs, cards, dialogs, menus, appbars, FABs, snackbars, chips, lists, data tables, bottom navigation, and a theming engine that propagates through everything. What you do not get: navigation (pair it with React Navigation), charts, or complex domain widgets like calendars and chat UIs.

Installing react native paper in a new project

Paper needs two peer dependencies: react-native-safe-area-context and an icon source. In an Expo project (see our Expo guide if you are choosing between Expo and bare):

npx expo install react-native-paper react-native-safe-area-context

In a bare React Native app:

npm install react-native-paper react-native-safe-area-context
cd ios && pod install

Icons come from MaterialCommunityIcons via react-native-vector-icons (or @expo/vector-icons in Expo, which ships them preconfigured). Then wrap your app root in the provider:

import { PaperProvider } from 'react-native-paper';

export default function App() {
  return (
    <PaperProvider>
      <Main />
    </PaperProvider>
  );
}

PaperProvider does three jobs: it injects the theme, hosts portals (dialogs, snackbars, menus render through it), and wires up safe area handling. Every Paper component must live below it in the tree. Forgetting the provider is the number one “why is my Dialog not showing” issue on their tracker.

Theming: MD3, custom colors, dark mode

Paper v5 defaults to Material Design 3. Two built-in themes cover the basics:

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

export default function App() {
  const scheme = useColorScheme();
  const theme = scheme === 'dark' ? MD3DarkTheme : MD3LightTheme;
  return (
    <PaperProvider theme={theme}>
      <Main />
    </PaperProvider>
  );
}

That is dark mode, done, for every Paper component in the app. Custom branding means extending the theme object:

const theme = {
  ...MD3LightTheme,
  colors: {
    ...MD3LightTheme.colors,
    primary: '#0D6EFD',
    secondary: '#5C636A',
  },
};

MD3 color schemes have far more roles than the old primary/accent pair: primaryContainer, onPrimary, surfaceVariant, and so on. Do not hand-pick all of them. Generate a full scheme from one brand color with Callstack’s own theme builder or Google’s Material Theme Builder, paste the result in, and move on. Inside components, read the theme with the hook:

import { useTheme } from 'react-native-paper';

function PriceTag() {
  const theme = useTheme();
  return <Text style={{ color: theme.colors.primary }}>$29</Text>;
}

One more trick worth knowing: if you use React Navigation, Paper exports adaptNavigationTheme so headers and backgrounds from both libraries agree on colors instead of clashing.

The components you will actually use

Buttons and inputs

import { Button, TextInput } from 'react-native-paper';

<TextInput
  label="Email"
  value={email}
  onChangeText={setEmail}
  mode="outlined"
  keyboardType="email-address"
/>

<Button mode="contained" loading={busy} onPress={submit}>
  Sign in
</Button>

Button has five modes (text, outlined, contained, elevated, contained-tonal). TextInput has flat and outlined, plus label animation, error state, and left/right affordances built in. The built-in loading spinner on Button removes an entire class of “disable the button while submitting” boilerplate.

Cards

import { Card } from 'react-native-paper';

<Card>
  <Card.Cover source={{ uri: item.image }} />
  <Card.Title title={item.name} subtitle={item.category} />
  <Card.Content>
    <Text variant="bodyMedium">{item.description}</Text>
  </Card.Content>
  <Card.Actions>
    <Button onPress={() => add(item)}>Add to cart</Button>
  </Card.Actions>
</Card>

Appbar and FAB

import { Appbar, FAB } from 'react-native-paper';

<Appbar.Header>
  <Appbar.BackAction onPress={goBack} />
  <Appbar.Content title="Inbox" />
  <Appbar.Action icon="magnify" onPress={openSearch} />
</Appbar.Header>

<FAB icon="plus" style={styles.fab} onPress={compose} />

Dialogs, snackbars and the Portal

Anything that floats renders through a Portal so it sits above your screen content:

import { Portal, Dialog, Snackbar, Button } from 'react-native-paper';

<Portal>
  <Dialog visible={visible} onDismiss={hide}>
    <Dialog.Title>Delete message?</Dialog.Title>
    <Dialog.Actions>
      <Button onPress={hide}>Cancel</Button>
      <Button onPress={confirmDelete}>Delete</Button>
    </Dialog.Actions>
  </Dialog>
</Portal>

<Snackbar visible={saved} onDismiss={clear} duration={3000}>
  Draft saved
</Snackbar>

Lists and data tables

List.Item with List.Icon covers settings screens and menus in a few lines. DataTable gives you sortable headers and pagination for admin-style screens. Both are fine for dozens of rows. For hundreds, render Paper components inside a FlatList or FlashList instead; DataTable does not virtualize.

Sharp edges to know before you commit

  • Bundle size and icons. MaterialCommunityIcons is a large font. If you only use ten icons, configure your build to strip the rest, or accept the megabytes.
  • Text must come from Paper. Mixing React Native’s Text with Paper’s Text gives you inconsistent typography and broken theming. Use Paper’s Text with its variant prop (displayLarge down to labelSmall) everywhere.
  • Style overrides have limits. Most components accept style and contentStyle, but deep internals (a ripple color here, a label margin there) sometimes only respond to theme changes, not inline styles. If you are overriding more than you are using, reconsider the library choice.
  • v5 to v6. The 6.0 alpha modernizes internals but the API is not settled. Pin to 5.15.x and watch the releases page.

Paper vs the alternatives

The honest comparison: Paper is the best choice when Material Design is acceptable or desired, and when you value stability and accessibility over pixel-level design freedom. Its main competitors solve different problems. Utility-first styling (NativeWind) gives design freedom with no components. Headless libraries give behavior with no styling. Kitchen-sink libraries (UI Kitten, RNE) trade polish for breadth. And for specialized surfaces like messaging you will reach for a purpose-built kit anyway; component libraries stop at the widget level, as we found when we compared React Native chat libraries.

If you are still deciding whether React Native itself is the right layer for your app, our React vs React Native breakdown covers that decision.

FAQ

Is React Native Paper free for commercial use?
Yes. MIT licensed, no paid tier, backed by Callstack.

Does React Native Paper work with Expo?
Yes, fully. No native configuration needed; @expo/vector-icons already includes the MaterialCommunityIcons set Paper uses.

Does it support Material Design 3?
Yes. MD3 is the default since v5. MD2 remains available per component via a theme version flag if you are migrating an older app.

Can I use React Native Paper on the web?
Mostly. It works with react-native-web and Expo web builds, with occasional layout quirks in portal-based components. Test dialogs and menus early.

Is Paper still maintained in 2026?
Yes. 5.15.3 shipped in May 2026 and a 6.0 alpha is in progress, which is exactly the release rhythm you want from a mature library.

Leave a Reply 0

Your email address will not be published. Required fields are marked *