0
# React Native Paper
1

2
React Native Paper is a comprehensive Material Design component library for React Native applications. It provides a complete collection of Material Design components that work seamlessly across iOS and Android platforms, with full theming support, TypeScript integration, and extensive customization options.
3

4
## Package Information
5

6
- **Package Name**: react-native-paper
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install react-native-paper` or `yarn add react-native-paper`
10

11
## Core Imports
12

13
```typescript
14
import { PaperProvider, Button, Card } from 'react-native-paper';
15
```
16

17
CommonJS:
18

19
```javascript
20
const { PaperProvider, Button, Card } = require('react-native-paper');
21
```
22

23
## Basic Usage
24

25
```typescript
26
import React from 'react';
27
import { PaperProvider, Button, Card, Text } from 'react-native-paper';
28
import { View } from 'react-native';
29

30
export default function App() {
31
  return (
32
    <PaperProvider>
33
      <View style={{ flex: 1, padding: 16 }}>
34
        <Card>
35
          <Card.Title title="Welcome" subtitle="React Native Paper" />
36
          <Card.Content>
37
            <Text>This is a Material Design card component.</Text>
38
          </Card.Content>
39
          <Card.Actions>
40
            <Button mode="contained">
41
              Get Started
42
            </Button>
43
          </Card.Actions>
44
        </Card>
45
      </View>
46
    </PaperProvider>
47
  );
48
}
49
```
50

51
## Architecture
52

53
React Native Paper is built around several key architectural concepts:
54

55
- **Provider System**: `PaperProvider` wraps your app and provides theme context to all components
56
- **Material Design 3**: Latest Material Design guidelines with full MD3 token support and backwards compatibility with MD2
57
- **Theming Engine**: Comprehensive theming system with light/dark mode support, custom color schemes, and typography scaling
58
- **Component Composition**: Complex components built from smaller composable parts (e.g., `Card.Title`, `Card.Content`)
59
- **Platform Adaptation**: Components automatically adapt to iOS and Android design patterns while maintaining Material Design principles
60
- **TypeScript Integration**: Full type safety with comprehensive prop interfaces and theme typing
61

62
## Capabilities
63

64
### Core Provider & Theming
65

66
Essential provider components and theming utilities for setting up React Native Paper in your application.
67

68
```typescript { .api }
69
function PaperProvider(props: ProviderProps): JSX.Element;
70

71
interface ProviderProps {
72
  theme?: MD3Theme | MD2Theme;
73
  children: React.ReactNode;
74
  settings?: {
75
    icon?: IconSource;
76
  };
77
}
78

79
function useTheme<T = MD3Theme>(overrides?: $DeepPartial<T>): T;
80
function withTheme<Props, C>(WrappedComponent: ComponentType<Props & { theme: MD3Theme | MD2Theme }> & C): ComponentType<Props> & C;
81
```
82

83
[Provider & Theming](./provider-theming.md)
84

85
### Buttons & Actions
86

87
Interactive components for user actions including buttons, floating action buttons, and icon buttons.
88

89
```typescript { .api }
90
function Button(props: ButtonProps): JSX.Element;
91
function IconButton(props: IconButtonProps): JSX.Element;
92
function FAB(props: FABProps): JSX.Element;
93
function TouchableRipple(props: TouchableRippleProps): JSX.Element;
94

95
interface ButtonProps {
96
  mode?: 'text' | 'outlined' | 'contained' | 'elevated' | 'contained-tonal';
97
  children: React.ReactNode;
98
  onPress?: () => void;
99
  disabled?: boolean;
100
  loading?: boolean;
101
  icon?: IconSource;
102
}
103
```
104

105
[Buttons & Actions](./buttons-actions.md)
106

107
### Form Controls
108

109
Input components including text fields, checkboxes, radio buttons, switches, and form validation helpers.
110

111
```typescript { .api }
112
function TextInput(props: TextInputProps): JSX.Element;
113
function Checkbox(props: CheckboxProps): JSX.Element;
114
function RadioButton(props: RadioButtonProps): JSX.Element;
115
function Switch(props: SwitchProps): JSX.Element;
116

