Skip to content

Commit af39102

Browse files
lukewalczaklukewalczak
authored
refactor: deprecations clean up (#4740)
* refactor: remove deprecated and renamed annotations * refactor: remove react-navigation directory * docs: adjust theme names, remove MD2 part
1 parent e9ac46d commit af39102

26 files changed

+356
-1368
lines changed

‎docs/docs/guides/01-getting-started.md‎

Lines changed: 1 addition & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -142,10 +142,7 @@ Example:
142142

143143
```js
144144
import * as React from 'react';
145-
import {
146-
MD3LightTheme as DefaultTheme,
147-
PaperProvider,
148-
} from 'react-native-paper';
145+
import { DefaultTheme, PaperProvider } from 'react-native-paper';
149146
import App from './src/App';
150147

151148
const theme = {
@@ -165,7 +162,3 @@ export default function Main() {
165162
);
166163
}
167164
```
168-
169-
:::note
170-
For MD2 check the following [Material Design 2 default theme](https://github.com/callstack/react-native-paper/blob/main/src/styles/themes/v2/LightTheme.tsx).
171-
:::

‎docs/docs/guides/02-theming.mdx‎

Lines changed: 17 additions & 163 deletions
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,6 @@ export default function Main() {
2828
}
2929
```
3030

31-
By default React Native Paper will apply the [Material You theme (MD3)](https://github.com/callstack/react-native-paper/blob/main/src/styles/themes/v3/LightTheme.tsx) if no `theme` or `version` prop is passed to the `PaperProvider`.
32-
3331
## Accessing theme properties
3432

3533
Use the built-in `useTheme()` hook to get access to the theme's variables:
@@ -65,9 +63,6 @@ You can change the theme prop dynamically and all the components will automatica
6563
A theme usually contains the following properties:
6664

6765
- `dark` (`boolean`): whether this is a dark theme or light theme.
68-
- `version`: specify which design system components should follow in the app
69-
- 3 - new Material You (MD3)
70-
- 2 - previous Material Design (MD2)
7166
- `mode` (`'adaptive' | 'exact'`): color mode for dark theme (See [Dark Theme](#dark-theme)).
7267
- `roundness` (`number`): roundness of common elements, such as buttons.
7368
- `colors` (`object`): various colors used throughout different elements.
@@ -160,10 +155,7 @@ Keeping your own properties in the theme is fully supported by our library:
160155

161156
```js
162157
import * as React from 'react';
163-
import {
164-
MD3LightTheme as DefaultTheme,
165-
PaperProvider,
166-
} from 'react-native-paper';
158+
import { DefaultTheme, PaperProvider } from 'react-native-paper';
167159
import App from './src/App';
168160

169161
const theme = {
@@ -207,10 +199,7 @@ Once we have copied the color schemes from the generated JSON above, we can use
207199

208200
```jsx
209201
import * as React from 'react';
210-
import {
211-
MD3LightTheme as DefaultTheme,
212-
PaperProvider,
213-
} from 'react-native-paper';
202+
import { DefaultTheme, PaperProvider } from 'react-native-paper';
214203
import App from './src/App';
215204

216205
const theme = {
@@ -240,7 +229,7 @@ To get started, follow the [installation instructions](https://github.com/pchmn/
240229
```tsx
241230
import { useMaterial3Theme } from '@pchmn/expo-material3-theme';
242231
import { useColorScheme } from 'react-native';
243-
import { MD3DarkTheme, MD3LightTheme, PaperProvider } from 'react-native-paper';
232+
import { DarkTheme, LightTheme, PaperProvider } from 'react-native-paper';
244233
import App from './src/App';
245234

246235
export default function Main() {
@@ -249,8 +238,8 @@ export default function Main() {
249238

250239
const paperTheme =
251240
colorScheme === 'dark'
252-
? { ...MD3DarkTheme, colors: theme.dark }
253-
: { ...MD3LightTheme, colors: theme.light };
241+
? { ...DarkTheme, colors: theme.dark }
242+
: { ...LightTheme, colors: theme.light };
254243

255244
return (
256245
<PaperProvider theme={paperTheme}>
@@ -317,7 +306,7 @@ import { NavigationContainer, DefaultTheme } from '@react-navigation/native';
317306
import { createStackNavigator } from '@react-navigation/stack';
318307
import {
319308
PaperProvider,
320-
MD3LightTheme,
309+
LightTheme as PaperLightTheme,
321310
adaptNavigationTheme,
322311
} from 'react-native-paper';
323312
const Stack = createStackNavigator();
@@ -326,7 +315,7 @@ const { LightTheme } = adaptNavigationTheme({
326315
});
327316
export default function App() {
328317
return (
329-
<PaperProvider theme={MD3LightTheme}>
318+
<PaperProvider theme={PaperLightTheme}>
330319
<NavigationContainer theme={LightTheme}>
331320
<Stack.Navigator initialRouteName="Home">
332321
<Stack.Screen name="Home" component={HomeScreen} />
@@ -350,29 +339,20 @@ There are two supported ways of overriding the theme:
350339
change the built-in schema shape
351340
</i>
352341

353-
:::caution
354-
TypeScript support for `withTheme` is currently limited to <b>Material You (MD3)</b> theme only.
355-
356-
<i>
357-
We are planning to provide a better support of handling custom theme overrides
358-
in future releases.
359-
</i>
360-
:::
361-
362342
### Simple built-in theme overrides
363343

364344
You can provide a `theme` prop with a theme object with the same properties as the default theme:
365345

366346
```js
367347
import * as React from 'react';
368-
import { MD3LightTheme, PaperProvider } from 'react-native-paper';
348+
import { LightTheme, PaperProvider } from 'react-native-paper';
369349
import App from './src/App';
370350

371351
const theme = {
372-
...MD3LightTheme, // or MD3DarkTheme
352+
...LightTheme, // or DarkTheme
373353
roundness: 2,
374354
colors: {
375-
...MD3LightTheme.colors,
355+
...LightTheme.colors,
376356
primary: '#3498db',
377357
secondary: '#f1c40f',
378358
tertiary: '#a1b2c3',
@@ -396,18 +376,18 @@ If you need to modify the built-in theme schema by adding a new property or chan
396376

397377
```ts
398378
import * as React from 'react';
399-
import { MD3LightTheme, PaperProvider } from 'react-native-paper';
379+
import { LightTheme, PaperProvider } from 'react-native-paper';
400380
import App from './src/App';
401381

402382
const theme = {
403-
...MD3LightTheme,
383+
...LightTheme,
404384

405385
// Specify a custom property
406386
custom: 'property',
407387

408388
// Specify a custom property in nested object
409389
colors: {
410-
...MD3LightTheme.colors,
390+
...LightTheme.colors,
411391
brandPrimary: '#fefefe',
412392
brandSecondary: 'red',
413393
},
@@ -426,18 +406,18 @@ export default function Main() {
426406

427407
```ts
428408
import * as React from 'react';
429-
import { MD3LightTheme, PaperProvider, useTheme } from 'react-native-paper';
409+
import { LightTheme, PaperProvider, useTheme } from 'react-native-paper';
430410
import App from './src/App';
431411

432412
const theme = {
433-
...MD3LightTheme,
413+
...LightTheme,
434414

435415
// Specify a custom property
436416
custom: 'property',
437417

438418
// Specify a custom property in nested object
439419
colors: {
440-
...MD3LightTheme.colors,
420+
...LightTheme.colors,
441421
brandPrimary: '#fefefe',
442422
brandSecondary: 'red',
443423
},
@@ -471,112 +451,6 @@ export default function HomeScreen() {
471451
}
472452
```
473453

474-
## Material Design 2
475-
476-
Using Material Design 2 is <b>fully supported in React Native Paper v5.x</b>.
477-
478-
### Simple setup
479-
480-
In order to use the Material Design 2 theme you can just pass `{ version: 2 }` to the PaperProvider theme prop:
481-
482-
```js
483-
import * as React from 'react';
484-
import { PaperProvider } from 'react-native-paper';
485-
import App from './src/App';
486-
487-
export default function Main() {
488-
return (
489-
<PaperProvider theme={{ version: 2 }}>
490-
<App />
491-
</PaperProvider>
492-
);
493-
}
494-
```
495-
496-
Specifying `{ version: 2 }` tells React Native Paper to use the built in Material Design 2 theme, so you don't have to fully extend it on your own.
497-
498-
### Advanced setup
499-
500-
As with any theme, you can also specify your custom properties within the Material Design 2 theme:
501-
502-
```js
503-
import * as React from 'react';
504-
import { MD2LightTheme, PaperProvider } from 'react-native-paper';
505-
import App from './src/App';
506-
507-
export default function Main() {
508-
const theme = {
509-
...MD2LightTheme,
510-
511-
// Specify a custom property
512-
custom: 'property',
513-
514-
// Specify a custom nested property
515-
colors: {
516-
...MD2LightTheme.colors,
517-
primary: '#fefefe',
518-
},
519-
};
520-
521-
return (
522-
<PaperProvider theme={theme}>
523-
<App />
524-
</PaperProvider>
525-
);
526-
}
527-
```
528-
529-
### Typescript
530-
531-
Due to the amount of changes in the theme's schema shape it falls into the [Advanced theme overrides](#advanced-theme-overrides) category. The steps are identical as with any advanced theme, just make sure to extend the built-in `MD2LightTheme` or `MD2DarkTheme` instead of `MD3LightTheme` or `MD3DarkTheme`.
532-
533-
The final example for Material Design 2 would look like this:
534-
535-
```ts
536-
import * as React from 'react';
537-
import { MD2LightTheme, PaperProvider, useTheme } from 'react-native-paper';
538-
import App from './src/App';
539-
540-
const theme = {
541-
// Extend Material Design 2 theme
542-
543-
...MD2LightTheme, // or MD2DarkTheme
544-
545-
// Specify a custom property
546-
myOwnProperty: true,
547-
548-
// Specify a custom nested property
549-
colors: {
550-
...MD2LightTheme.colors,
551-
myOwnColor: '#BADA55',
552-
},
553-
};
554-
555-
export type AppTheme = typeof theme;
556-
557-
export const useAppTheme = () => useTheme<AppTheme>();
558-
559-
export default function Main() {
560-
return (
561-
<PaperProvider theme={theme}>
562-
<App />
563-
</PaperProvider>
564-
);
565-
}
566-
567-
// App.tsx
568-
569-
export default function App() {
570-
const { theme } = useAppTheme();
571-
572-
return <View style={{ backgroundColor: theme.colors.primary }} />;
573-
}
574-
```
575-
576-
### Migrating to Material You
577-
578-
If you are migrating from Material Design 2 (4.x and lower) to Material You (5.x), please refer to our [Migration Guide](https://callstack.github.io/react-native-paper/docs/guides/migration-guide-to-5.0)
579-
580454
## Applying a theme to a paper component
581455

582456
If you want to change the theme for a certain component from the library, you can directly pass the `theme` prop to the component. The theme passed as the prop is merged with the theme from the `PaperProvider`:
@@ -586,11 +460,7 @@ import * as React from 'react';
586460
import { Button } from 'react-native-paper';
587461

588462
export default function ButtonExample() {
589-
return (
590-
<Button raised theme={{ roundness: 3 }}>
591-
Press me
592-
</Button>
593-
);
463+
return <Button theme={{ roundness: 3 }}>Press me</Button>;
594464
}
595465
```
596466

@@ -616,22 +486,6 @@ export default function FancyButton(props) {
616486

617487
Now you can use your `FancyButton` component everywhere instead of using `Button` from Paper.
618488

619-
## Dark Theme
620-
621-
Since 3.0 we adapt dark theme to follow [Material design guidelines](https://material.io/design/color/dark-theme.html). <br/>
622-
In contrast to light theme, dark theme by default uses `surface` colour instead of `primary` on large components like `AppBar` or `BottomNavigation`.<br/>
623-
The dark theme adds a white overlay with opacity depending on elevation of surfaces. It uses it for the better accentuation of surface elevation. Using only shadow is highly imperceptible on dark surfaces.
624-
625-
We are aware that users often use dark theme in their own ways and may not want to use the default dark theme features from the guidelines.<br/>
626-
That's why if you are using dark theme you can switch between two dark theme `mode`s:
627-
628-
- `exact` where everything is like it was before. `Appbar` and `BottomNavigation` will still use primary colour by default.<br/>
629-
- `adaptive` where we follow [Material design guidelines](https://material.io/design/color/dark-theme.html), the surface will use white overlay with opacity to show elevation, `Appbar` and `BottomNavigation` will use surface colour as a background.
630-
631-
If you don't use a custom theme, Paper will automatically change between the default theme and the default dark theme, depending on device settings.
632-
633-
Otherwise, your custom theme will need to handle it manually, using React Native's [Appearance API](https://reactnative.dev/docs/appearance).
634-
635489
## Gotchas
636490

637491
The `PaperProvider` exposes the theme to the components via [React's context API](https://reactjs.org/docs/context.html), which means that the component must be in the same tree as the `PaperProvider`. Some React Native components will render a different tree such as a `Modal`, in which case the components inside the `Modal` won't be able to access the theme. The work around is to get the theme using the `withTheme` HOC and pass it down to the components as props, or expose it again with the exported `ThemeProvider` component.

0 commit comments

Comments
 (0)