0
# Provider & Theming
1

2
Core provider components and comprehensive theming system for React Native Paper applications, including Material Design 2/3 theme support and customization utilities.
3

4
## Capabilities
5

6
### PaperProvider
7

8
Main provider component that wraps your application and provides theme context to all React Native Paper components.
9

10
```typescript { .api }
11
/**
12
 * Main provider component for React Native Paper
13
 * @param props - Provider configuration options
14
 * @returns JSX Element wrapping your app
15
 */
16
function PaperProvider(props: ProviderProps): JSX.Element;
17

18
interface ProviderProps {
19
  /** Theme object (MD2 or MD3) */
20
  theme?: MD3Theme | MD2Theme;
21
  /** App content */
22
  children: React.ReactNode;
23
  /** Global settings */
24
  settings?: {
25
    /** Default icon source for components */
26
    icon?: IconSource;
27
  };
28
}
29
```
30

31
**Usage Example:**
32

33
```typescript
34
import React from 'react';
35
import { PaperProvider, MD3LightTheme } from 'react-native-paper';
36
import { MyApp } from './MyApp';
37

38
export default function App() {
39
  return (
40
    <PaperProvider theme={MD3LightTheme}>
41
      <MyApp />
42
    </PaperProvider>
43
  );
44
}
45
```
46

47
### Theme Hooks
48

49
Hook for accessing and consuming theme values within components.
50

51
```typescript { .api }
52
/**
53
 * Hook to access the current theme with optional overrides
54
 * @param overrides - Partial theme overrides
55
 * @returns Complete theme object
56
 */
57
function useTheme<T = MD3Theme>(overrides?: $DeepPartial<T>): T;
58

59
/**
60
 * Internal theme hook used by Paper components
61
 * @param themeOverrides - Partial theme overrides
62
 * @returns Internal theme with component-specific extensions
63
 */
64
function useInternalTheme(themeOverrides?: $DeepPartial<InternalTheme>): InternalTheme;
65
```
66

67
**Usage Example:**
68

69
```typescript
70
import React from 'react';
71
import { View, Text } from 'react-native';
72
import { useTheme } from 'react-native-paper';
73

74
function ThemedComponent() {
75
  const theme = useTheme();
76
  
77
  return (
78
    <View style={{ backgroundColor: theme.colors.surface }}>
79
      <Text style={{ color: theme.colors.onSurface }}>
80
        Themed content
81
      </Text>
82
    </View>
83
  );
84
}
85
```
86

87
### Higher-Order Components
88

89
HOCs for providing theme access to class components and custom components.
90

91
```typescript { .api }
92
/**
93
 * Higher-order component that injects theme as a prop
94
 * @param WrappedComponent - Component to wrap with theme
95
 * @returns Component with theme prop injected
96
 */
97
function withTheme<Props, C>(
98
  WrappedComponent: ComponentType<Props & { theme: MD3Theme | MD2Theme }> & C
99
): ComponentType<Props> & C;
100

101
/**
102
 * Internal HOC for Paper components
103
 * @param WrappedComponent - Component to wrap with internal theme
104
 * @returns Component with internal theme injected
105
 */
106
function withInternalTheme<Props extends { theme: InternalTheme }, C>(
107
  WrappedComponent: ComponentType<Props & { theme: InternalTheme }> & C
108
): ComponentType<Omit<Props, 'theme'>> & C;
109
```
110

111
### Theme Context Provider
112

113
Core theme provider component from the theming system.
114

115
```typescript { .api }
116
/**
117
 * Theme context provider component
118
 * @param props - Provider props with theme and children
119
 * @returns Provider element
120
 */
121
function ThemeProvider(props: { theme: MD3Theme | MD2Theme; children: React.ReactNode }): JSX.Element;
122
```
123

124
### Default Themes
125

126
Pre-built theme objects following Material Design guidelines.
127

128
```typescript { .api }
129
/** Default Material Design 3 light theme */
130
const DefaultTheme: MD3Theme;
131

132
/** Material Design 3 light theme */
133
const MD3LightTheme: MD3Theme;
134

135
/** Material Design 3 dark theme */
136
const MD3DarkTheme: MD3Theme;
137

138
/** Material Design 2 light theme */
139
const MD2LightTheme: MD2Theme;
140

141
/** Material Design 2 dark theme */
142
const MD2DarkTheme: MD2Theme;
143
```
144