117
interface TextInputProps {
118
  label?: string;
119
  placeholder?: string;
120
  value: string;
121
  onChangeText: (text: string) => void;
122
  mode?: 'flat' | 'outlined';
123
  error?: boolean;
124
  disabled?: boolean;
125
}
126
```
127

128
[Form Controls](./form-controls.md)
129

130
### Cards & Surfaces
131

132
Layout components for organizing content including cards, surfaces, and dividers.
133

134
```typescript { .api }
135
function Card(props: CardProps): JSX.Element;
136
function Surface(props: SurfaceProps): JSX.Element;
137
function Divider(props: DividerProps): JSX.Element;
138

139
namespace Card {
140
  function Title(props: CardTitleProps): JSX.Element;
141
  function Content(props: CardContentProps): JSX.Element;
142
  function Actions(props: CardActionsProps): JSX.Element;
143
  function Cover(props: CardCoverProps): JSX.Element;
144
}
145
```
146

147
[Cards & Surfaces](./cards-surfaces.md)
148

149
### Lists & Data Display
150

151
Components for displaying structured data including lists, data tables, and related components.
152

153
```typescript { .api }
154
namespace List {
155
  function Item(props: ListItemProps): JSX.Element;
156
  function Accordion(props: ListAccordionProps): JSX.Element;
157
  function Section(props: ListSectionProps): JSX.Element;
158
  function Icon(props: ListIconProps): JSX.Element;
159
  function Image(props: ListImageProps): JSX.Element;
160
}
161

162
function DataTable(props: DataTableProps): JSX.Element;
163

164
namespace DataTable {
165
  function Header(props: DataTableHeaderProps): JSX.Element;
166
  function Row(props: DataTableRowProps): JSX.Element;
167
  function Cell(props: DataTableCellProps): JSX.Element;
168
}
169
```
170

171
[Lists & Data Display](./lists-data-display.md)
172

173
### Navigation Components
174

175
Navigation and app structure components including app bars, bottom navigation, and drawer components.
176

177
```typescript { .api }
178
namespace Appbar {
179
  function Header(props: AppbarHeaderProps): JSX.Element;
180
  function Content(props: AppbarContentProps): JSX.Element;
181
  function Action(props: AppbarActionProps): JSX.Element;
182
  function BackAction(props: AppbarBackActionProps): JSX.Element;
183
}
184

185
function BottomNavigation(props: BottomNavigationProps): JSX.Element;
186

187
namespace Drawer {
188
  function Item(props: DrawerItemProps): JSX.Element;
189
  function Section(props: DrawerSectionProps): JSX.Element;
190
  function CollapsedItem(props: DrawerCollapsedItemProps): JSX.Element;
191
}
192
```
193

194
[Navigation](./navigation.md)
195

196
### Overlays & Feedback
197

198
Modal and overlay components including dialogs, menus, modals, portals, and feedback components.
199

200
```typescript { .api }
201
namespace Dialog {
202
  function Title(props: DialogTitleProps): JSX.Element;
203
  function Content(props: DialogContentProps): JSX.Element;
204
  function Actions(props: DialogActionsProps): JSX.Element;
205
  function ScrollArea(props: DialogScrollAreaProps): JSX.Element;
206
  function Icon(props: DialogIconProps): JSX.Element;
207
}
208

209
function Menu(props: MenuProps): JSX.Element;
210
function Modal(props: ModalProps): JSX.Element;
211
function Portal(props: PortalProps): JSX.Element;
212
function Snackbar(props: SnackbarProps): JSX.Element;
213
```
214

215
[Overlays & Feedback](./overlays-feedback.md)
216

217
### Typography & Display
218

219
Text and display components including typography variants, avatars, badges, chips, and icons.
220

221
```typescript { .api }
222
function Text(props: TextProps): JSX.Element;
223
function customText(variant: keyof MD3Typescale): ComponentType<TextProps>;
224

