DOCSEARCHbyAlgolia
Submit Docs

React Native Paper

repository·main·Indexed 12 days ago

https://github.com/callstack/react-native-paper

A cross-platform UI kit library for React Native providing customizable, production-ready components that follow Google's Material Design guidelines. It includes full theming support and platform adaptation for iOS and Android. Version 6.0.0-alpha.0.

Tokens
94.5K
Snippets
208
Records
385
Agent score
93%

What's inside React Native Paper

  1. Overview of React Native Paper

    main

    React Native Paper is a collection of customizable and production-ready components for React Native that follow Google's Material Design guidelines. It is designed for cross-platform parity across iOS, Android, and React Native Web.

    Key features include:

    • Production-ready components: A wide range of UI elements like Buttons, inputs, lists, cards, menus, dialogs, navigation, and feedback patterns.
    • Material You theming: Support for Material 3 color, typography, elevation, and state layers.
    • Accessibility: Common interactions, contrast, and state handling are built into the component surface.
    • Dark mode support: Primitives for both light and dark experiences, including adaptive surfaces and semantic color roles.

  2. What is React Native Paper

    main
    React Native Paper is a collection of customizable and production-ready components for React Native that follow Google's Material Design guidelines. It provides cross-platform parity across iOS, Android, and React Native Web, ensuring design language and component behavior remain aligned from a single codebase.

  4. Explore React Native Paper features and documentation

    main

    React Native Paper offers several key capabilities for building mobile interfaces:

    For a complete list of components and usage examples, visit the official documentation.

  6. Key features of React Native Paper

    main

    React Native Paper offers several core capabilities for building production apps:

    • Production-ready components: A suite of components including Buttons, inputs, lists, cards, menus, dialogs, navigation, and feedback patterns.
    • Material You theming: Support for Material 3 color, typography, elevation, and state layers via a dedicated theme system.
    • Accessibility: Common interactions, contrast, and state handling are built directly into the component surface.
    • Cross-platform parity: Consistent behavior across iOS, Android, and React Native Web.
    • Dark mode support: Primitives for both light and dark experiences, including adaptive surfaces and semantic color roles.

  7. Add accessories to TextInput using startAccessory and endAccessory

    main

    You can add interactive or decorative elements to the beginning or end of a TextInput using the startAccessory and endAccessory props. These props expect a function that receives accessory properties (like style and disabled) and returns a component.

    For simple icons, you can use TextInput.Icon within these accessory functions.

    const searchAccessory = (accessoryProps) => (
  <TextInput.Icon {...accessoryProps} icon="magnify" />
);

// Usage
<TextInput
  label="Search"
  startAccessory={searchAccessory}
/>

  8. Configure RTL support for icons

    main

    To ensure icons behave correctly in Right-to-Left (RTL) environments, you can pass an object to the icon prop instead of a direct value. The object should have the shape { source: ..., direction: ... }.

    source

    Can be any value accepted by the icon prop (icon name or image source).

    direction options

    • auto: Uses the device language (via I18nManager) to determine if the icon should be RTL.
    • rtl: Forces the icon to be flipped for RTL.
    • ltr: Forces the icon to be displayed as LTR, even in an RTL environment.

    Render Function Support

    When using a render function, you gain access to a direction property ('rtl' or 'ltr') in the arguments object, allowing you to manually handle transformations (like scaleX: -1).

    // Using an icon name with RTL direction
<Button icon={{ source: 'add-a-photo', direction: 'rtl' }}>Press me</Button>

// Using a render function with RTL direction
<Button
  icon={({ size, color, direction }) => (
    <Image
      source={require('../assets/chameleon.jpg')}
      style={[
        { transform: [{ scaleX: direction === 'rtl' ? -1 : 1 }] },
        { width: size, height: size, tintColor: color },
      ]}
    />
  )}
>
  Press me
</Button>

  9. Understand Dark Theme modes: exact vs adaptive

    main

    React Native Paper supports two modes for dark themes to control how Material Design guidelines are applied:

    • exact: Maintains the previous behavior. Appbar and BottomNavigation use the primary color by default.
    • adaptive: Follows Material Design guidelines. Surfaces use a white overlay with opacity to indicate elevation, and Appbar and BottomNavigation use the surface color as a background.

    If you are using a custom theme, you must manually handle switching between light and dark modes using React Native's Appearance API.

  10. Enable RTL support for icons

    main

    To ensure icons behave correctly in Right-to-Left (RTL) environments, you can pass an object to the icon prop instead of a simple value. The object shape is:

    { source: any, direction: 'auto' | 'rtl' | 'ltr' }

    • source: Accepts any value supported by the icon prop (icon name, image source, or render function).
    • direction:
      • auto: Uses the device language (via I18nManager) to determine direction.
      • rtl: Forces the icon to be flipped/displayed for RTL.
      • ltr: Forces the icon to be displayed for LTR, even in an RTL environment.

    When using a render function, you also receive direction in the arguments ('rtl' or 'ltr'), allowing you to manually apply transformations like scaleX: -1 for RTL.

    Note: If using a render function, you are responsible for handling the visual flip (e.g., using transform: [{ scaleX: -1 }]) if the icon requires it.

    // RTL with Image Source
<Button
  icon={{
    source: { uri: 'https://path.to/image.png' },
    direction: 'rtl',
  }}
>
  Press me
</Button>

// RTL with Icon Name
<Button icon={{ source: 'add-a-photo', direction: 'rtl' }}>Press me</Button>

// RTL with Render Function
<Button
  icon={({ size, color, direction }) => (
    <Image
      source={require('../assets/chameleon.jpg')}
      style={[
        { transform: [{ scaleX: direction === 'rtl' ? -1 : 1 }] },
        { width: size, height: size, tintColor: color },
      ]}
    />
  )}
>
  Press me
</Button>

  11. How Portal.Host works

    main

    A Portal.Host acts as a container that renders all of its child Portal elements. This is useful for rendering UI elements (like Modals or Dialogs) at the top level of your component tree, ensuring they appear above the rest of your application content.

    Note: If you are already using the Provider component from react-native-paper, you do not need to manually add Portal.Host because Provider includes it by default.

    import * as React from 'react';
import { Text } from 'react-native';
import { Portal } from 'react-native-paper';

const MyComponent = () => (
  <Portal.Host>
    <Text>Content of the app</Text>
  </Portal.Host>
);

export default MyComponent;

  12. How RTL support works in React Native Paper

    main

    React Native Paper supports right-to-left (RTL) layouts for languages like Arabic and Hebrew.

    On native platforms, the library automatically reads the writing direction from I18nManager.getConstants().isRTL. You must configure your app's RTL support using the standard React Native I18nManager or Expo localization guides.

    On Web, I18nManager.getConstants().isRTL is a no-op. To enable RTL globally on the web, you must set the dir attribute on the <html> element:

    <html dir="rtl">
  <!-- App content -->
</html>

    Important: The direction prop in React Native Paper informs the library about the text direction; it does not change the text direction itself. You must ensure the direction prop matches the actual configuration of your app to avoid incorrect layouts.