Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
97 changes: 64 additions & 33 deletions docs/docs/guides/02-theming.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: Theming
---

import DynamicColorTheme from '@site/src/components/DynamicColorTheme.tsx'
import DynamicColorTheme from '@site/src/components/DynamicColorTheme.tsx';

# Theming

Expand Down Expand Up @@ -188,18 +188,18 @@ export default function Main() {

## Creating dynamic theme colors

Dynamic Color Themes allows for generating two color schemes lightScheme and darkScheme, based on the provided source color.
Dynamic Color Themes allows for generating two color schemes lightScheme and darkScheme, based on the provided source color.
Created schemes are following the Material Design 3 color system and covering colors structure from the Paper theme. User may generate these schemes using the following tool:

<DynamicColorTheme />

<br />

Passed source color into the util is translated into tones to automatically provide the range of tones that map to color roles.
Passed source color into the util is translated into tones to automatically provide the range of tones that map to color roles.

![customColors](../../static/screenshots/custom-colors.png)

*Source: [Material You Color System](https://m3.material.io/styles/color/the-color-system/custom-colors)*
_Source: [Material You Color System](https://m3.material.io/styles/color/the-color-system/custom-colors)_

### Using schemes

Expand Down Expand Up @@ -240,11 +240,7 @@ To get started, follow the [installation instructions](https://github.com/pchmn/
```tsx
import { useMaterial3Theme } from '@pchmn/expo-material3-theme';
import { useColorScheme } from 'react-native';
import {
MD3DarkTheme,
MD3LightTheme,
PaperProvider,
} from 'react-native-paper';
import { MD3DarkTheme, MD3LightTheme, PaperProvider } from 'react-native-paper';
import App from './src/App';

export default function Main() {
Expand All @@ -269,29 +265,65 @@ export default function Main() {
The `adaptNavigationTheme` function takes an existing React Navigation theme and returns a React Navigation theme using the colors from Material Design 3. This theme can be passed to `NavigationContainer` so that React Navigation's UI elements have the same color scheme as Paper.

```ts
adaptNavigationTheme(themes)
adaptNavigationTheme(themes);
```

:::info
For users of `react-navigation` version `7.0.0` and above, `adaptNavigationTheme` overrides the **fonts** from the navigation theme as follows:

```ts
fonts: {
regular: {
fontFamily: materialTheme.fonts.bodyMedium.fontFamily,
fontWeight: materialTheme.fonts.bodyMedium.fontWeight,
letterSpacing: materialTheme.fonts.bodyMedium.letterSpacing,
},
medium: {
fontFamily: materialTheme.fonts.titleMedium.fontFamily,
fontWeight: materialTheme.fonts.titleMedium.fontWeight,
letterSpacing: materialTheme.fonts.titleMedium.letterSpacing,
},
bold: {
fontFamily: materialTheme.fonts.headlineSmall.fontFamily,
fontWeight: materialTheme.fonts.headlineSmall.fontWeight,
letterSpacing: materialTheme.fonts.headlineSmall.letterSpacing,
},
heavy: {
fontFamily: materialTheme.fonts.headlineLarge.fontFamily,
fontWeight: materialTheme.fonts.headlineLarge.fontWeight,
letterSpacing: materialTheme.fonts.headlineLarge.letterSpacing,
},
}
```

:::

<b>Parameters:</b>

| NAME | TYPE |
| ----------- | ----------- |
| themes | object |
| NAME | TYPE |
| ------ | ------ |
| themes | object |

Valid `themes` keys are:

* `reactNavigationLight` () - React Navigation compliant light theme.
* `reactNavigationDark` () - React Navigation compliant dark theme.
* `materialLight` () - React Native Paper compliant light theme.
* `materialDark` () - React Native Paper compliant dark theme.
- `reactNavigationLight` () - React Navigation compliant light theme.
- `reactNavigationDark` () - React Navigation compliant dark theme.
- `materialLight` () - React Native Paper compliant light theme.
- `materialDark` () - React Native Paper compliant dark theme.

```ts
// App.tsx
import { NavigationContainer, DefaultTheme } from '@react-navigation/native';
import { createStackNavigator } from '@react-navigation/stack';
import { PaperProvider, MD3LightTheme, adaptNavigationTheme } from 'react-native-paper';
import {
PaperProvider,
MD3LightTheme,
adaptNavigationTheme,
} from 'react-native-paper';
const Stack = createStackNavigator();
const { LightTheme } = adaptNavigationTheme({ reactNavigationLight: DefaultTheme });
const { LightTheme } = adaptNavigationTheme({
reactNavigationLight: DefaultTheme,
});
export default function App() {
return (
<PaperProvider theme={MD3LightTheme}>
Expand All @@ -312,12 +344,19 @@ By default, TypeScript works well whenever you change the value of the built-in

There are two supported ways of overriding the theme:

1. <b>Simple built-in theme overrides</b> - when you only customize the values and the whole theme schema remains the same
2. <b>Advanced theme overrides</b> - when you <i>add new properties</i> or <i>change the built-in schema shape</i>
1. <b>Simple built-in theme overrides</b> - when you only customize the values and
the whole theme schema remains the same
2. <b>Advanced theme overrides</b> - when you <i>add new properties</i> or <i>
change the built-in schema shape
</i>

:::caution
TypeScript support for `withTheme` is currently limited to <b>Material You (MD3)</b> theme only.
<i>We are planning to provide a better support of handling custom theme overrides in future releases.</i>
TypeScript support for `withTheme` is currently limited to <b>Material You (MD3)</b> theme only.

<i>
We are planning to provide a better support of handling custom theme overrides
in future releases.
</i>
:::

### Simple built-in theme overrides
Expand Down Expand Up @@ -387,11 +426,7 @@ export default function Main() {

```ts
import * as React from 'react';
import {
MD3LightTheme,
PaperProvider,
useTheme,
} from 'react-native-paper';
import { MD3LightTheme, PaperProvider, useTheme } from 'react-native-paper';
import App from './src/App';

const theme = {
Expand Down Expand Up @@ -499,11 +534,7 @@ The final example for Material Design 2 would look like this:

```ts
import * as React from 'react';
import {
MD2LightTheme,
PaperProvider,
useTheme,
} from 'react-native-paper';
import { MD2LightTheme, PaperProvider, useTheme } from 'react-native-paper';
import App from './src/App';

const theme = {
Expand Down
52 changes: 10 additions & 42 deletions example/src/index.native.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -4,33 +4,31 @@ import { I18nManager } from 'react-native';
import { useMaterial3Theme } from '@pchmn/expo-material3-theme';
import AsyncStorage from '@react-native-async-storage/async-storage';
import { createDrawerNavigator } from '@react-navigation/drawer';
import {
InitialState,
NavigationContainer,
DarkTheme as NavigationDarkTheme,
DefaultTheme as NavigationDefaultTheme,
} from '@react-navigation/native';
import { InitialState, NavigationContainer } from '@react-navigation/native';
import { useFonts } from 'expo-font';
import { useKeepAwake } from 'expo-keep-awake';
import { StatusBar } from 'expo-status-bar';
import * as Updates from 'expo-updates';
import {
Provider as PaperProvider,
MD3DarkTheme,
MD3LightTheme,
PaperProvider,
MD2DarkTheme,
MD2LightTheme,
MD3DarkTheme,
MD3LightTheme,
MD2Theme,
MD3Theme,
useTheme,
adaptNavigationTheme,
configureFonts,
} from 'react-native-paper';
import { SafeAreaInsetsContext } from 'react-native-safe-area-context';

import DrawerItems from './DrawerItems';
import App from './RootNavigator';
import { deviceColorsSupported } from '../utils';
import {
CombinedDefaultTheme,
CombinedDarkTheme,
createConfiguredFontTheme,
} from '../utils/themes';

const PERSISTENCE_KEY = 'NAVIGATION_STATE';
const PREFERENCES_KEY = 'APP_PREFERENCES';
Expand Down Expand Up @@ -192,38 +190,8 @@ export default function PaperExample() {
return null;
}

const { LightTheme, DarkTheme } = adaptNavigationTheme({
reactNavigationLight: NavigationDefaultTheme,
reactNavigationDark: NavigationDarkTheme,
});

const CombinedDefaultTheme = {
...MD3LightTheme,
...LightTheme,
colors: {
...MD3LightTheme.colors,
...LightTheme.colors,
},
};

const CombinedDarkTheme = {
...MD3DarkTheme,
...DarkTheme,
colors: {
...MD3DarkTheme.colors,
...DarkTheme.colors,
},
};

const combinedTheme = isDarkMode ? CombinedDarkTheme : CombinedDefaultTheme;
const configuredFontTheme = {
...combinedTheme,
fonts: configureFonts({
config: {
fontFamily: 'Abel',
},
}),
};
const configuredFontTheme = createConfiguredFontTheme(combinedTheme);

return (
<PaperProvider
Expand Down
46 changes: 7 additions & 39 deletions example/src/index.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,7 @@ import * as React from 'react';

import AsyncStorage from '@react-native-async-storage/async-storage';
import { createDrawerNavigator } from '@react-navigation/drawer';
import {
InitialState,
NavigationContainer,
DarkTheme as NavigationDarkTheme,
DefaultTheme as NavigationDefaultTheme,
} from '@react-navigation/native';
import { InitialState, NavigationContainer } from '@react-navigation/native';
import { useFonts } from 'expo-font';
import { useKeepAwake } from 'expo-keep-awake';
import {
Expand All @@ -19,13 +14,16 @@ import {
MD2Theme,
MD3Theme,
useTheme,
adaptNavigationTheme,
configureFonts,
} from 'react-native-paper';
import { SafeAreaInsetsContext } from 'react-native-safe-area-context';

import DrawerItems from './DrawerItems';
import App from './RootNavigator';
import {
CombinedDarkTheme,
CombinedDefaultTheme,
createConfiguredFontTheme,
} from '../utils/themes';

const PERSISTENCE_KEY = 'NAVIGATION_STATE';
const PREFERENCES_KEY = 'APP_PREFERENCES';
Expand Down Expand Up @@ -149,38 +147,8 @@ export default function PaperExample() {
return null;
}

const { LightTheme, DarkTheme } = adaptNavigationTheme({
reactNavigationLight: NavigationDefaultTheme,
reactNavigationDark: NavigationDarkTheme,
});

const CombinedDefaultTheme = {
...MD3LightTheme,
...LightTheme,
colors: {
...MD3LightTheme.colors,
...LightTheme.colors,
},
};

const CombinedDarkTheme = {
...MD3DarkTheme,
...DarkTheme,
colors: {
...MD3DarkTheme.colors,
...DarkTheme.colors,
},
};

const combinedTheme = isDarkMode ? CombinedDarkTheme : CombinedDefaultTheme;
const configuredFontTheme = {
...combinedTheme,
fonts: configureFonts({
config: {
fontFamily: 'Abel',
},
}),
};
const configuredFontTheme = createConfiguredFontTheme(combinedTheme);

return (
<PaperProvider
Expand Down
44 changes: 44 additions & 0 deletions example/utils/themes.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
import {
DarkTheme as NavigationDarkTheme,
DefaultTheme as NavigationDefaultTheme,
} from '@react-navigation/native';
import {
adaptNavigationTheme,
MD3DarkTheme,
MD3LightTheme,
configureFonts,
} from 'react-native-paper';

const { LightTheme, DarkTheme } = adaptNavigationTheme({
reactNavigationLight: NavigationDefaultTheme,
reactNavigationDark: NavigationDarkTheme,
});

export const CombinedDefaultTheme = {
...MD3LightTheme,
...LightTheme,
colors: {
...MD3LightTheme.colors,
...LightTheme.colors,
},
};

export const CombinedDarkTheme = {
...MD3DarkTheme,
...DarkTheme,
colors: {
...MD3DarkTheme.colors,
...DarkTheme.colors,
},
};

type CombinedTheme = typeof CombinedDefaultTheme;

export const createConfiguredFontTheme = (theme: CombinedTheme) => ({
...theme,
fonts: configureFonts({
config: {
fontFamily: 'Abel',
},
}),
});
Loading
Loading