145
### Theme Utilities
146

147
Utility functions for theme manipulation and configuration.
148

149
```typescript { .api }
150
/**
151
 * Get theme by version and scheme
152
 * @param isDark - Whether to return dark theme
153
 * @param isV3 - Whether to use Material Design 3
154
 * @returns Appropriate theme object
155
 */
156
function getTheme<Scheme extends boolean = false, IsVersion3 extends boolean = true>(
157
  isDark?: Scheme,
158
  isV3?: IsVersion3  
159
): (typeof defaultThemesByVersion)[IsVersion3 extends true ? 3 : 2][Scheme extends true ? 'dark' : 'light'];
160

161
/** Theme configuration by version and scheme */
162
const defaultThemesByVersion: {
163
  2: { light: MD2Theme; dark: MD2Theme };
164
  3: { light: MD3Theme; dark: MD3Theme };
165
};
166
```
167

168
### React Navigation Integration
169

170
Utility for adapting Material themes to work with React Navigation.
171

172
```typescript { .api }
173
/**
174
 * Adapts Material Design themes for React Navigation
175
 * @param themes - Navigation and material theme configuration
176
 * @returns Adapted navigation themes
177
 */
178
function adaptNavigationTheme<T extends NavigationTheme>(themes: {
179
  reactNavigationLight?: T;
180
  reactNavigationDark?: T;
181
  materialLight?: MD3Theme;
182
  materialDark?: MD3Theme;
183
}): { LightTheme?: T; DarkTheme?: T };
184

185
interface NavigationTheme {
186
  dark: boolean;
187
  colors: {
188
    primary: string;
189
    background: string;
190
    card: string;
191
    text: string;
192
    border: string;
193
    notification: string;
194
  };
195
}
196
```
197

198
**Usage Example:**
199

200
```typescript
201
import { DefaultTheme as NavigationDefaultTheme, DarkTheme as NavigationDarkTheme } from '@react-navigation/native';
202
import { MD3LightTheme, MD3DarkTheme, adaptNavigationTheme } from 'react-native-paper';
203

204
const { LightTheme, DarkTheme } = adaptNavigationTheme({
205
  reactNavigationLight: NavigationDefaultTheme,
206
  reactNavigationDark: NavigationDarkTheme,
207
  materialLight: MD3LightTheme,
208
  materialDark: MD3DarkTheme,
209
});
210
```
211

212
### Style Utilities
213

214
Utility functions for shadows, overlays, and font configuration.
215

216
```typescript { .api }
217
/**
218
 * Generate shadow styles for elevation
219
 * @param elevation - Elevation level (0-24)
220
 * @returns Shadow style object
221
 */
222
function shadow(elevation: number): {
223
  shadowOffset: { width: number; height: number };
224
  shadowOpacity: number;
225
  shadowRadius: number;
226
  elevation: number;
227
};
228

229
/**
230
 * Generate overlay color for surfaces
231
 * @param elevation - Elevation level
232
 * @param surfaceColor - Base surface color
233
 * @returns Overlay color string
234
 */
235
function overlay(elevation: number, surfaceColor?: string): string;
236

237
/**
238
 * Configure custom fonts for themes
239
 * @param config - Font configuration
240
 * @returns Font configuration object
241
 */
242
function configureFonts(config: {
243
  ios?: Partial<Fonts>;
244
  android?: Partial<Fonts>;
245
  web?: Partial<Fonts>;
246
}): Fonts;
247
```
248

249
### Color Collections
250

251
Pre-defined color collections for Material Design 2 and 3.
252

253
```typescript { .api }
254
/** Material Design 2 color tokens */
255
namespace MD2Colors {
256
  const red50: string;
257
  const red100: string;
258
  const red200: string;
259
  // ... additional color tokens
260
  const purple500: string;
261
  const purple600: string;
262
  // ... complete MD2 color palette
263
}
264

265
/** Material Design 3 color tokens */
266
namespace MD3Colors {
267
  const primary0: string;
268
  const primary10: string;
269
  const primary20: string;
270
  // ... complete MD3 color palette
271
  const neutral99: string;
272
  const neutralVariant99: string;
273
}
274
```
275

276
### Dynamic Theme Colors
277

278
Utility for generating dynamic theme colors on Android 12+.
279