225
namespace Avatar {
226
  function Icon(props: AvatarIconProps): JSX.Element;
227
  function Image(props: AvatarImageProps): JSX.Element;
228
  function Text(props: AvatarTextProps): JSX.Element;
229
}
230

231
function Badge(props: BadgeProps): JSX.Element;
232
function Chip(props: ChipProps): JSX.Element;
233
function Icon(props: { source: IconSource; size?: number; color?: string }): JSX.Element;
234
```
235

236
[Typography & Display](./typography-display.md)
237

238
### Progress & Status
239

240
Components for showing loading states, progress, and status information.
241

242
```typescript { .api }
243
function ActivityIndicator(props: ActivityIndicatorProps): JSX.Element;
244
function ProgressBar(props: ProgressBarProps): JSX.Element;
245
function Banner(props: BannerProps): JSX.Element;
246

247
interface ActivityIndicatorProps {
248
  animating?: boolean;
249
  color?: string;
250
  size?: number | 'small' | 'large';
251
  hidesWhenStopped?: boolean;
252
}
253
```
254

255
[Progress & Status](./progress-status.md)
256

257
### React Navigation Integration
258

259
Components and utilities for integrating with React Navigation, including Material bottom tab navigation.
260

261
```typescript { .api }
262
function createMaterialBottomTabNavigator(): TypedNavigator<ParamListBase, NavigationState, MaterialBottomTabNavigationOptions, MaterialBottomTabNavigationEventMap, MaterialBottomTabNavigationProp<ParamListBase>>;
263

264
function MaterialBottomTabView(props: MaterialBottomTabViewProps): JSX.Element;
265

266
function adaptNavigationTheme<T extends NavigationTheme>(themes: {
267
  reactNavigationLight?: T;
268
  reactNavigationDark?: T;
269
  materialLight?: MD3Theme;
270
  materialDark?: MD3Theme;
271
}): { LightTheme?: T; DarkTheme?: T };
272
```
273

274
[React Navigation Integration](./react-navigation.md)
275

276
## Core Types
277

278
```typescript { .api }
279
type IconSource = string | ImageSourcePropType | {
280
  default: ImageSourcePropType;
281
} | {
282
  ios: ImageSourcePropType;
283
  android: ImageSourcePropType;
284
};
285

286
interface MD3Theme extends ThemeBase {
287
  version: 3;
288
  isV3: true;
289
  colors: MD3Colors;
290
  fonts: MD3Typescale;
291
}
292

293
interface MD2Theme extends ThemeBase {
294
  version: 2;
295
  isV3: false;
296
  colors: MD2Colors;
297
  fonts: Fonts;
298
}
299

300
interface ThemeBase {
301
  dark: boolean;
302
  mode?: 'adaptive' | 'exact';
303
  roundness: number;
304
  animation: {
305
    scale: number;
306
    defaultAnimationDuration?: number;
307
  };
308
}
309

310
type MD3Elevation = 0 | 1 | 2 | 3 | 4 | 5;
311

312
enum MD3TypescaleKey {
313
  displayLarge = 'displayLarge',
314
  displayMedium = 'displayMedium',
315
  displaySmall = 'displaySmall',
316
  headlineLarge = 'headlineLarge',
317
  headlineMedium = 'headlineMedium',
318
  headlineSmall = 'headlineSmall',
319
  titleLarge = 'titleLarge',
320
  titleMedium = 'titleMedium',
321
  titleSmall = 'titleSmall',
322
  labelLarge = 'labelLarge',
323
  labelMedium = 'labelMedium',
324
  labelSmall = 'labelSmall',
325
  bodyLarge = 'bodyLarge',
326
  bodyMedium = 'bodyMedium',
327
  bodySmall = 'bodySmall',
328
}
329
```