reactive-image-colors

Extract semantic colors (accent, light, dark) from images to build reactive, image-driven UI themes.

Installation & Usage

1. Install:

Using npm package:

        npm i reactive-image-colors

OR cloning the project on local machine:

        git clone https://github.com/codex-leo/reactive-image-colors.git

        cd reactive-image-colors
        
        npm install

2. Usage:
   • Using in simple js/ts application:

        import { extractColors } from 'reactive-image-colors';

        const colors = await extractColors('path/to/image.jpg');
        console.log(colors);

• This will log an object containing the accent, light, dark colors and palette extracted from the image.

• The output will look like this:

        {
          accent: '#ff5733',
          contrast: {
            onAccent: { text: '#000000', bg: '#ff5733'},
            onLight: { text: '#000000', bg: '#f0e68c'},
            onDark: { text: '#ffffff', bg: '#2f4f4f'}
          }
          light: '#f0e68c',
          dark: '#2f4f4f',
          palette: ['#ff5733', '#33ff57', '#3357ff', '#f0e68c', '#2f4f4f', '#8b4513'] //6 most prominent colors
        }

3. React Hook Usage:

   • You can also use the provided React hook to extract colors in a React component.

   • Hook useImageColors: This hook accepts two parameters: image source (URL or HTMLImageElement) and options. (Refer extractColors function section for available options in detailed documentation on github repository.)

    import { useImageColors } from "reactive-image-colors/react";

    export default function AlbumCard() {
    const imageUrl =
    "https://images.example.com/album-cover.jpg";

    const { colors, loading } = useImageColors(imageUrl, {
        mode: "music"
    });

    if (loading) {
     return <div>Extracting colors...</div>;
    }

    return (
        <div
        style={{
            backgroundColor: colors?.contrast.onAccent.bg,
            color: colors?.contrast.onAccent.text,
            padding: "1rem",
            borderRadius: "12px"
        }}
        >
      <h2>Album Colors</h2>

      <p>Accent: {colors?.accent}</p>
      <p>Light: {colors?.light}</p>
      <p>Dark: {colors?.dark}</p>

      <p>
        Palette: {colors?.palette?.join(", ")}
      </p>
    </div>
  );
}

• This hook returns an object containing:

    {
        colors: {
            accent: string
            contrast: {
                onAccent: { text: string, bg: string },
                onLight: { text: string, bg: string },
                onDark: { text: string, bg: string }
            }
            light: string
            dark: string
            palette: string[]
        } | null
        loading: boolean
    }

• and also have loading state to indicate if the colors are still being extracted.

4. Use To Get Background & Text Contrast Pairs:
   • The returned contrast object contains text and background color pairs for each of the extracted colors (accent, light, dark).
   • This is useful for ensuring good readability when using the extracted colors as backgrounds.
   • Example:

        const colors = await extractColors('path/to/image.jpg');

        const accentBg = colors.accent; // or colors.contrast.onAccent.bg;
        const accentText = colors.contrast.onAccent.text;

        // Now you can use accentBg as background color and accentText as text color
        console.log(`Use ${accentText} on background ${accentBg} for good contrast.`);

• Example Screenshot:

     const imgColors1 = await extractColors(image);
     const imgColors2 = await extractColors(image2);
     const imgColors3 = await extractColors(image3);
     // for each image, you can get text and background pairs like this:
     const accentText1 = imgColors1.contrast.onAccent.text;
     const accentBg1 = imgColors1.contrast.onAccent.bg;
     const accentText2 = imgColors2.contrast.onAccent.text;
     const accentBg2 = imgColors2.contrast.onAccent.bg;
     const accentText3 = imgColors3.contrast.onAccent.text;
     const accentBg3 = imgColors3.contrast.onAccent.bg;

5. That's it! You can now use reactive-image-colors to extract colors from images and create dynamic, image-driven UIs.

For detailed documentation, please refer this project's github repository: GITHUB REPOSITORY