react-native-material-palette

Android Palette API brought to react native. It extracts prominent colors from images to help you create visually engaging apps.

The library only supports Android and requires new architecture to work.

Installation

npm install react-native-material-palette

Usage

createPalette

Extract prominent color swatches from an image:

import { createPalette } from 'react-native-material-palette';

const palette = await createPalette({ uri: 'https://example.com/photo.jpg' });

Or with local image:

const palette = await createPalette(require('./photo.jpg'));

The returned PaletteResult has the following properties, each of which is a PaletteSwatch or undefined:

Property	Description
vibrant	A vibrant color from the image
lightVibrant	A light and vibrant color
darkVibrant	A dark and vibrant color
muted	A muted color from the image
lightMuted	A light and muted color
darkMuted	A dark and muted color

Each PaletteSwatch has the following properties:

Property	Type	Description
color	string	The main color of the swatch (hex format)
population	number	The number of pixels represented by this swatch
bodyTextColor	string	A color suitable for body text over the swatch color
titleTextColor	string	A color suitable for title text over the swatch color

Options

region

Specifies a rectangular area of the image to use for palette generation. Coordinates are in pixels.

const palette = await createPalette(
  { uri: 'https://example.com/photo.jpg' },
  {
    region: {
      left: 0,
      top: 0,
      right: 100,
      bottom: 100,
    },
  }
);

maximumColorCount

Maximum colors in the palette. The default value is 16, and the optimal value depends on the source image. For landscapes, optimal values range from 8-16, while pictures with faces usually have values from 24-32.

createPaletteForTarget

Extract a single swatch using a custom target for fine-grained control over color matching:

import { createPaletteForTarget } from 'react-native-material-palette';

const swatch = await createPaletteForTarget(
  { uri: 'https://example.com/photo.jpg' },
  {
    targetLightness: 0.5,
    minimumLightness: 0.2,
    maximumLightness: 0.8,
    targetSaturation: 0.7,
    minimumSaturation: 0.3,
    maximumSaturation: 1.0,
    lightnessWeight: 0.6,
    saturationWeight: 0.3,
    populationWeight: 0.1,
    exclusive: true,
  }
);

It accepts the same region and maximumColorCount options as createPalette in an optional third argument.

usePaletteSwatch

A hook for using palette colors in components. It extracts a single swatch based on the type option:

import { usePaletteSwatch } from 'react-native-material-palette';

function MyComponent() {
  const swatch = usePaletteSwatch(
    { uri: 'https://example.com/photo.jpg' },
    { type: 'vibrant' }
  );

  return (
    <View style={{ backgroundColor: swatch?.color ?? 'white' }}>
      <Text style={{ color: swatch?.bodyTextColor ?? 'black' }}>Hello</Text>
    </View>
  );
}

The type option can be one of the 6 built-in targets ('vibrant', 'lightVibrant', 'darkVibrant', 'muted', 'lightMuted', 'darkMuted') or a custom target object.

Returns undefined while loading or if generation fails.

Tip

To avoid delays due to async palette generation, you can preload the palette by calling createPalette with the same image and options ahead of time.

Palette.View

A component that uses a palette swatch color as its background:

import { Palette } from 'react-native-material-palette';

function MyComponent() {
  return (
    <Palette.View
      source={{ uri: 'https://example.com/photo.jpg' }}
      type="vibrant"
    >
      {/* your content */}
    </Palette.View>
  );
}

It accepts the same options as usePaletteSwatch and an optional fallback prop with a PaletteSwatch to use while loading or if generation fails.

By default, it uses the color property of the swatch as its background color. You can customize which swatch color to use with the variant prop:

• color (default) — main swatch color
• titleTextColor — title text color
• bodyTextColor — body text color

It renders a regular View when not used on Android.

Palette.Text

A component that uses palette swatch colors for text:

import { Palette } from 'react-native-material-palette';

function MyComponent() {
  return (
    <Palette.Text
      source={{ uri: 'https://example.com/photo.jpg' }}
      type="vibrant"
    >
      Hello, World!
    </Palette.Text>
  );
}

By default, it uses the bodyTextColor property of the swatch as its text color. You can customize which swatch color to use with the variant prop:

• color — main swatch color
• titleTextColor — title text color
• bodyTextColor (default) — body text color

When nested inside Palette.View, it automatically uses the swatch from the parent without needing to provide source and type props:

import { Palette } from 'react-native-material-palette';

function MyComponent() {
  return (
    <Palette.View
      source={{ uri: 'https://example.com/photo.jpg' }}
      type="vibrant"
    >
      <Palette.Text>Hello, World!</Palette.Text>
    </Palette.View>
  );
}

The source and type props can still be provided explicitly to override the parent swatch.

It renders a regular Text when not used on Android.

Contributing

• Development workflow
• Sending a pull request
• Code of conduct

License

MIT

---

Made with create-react-native-library