https://github.com/alabsi91/react-native-material-you-colors
Bring Material You color palettes to Android, iOS, and web platforms.
https://github.com/alabsi91/react-native-material-you-colors
android dynamic-color expo ios material-design palette-generation react-native web
Last synced: about 1 year ago
JSON representation
Bring Material You color palettes to Android, iOS, and web platforms.
- Host: GitHub
- URL: https://github.com/alabsi91/react-native-material-you-colors
- Owner: alabsi91
- License: mit
- Created: 2023-09-02T17:42:18.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2023-10-23T12:03:53.000Z (over 2 years ago)
- Last Synced: 2024-10-05T22:17:58.287Z (over 1 year ago)
- Topics: android, dynamic-color, expo, ios, material-design, palette-generation, react-native, web
- Language: TypeScript
- Homepage:
- Size: 764 KB
- Stars: 24
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
[](https://www.npmjs.com/package/react-native-material-you-colors)
[](https://github.com/alabsi91/react-native-material-you-colors/blob/main/LICENSE)
[](https://github.com/alabsi91/react-native-material-you-colors/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc)
https://github.com/alabsi91/react-native-material-you-colors/assets/58077449/5d70f2a6-ae2a-42c3-be02-0446e9f69f42
# React Native Material You Colors
React Native Material You Colors simplifies the retrieval of Material You color palettes while ensuring compatibility across multiple platforms. With just a single seed color, you can generate palettes inspired by Material You's dynamic theming.
> Please check out my other library, [`Reanimated Color Picker`](https://github.com/alabsi91/reanimated-color-picker)
## Key Features
1. Multi-Platform Support: Andorid, IOS and WEB
2. Theme Management
## Installation
```sh
npm install react-native-material-you-colors
```
> **Warning**
> For `Expo` users, please note that the native side of this library will not function in `Expo Go` during app development. The native side is solely used to retrieve Material You colors from the `Android` system, but you can still generate palettes. The native side will work as expected after building the app in production mode.
## Usage
### Without using the Theme Provider
```ts
import MaterialYou from 'react-native-material-you-colors';
const palette = MaterialYou.getMaterialYouPalette();
/**
* The output object
* {
* system_accent1: string[]; An array containing `13` color shades.
* system_accent2: string[];
* system_accent3: string[];
* system_neutral1: string[];
* system_neutral2: string[];
* }
*/
```
**API**
- **isSupported**
```ts
MaterialYou.isSupported : boolean
```
To verify the current platform/device support for Material You dynamic colors.
- **getMaterialYouPalette**
```ts
MaterialYou.getMaterialYouPalette(fallbackSeedColor?: string, style?: GenerationStyle): MaterialYouPalette
```
Get the Material You color palette from the Android system on the device.
If Material You is not supported on the user's device, a color palette generated from a fallback seed color will be returned.
- **generatePaletteFromColor**
```ts
MaterialYou.generatePaletteFromColor(colorSeed: string, style?: GenerationStyle): MaterialYouPalette
```
Generate a complete Material You palette from a single HEX color (seed color).
Various styles are available to choose from, each of which dictates how the palette will be generated.
**Note:** The input seed color should be in HEX format (#RRGGBB), without the alpha channel. For example, `#1b6ef3`.
- **The shape of the output palette data**
```ts
type MaterialYouPalette = {
system_accent1: string[]; // An array containing `13` color shades.
system_accent2: string[];
system_accent3: string[];
system_neutral1: string[];
system_neutral2: string[];
};
```
### Using the Theme Provider
1. Create a new theme context and provide a function to determine which colors you want to use.
> **Warning**
> The function should return an object with the keys `light` and `dark`, where both keys contain objects with the same set of keys representing the colors you want to use for the light and dark themes.
```ts
// theme.ts
import MaterialYou from 'react-native-material-you-colors';
import type { MaterialYouPalette } from 'react-native-material-you-colors';
function generateTheme(palette: MaterialYouPalette) {
const light = {
isDark: false,
primary: palette.system_accent1[7], // shade 500
text: palette.system_accent1[9], // shade 700
textColored: palette.system_accent1[2], // shade 50
background: palette.system_neutral1[1], // shade 10
card: palette.system_accent2[2], // shade 50
icon: palette.system_accent1[10], // shade 800
};
const dark: typeof light = {
isDark: true,
primary: palette.system_accent1[4], // shade 200
text: palette.system_accent1[3], // shade 100
textColored: palette.system_accent1[9], // shade 700
background: palette.system_neutral1[11], // shade 900
card: palette.system_accent2[10], // shade 800
icon: palette.system_accent1[3], // shade 100
};
return { light, dark };
}
export const { ThemeProvider, useMaterialYouTheme } = MaterialYou.createThemeContext(generateTheme);
```
2. Wrap your app with the Theme Provider, providing the initial props:
```ts
// App.tsx
import React from 'react';
import Home from './screens/Home';
import { ThemeProvider } from './Theme'; // 👈
export default function App() {
return (
);
}
```
**`ThemeProvider` props:**
| Prop | Type | Description | Default |
| ----------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------- |
| `colorScheme` | `"auto" \| "dark" \| "light"` | Specifies the initial color scheme for your app. | `"auto"` |
| `fallbackColor` | `string` (HEX Color) | This is used to generate a fallback palette in case the platform does not support Material You colors. | `'#1b6ef3'` |
| `generationStyle` | `"SPRITZ"\| "TONAL_SPOT"\| "VIBRANT"\| "EXPRESSIVE"\| "RAINBOW"\| "FRUIT_SALAD"\| "CONTENT"\| "MONOCHROMATIC"` | Palette generation style. | `"TONAL_SPOT"` |
| `seedColor` | `"auto" \| string` (HEX Color) | If set to `"auto"`, it tries to get the palette from the device, falling back to the provided color if unsupported. If set to a color (HEX only), it generates a new palette without device retrieval. | `"auto"` |
3. Use the `useMaterialYouTheme` hook to access the current theme in your components:
```jsx
import React from 'react';
import { Image, StyleSheet, Text, View } from 'react-native';
import { useMaterialYouTheme } from './Theme'; // 👈
export default function MyComponent() {
const theme = useMaterialYouTheme();
return
// ...
}
```
**`useMaterialYouTheme` provide other utilities you can use throw your app:**
- **Changing Color Scheme**
```ts
setColorScheme: (value: "auto" | "dark" | "light") => void
```
**Description**
Switch between themes (`dark` or `light`) or set it to `auto` to follow system color scheme preference.
- **Generate new palette**
```ts
setMaterialYouColor: (seedColor: "auto" | string), style?: GenerationStyle) => void
```
**Description**
Generate a new Material You palette and set it as the current theme.
`The seed color:` It can be `"auto"` to follow the system theme if supported;
otherwise, it will generate a palette using the `fallbackColor` prop.
If a HEX color is provided, it will generate a new palette using that seed color.
`style:` - The style that dictates how the palette will be generated.
- **Change palette generation style**
```ts
setPaletteStyle: (style: generationStyle) => void;
type generationStyle = "SPRITZ" | "TONAL_SPOT" | "VIBRANT" | "EXPRESSIVE" | "RAINBOW" | "FRUIT_SALAD" | "CONTENT" | "MONOCHROMATIC"
```
**Description**
Change the palette generation style and set it as the current theme.
**Disclaimer**: If the current Material You palette is set to `"auto"` (following the system theme), a new palette will be generated using the `fallbackColor` prop.
- **Other**
```ts
palette: MaterialYouPalette;
```
**Description**
The current color palette.
```ts
seedColor: 'auto' | string;
```
**Description**
Returns the current seed color used to generate the palette.
If the palette follows the system theme, it will be `"auto"`.
```ts
style: GenerationStyle;
```
**Description**
Returns the current generation style used to generate the palette.
## Examples
Explore how to use React Native Material You Colors with these practical examples:
1. [Example: React Native App](https://github.com/alabsi91/react-native-material-you-colors/tree/main/example)
2. [Example: Expo Snack](https://snack.expo.dev/@alabsi91/react-native-material-you-colors)
> **Warning** Please be aware that retrieving the Material You color palette from Android system on `Expo` only functions in the production build.
## License
React Native Material You Colors library is licensed under [**The MIT License.**](https://github.com/alabsi91/react-native-material-you-colors/blob/main/LICENSE)
## Sponsoring
If you're integrating React Native Material You Colors in a production app and have found value in this library, consider [funding this project](https://github.com/sponsors/alabsi91). Your support helps maintain and improve the library for the community.
Feel free to [contact me](mailto:alabsi91@gmail.com) if you have any questions or would like to discuss further sponsorship options. Your support is greatly appreciated!
---
Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)