Registry / ai-ml / react-native-image-colors

react-native-image-colors

library2.6.0jsnpmunverified

A React Native library for extracting prominent colors from images (URL, local file, base64, content URI) on iOS, Android, Expo, and web. Current stable version is v2.6.0, released roughly monthly. Wraps native palettes: Android Palette, iOS UIImageColors, web node-vibrant. Key differentiators: unified API across all platforms, built-in caching, and fallback support. Requires React Native 0.70+ and Expo SDK 47+. For older RN versions, use v1.x.

ai-ml

npm install react-native-image-colors

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-NATIVE-IMAGE

react-native-image-colors

ai-mljavascriptv2.6.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

getColors

✓ import { getColors } from 'react-native-image-colors'

✗ import ImageColors from 'react-native-image-colors'

Default export was removed in v2. Use named export getColors.

ImageColors

✓ import { ImageColors } from 'react-native-image-colors'

✗ import ImageColors from 'react-native-image-colors'

ImageColors is a named export containing getColors and other properties. Common mistake: using as default import.

ImageColorsResult

✓ import { ImageColorsResult } from 'react-native-image-colors'

TypeScript type export for the result object. Must be imported as named type.

Shows basic usage: fetch colors from a URL and display all six palette properties with caching enabled.

import React, { useEffect, useState } from 'react'; import { getColors } from 'react-native-image-colors'; const App = () => { const [colors, setColors] = useState<ImageColorsResult | null>(null); useEffect(() => { const url = 'https://i.imgur.com/68jyjZT.jpg'; getColors(url, { fallback: '#228B22', cache: true, key: url, }).then(result => { setColors(result); }).catch(err => { console.error(err); }); }, []); return ( <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}> {colors && ( <Text> Vibrant: {colors.vibrant} {'\n'} Dark Vibrant: {colors.darkVibrant} {'\n'} Light Vibrant: {colors.lightVibrant} {'\n'} Muted: {colors.muted} {'\n'} Dark Muted: {colors.darkMuted} {'\n'} Light Muted: {colors.lightMuted} </Text> )} </View> ); };

Debug

Known issues

breakingIn v2, default export was removed. The API changed from `ImageColors.getColors()` to a named `getColors()` function. Also `ImageColors` namespace is no longer the default.

fix

Replace `import ImageColors from 'react-native-image-colors'` with `import { getColors } from 'react-native-image-colors'`.

affects: >=2.0.0

gotchaOn Android, the `getColors` function can throw an error if the image cannot be decoded (e.g., unsupported format or corrupted file). Always wrap in try/catch or use `.catch()`.

fix

Use `getColors(url, config).then().catch(err => console.warn(err))` or try-catch with async/await.

affects: >=2.0.0

deprecatedIn v2, the old `quality` config option is no longer supported. Use `fallback` and `cache` instead.

fix

Remove any `quality` property from the config object.

affects: >=2.0.0

gotchaThe `key` option in config is required if `cache` is true, else an error is thrown.

fix

Always provide a unique `key` string when setting `cache: true`.

affects: >=2.0.0

gotchaOn web, the library uses node-vibrant which may have different color results compared to native platforms. Note that web support is experimental.

fix

Test across platforms; if web results differ, consider platform-specific handling.

affects: >=2.0.0

breakingReact Native 0.69 and below are not supported in v2. Use v1.x instead.

fix

Either upgrade React Native to 0.70+ or install react-native-image-colors@1.x.

affects: >=2.0.0

gotchaOn iOS, the `getColors` function may returns null for some color properties (e.g., darkVibrant, darkMuted) if not available. Use fallback to avoid undefined.

fix

Provide a fallback color in the config and use optional chaining or nullish coalescing when accessing properties.

affects: >=2.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'vibrant')

The `getColors` promise resolved but result might be null; or you are accessing a property before it's set.

fix

Ensure you handle the result state correctly: `setColors(result)` and only render after `colors` is not null.

requireNativeComponent: "RNImageColors" was not found in the UIManager.

Native module not linked properly, or you haven't run `expo prebuild` (Expo) or `npx pod-install` (iOS) after installation.

fix

For Expo: run `npx expo prebuild`. For React Native CLI: ensure native modules are installed and reinstall pods: `cd ios && pod install && cd ..`.

Error: ImageColors: cache is true but no key provided

You set `cache: true` in config but omitted the `key` property.

fix

Add a unique `key` string in config, e.g., `{ cache: true, key: url }`.

Unhandled Promise Rejection: RuntimeError: Aborted(CompileError: WebAssembly.instantiate():...

WebAssembly (used by node-vibrant on web) might not be supported or blocked by Content Security Policy.

fix

Ensure WebAssembly is allowed or use fallback. See web documentation.

PlatformNotSupportedError: ImageColors.getColors is not available on this platform

Trying to use the library on an unsupported platform (e.g., Windows, macOS desktop without proper setup).

fix

Check platform compatibility; only iOS, Android, and web are supported.

Upgrade

Version history

2.6.0latest on npm

Audit

Dependencies

exporequiredPeer dependency required for Expo and React Native CLI setups (expo modules must be installed)

reactrequiredCore peer dependency

react-nativerequiredCore peer dependency

Agent activity

12 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/osamaqarem/react-native-image-colors ↗

packagereact-native-image-colors ↗

homepagehttps://github.com/osamaqarem/react-native-image-colors#readme ↗