280
```typescript { .api }
281
/**
282
 * Generate dynamic elevation colors based on Material You
283
 * @param scheme - Android dynamic color scheme
284
 * @returns Elevation color mapping
285
 */
286
function getDynamicThemeElevations(scheme: MD3AndroidColors): MD3ElevationColors;
287

288
interface MD3AndroidColors {
289
  primary: number;
290
  primaryContainer: number;
291
  secondary: number;
292
  secondaryContainer: number;
293
  tertiary: number;
294
  tertiaryContainer: number;
295
  surface: number;
296
  surfaceVariant: number;
297
  background: number;
298
  error: number;
299
  errorContainer: number;
300
  onPrimary: number;
301
  onPrimaryContainer: number;
302
  onSecondary: number;
303
  onSecondaryContainer: number;
304
  onTertiary: number;
305
  onTertiaryContainer: number;
306
  onSurface: number;
307
  onSurfaceVariant: number;
308
  onError: number;
309
  onErrorContainer: number;
310
  onBackground: number;
311
  outline: number;
312
  outlineVariant: number;
313
  inverseSurface: number;
314
  inverseOnSurface: number;
315
  inversePrimary: number;
316
  shadow: number;
317
  scrim: number;
318
}
319
```
320

321
## Types
322

323
```typescript { .api }
324
interface MD3Theme extends ThemeBase {
325
  version: 3;
326
  isV3: true;
327
  colors: MD3Colors;
328
  fonts: MD3Typescale;
329
}
330

331
interface MD2Theme extends ThemeBase {
332
  version: 2;
333
  isV3: false;
334
  colors: MD2Colors;
335
  fonts: Fonts;
336
}
337

338
interface ThemeBase {
339
  dark: boolean;
340
  mode?: 'adaptive' | 'exact';
341
  roundness: number;
342
  animation: {
343
    scale: number;
344
    defaultAnimationDuration?: number;
345
  };
346
}
347

348
interface MD3Colors {
349
  primary: string;
350
  primaryContainer: string;
351
  secondary: string;
352
  secondaryContainer: string;
353
  tertiary: string;
354
  tertiaryContainer: string;
355
  surface: string;
356
  surfaceVariant: string;
357
  surfaceDisabled: string;
358
  background: string;
359
  error: string;
360
  errorContainer: string;
361
  onPrimary: string;
362
  onPrimaryContainer: string;
363
  onSecondary: string;
364
  onSecondaryContainer: string;
365
  onTertiary: string;
366
  onTertiaryContainer: string;
367
  onSurface: string;
368
  onSurfaceVariant: string;
369
  onSurfaceDisabled: string;
370
  onError: string;
371
  onErrorContainer: string;
372
  onBackground: string;
373
  outline: string;
374
  outlineVariant: string;
375
  inverseSurface: string;
376
  inverseOnSurface: string;
377
  inversePrimary: string;
378
  shadow: string;
379
  scrim: string;
380
  backdrop: string;
381
  elevation: MD3ElevationColors;
382
}
383

384
interface MD2Colors {
385
  primary: string;
386
  background: string;
387
  surface: string;
388
  accent: string;
389
  error: string;
390
  text: string;
391
  onSurface: string;
392
  disabled: string;
393
  placeholder: string;
394
  backdrop: string;
395
  notification: string;
396
  tooltip: string;
397
}
398

399
interface MD3ElevationColors {
400
  level0: string;
401
  level1: string;
402
  level2: string;
403
  level3: string;
404
  level4: string;
405
  level5: string;
406
}
407

408
interface Fonts {
409
  regular: Font;
410
  medium: Font;
411
  light: Font;
412
  thin: Font;
413
}
414

415
interface Font {
416
  fontFamily: string;
417
  fontWeight?: 'normal' | 'bold' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900';
418
  fontStyle?: 'normal' | 'italic';
419
}
420

421
type MD3Typescale = {
422
  [key in MD3TypescaleKey]: MD3Type;
423
} & {
424
  default: Omit<MD3Type, 'lineHeight' | 'fontSize'>;
425
};
426

427
interface MD3Type {
428
  fontFamily: string;
429
  letterSpacing: number;
430
  fontWeight: Font['fontWeight'];
431
  lineHeight: number;
432
  fontSize: number;
433
  fontStyle?: Font['fontStyle'];
434
}
435

436
type InternalTheme = MD2Theme | MD3Theme;
437
type ThemeProp = $DeepPartial<InternalTheme>;
438
```