Chameleon.js 🦎

Easy get and use colors from image!Vadim Fedorov

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Chameleon.js is a jQuery plugin for automatic content colorization.
jQuerynpm version

Features:

  1. Colorize the content with image;
  2. Get colors from an image;
  3. Wrap the color in the jQuery element.

Alternative:

Installation

Download directly from GitHub or install via npm Bower.

Include jQuery and the plugin:
<script src="path/to/jquery.js"></script>
<script src="path/to/jquery.chameleon.js"></script>

Or add Chameleon.js to jQuery:
import $ from 'jquery';
import addChameleonJsToJquery from 'jquery.chameleon.js/addChameleonJsToJquery';

addChameleonJsToJquery($);

Run the plugin:
$(document).ready(function() {
    $('.chmln').chameleon();
});

Optional

If you need debug, include it:
<script src="path/to/chameleonDebug.js"></script>
With addChameleonJsToJquery($) debug included automatically.

Enable debug:
$(document).ready(function() {
    $('.chmln').chameleon({
        debug: true
    });
});

If you need colorization modes, include it:
<script src="path/to/colorization/mode.js"></script>
With addChameleonJsToJquery($) modes included automatically.

Use modes:
$(document).ready(function() {
    $('.chmln').chameleon({
        colorize_mode: {
            name: "blur",
            config: {}
          }
    });
});

If you need styles for color elements, include it:
<link rel="stylesheet" href="path/to/chmln__colors.css">

Or import:
import 'jquery.chameleon.js/css/chmln__colors.css';

Usage

1. $.fn.chameleon("colorize")

With method colorize, you can automatically color any content using the image.
This method is used by default.

Parameters:

NameDefaultDescription
content_prefix
"chmln"
Content class prefix.
color_format
"hex"
The format of color that is used in color element.

Allowed values: hex, rgb, rgba.
color_alpha
200
The minimum permissible value of the alpha channel of color

Min: 0, max: 255.
color_difference
120
The minimum allowed difference in colors. For example, if we compare colors: rgb(0, 0, 0) and rgb(255, 255, 255), then "color_difference" of them is 765. Math.abs(0 - 255 + 0 - 255 + 0 - 255) = 765.

Min: 50, max: 765.
color_adapt_limit
200
The number of iterations of color adaptation to the background.

Min: 1, max: 1000.
canvas_side
400
The maximum possible size of the canvas side (px). If the image dimensions are larger, it will be adapted to the canvas dimensions. The smaller canvas is processed more quickly, but the number of extracted colors of course is reduced, because the resolution of the image is reduced.

Min: 50, max: 10000.
colors_skip
0
Number of colors that will be skipped during extraction.

Min: 0, max: 1000.
Can be empty.
debug
false
Output to the console possible errors, warnings and the like.
async_colorize
false
Use asynchronous colorizing mode.
apply_colors
true
Apply the found colors to the elements.
adapt_colors
true
Adapt the colors of .chmln{n} elements for the color of the background.
all_colors
false
Return all found colors, not only those that were used for colorizing.
insert_colors
false
Insert the found colors in the html-markup of .chmln element.
data_colors
false
Store the colors in the "data-colors" attribute of the .chmln element.
dummy_back
"#ffffff"
The color that is used if the background color is missing.

A string (hex, rgb or rgba), an object, or an array.
dummy_front
"#000000"
The color that is used if the color for .chmln{n} element is missing.

A string (hex, rgb or rgba), an object, or an array.
content
{
  "root": "body",
  "items": []
}
Description of the content to be created.
rules
{
  "container": {
    "prop": "background-color"
  },
  "element": {
    "prop": "color"
  }
}
Rules for colorize content. Properties "container" and "element" are for .chmln container and .chmln{n} elements.
colorize_mode
{
  "name": "basic",
  "config": {}
}
The colorizing mode config.
afterColorized
function(c, s) {}
The function that is called after the colors are taken from the image.
beforeAsyncColorized
function(s) {}
The function that is called before asynchronous colorizing is started.
afterAsyncColorized
function(s) {}
The function that is called after asynchronous colorizing is finished.

Examples:

1.1. Basic usage

Just colorizing the content.

HTML
<div class="chmln">
  <h1 class="chmln1">Chameleon.js</h2>
  <blockquote class="chmln2">
    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    <cite class="chmln3">
      Lorem ipsum.
    </cite>
  </blockquote>
  <p class="chmln4">
    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
  </p>
  <img class="chmln__img" src="/img/src/bundles/template/page/lab/chameleon-js/img/chmln-img.png" alt="Chameleon Image">
</div>

JS
jQuery("#example1-1 .chmln").chameleon();

1.2. Colors skip

If you want to skip some number of extracted colors.

HTML
<div class="chmln">
  <h1 class="chmln1">Chameleon.js</h2>
  <blockquote class="chmln2">
    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    <cite class="chmln3">
      Lorem ipsum.
    </cite>
  </blockquote>
  <p class="chmln4">
    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
  </p>
  <img class="chmln__img" src="/img/src/bundles/template/page/lab/chameleon-js/img/chmln-img.png" alt="Chameleon Image">
  <div class="chmln__colors"></div>
</div>

JS
jQuery("#example1-2 .chmln").chameleon({
  "colors_skip": 6,
  "color_difference": 50,
  "insert_colors": true
});

1.3. Async colorization

Colorizing several elements in asynchronous mode, which allows not to block the interface.

HTML
<div>
  <div class="chmln">
    <img class="chmln__img" src="/img/src/bundles/template/page/lab/chameleon-js/img/chmln-img.png" alt="Chameleon Image">
  </div>
  <div class="chmln">
    <img class="chmln__img" src="/img/src/bundles/template/page/lab/chameleon-js/img/chmln-img-1.png" alt="Chameleon Image">
  </div>
  <div class="chmln">
    <img class="chmln__img" src="/img/src/bundles/template/page/lab/chameleon-js/img/chmln-img-2.png" alt="Chameleon Image">
  </div>
  <div class="chmln">
    <img class="chmln__img" src="/img/src/bundles/template/page/lab/chameleon-js/img/chmln-img-3.png" alt="Chameleon Image">
  </div>
  <div class="chmln">
    <img class="chmln__img" src="/img/src/bundles/template/page/lab/chameleon-js/img/chmln-img-4.png" alt="Chameleon Image">
  </div>
</div>

JS
jQuery("#example1-3 .chmln").chameleon({
  "async_colorize": true
});

1.4. Callbacks

Add callbacks to colorize process.

HTML
<div>
  <div class="chmln">
    <img class="chmln__img" src="/img/src/bundles/template/page/lab/chameleon-js/img/chmln-img.png" alt="Chameleon Image">
  </div>
  <div class="chmln">
    <img class="chmln__img" src="/img/src/bundles/template/page/lab/chameleon-js/img/chmln-img-1.png" alt="Chameleon Image">
  </div>
  <div class="chmln">
    <img class="chmln__img" src="/img/src/bundles/template/page/lab/chameleon-js/img/chmln-img-2.png" alt="Chameleon Image">
  </div>
  <div class="chmln">
    <img class="chmln__img" src="/img/src/bundles/template/page/lab/chameleon-js/img/chmln-img-3.png" alt="Chameleon Image">
  </div>
  <div class="chmln">
    <img class="chmln__img" src="/img/src/bundles/template/page/lab/chameleon-js/img/chmln-img-4.png" alt="Chameleon Image">
  </div>
</div>

JS
jQuery("#example1-4 .chmln").chameleon({
  "async_colorize": true,
  "afterColorized": function (colors, s) {
    s.$img
      .closest('.chmln')
      .addClass('_done');
  },
  "beforeAsyncColorized": function () {
    jQuery('#example1-4 .chmlnDemo')
      .removeClass('_done')
      .addClass('_colorizing');
  },
  "afterAsyncColorized": function () {
    jQuery('#example1-4 .chmlnDemo')
      .removeClass('_colorizing')
      .addClass('_done');
  }
});

1.5. Rules

With "rules" you can arrange colorizing in a way that you want.

HTML
<div class="chmln">
  <h1 class="chmln1">Chameleon.js</h2>
  <blockquote class="chmln2">
    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    <cite class="chmln3">
      Lorem ipsum.
    </cite>
  </blockquote>
  <p class="chmln4 _last-p">
    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
  </p>
  <img class="chmln__img" src="/img/src/bundles/template/page/lab/chameleon-js/img/chmln-img.png" alt="Chameleon Image">
</div>

JS
jQuery("#example1-5 .chmln").chameleon({
  "rules": {
    "container": function($elem, color, color_index, img_colors, is_decolorize) {
      $elem.css({
        'background': 'linear-gradient(110deg, ' + color.rgb + ' 60%,' + color.adjustLum(.2).rgb + ' 60%)',
        'box-shadow': '0 3px 25px ' + color.rgb
      });
    },
    "element": {
      "prop": "color"
    },
    "h1": function($elem, color, color_index, img_colors, is_decolorize) {
      $elem.css({
        'color': color.rgb,
        'text-shadow': '2px 3px 4px ' + color.adjustLum(-.8).setAlpha(0.8).rgba
      });
    },
    "blockquote": [
      { "prop": "color" },
      { "prop": "border-color" }
    ],
    "._last-p": function($elem, color, color_index, img_colors, is_decolorize) {
      $elem.css({'text-shadow': '1px 1px ' + color.adjustLum(-.8).setAlpha(0.8).rgba});
    }
  }
});

1.6. Colorization mode

Colorization mode is a pre-programmed template, which is essentially an extension for the plugin. To add a mode, you need to register it using the registerColorizeMode method. You can use different modes at the same time. For example, I created a "blur" mode that adds a blurry image to the background of the content.

HTML
<div class="chmln">
  <h1 class="chmln1">Chameleon.js</h2>
  <blockquote class="chmln2">
    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    <cite class="chmln3">
      Lorem ipsum.
    </cite>
  </blockquote>
  <p class="chmln4 _last-p">
    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
  </p>
  <img class="chmln__img" src="/img/src/bundles/template/page/lab/chameleon-js/img/chmln-img.png" alt="Chameleon Image">
</div>

JS
jQuery("#example1-6 .chmln").chameleon({
  "colorize_mode": {
    "name": "blur",
    "config": {
      "img_css": "bottom: -25%; right: -25%; width: 90%; opacity: .5;",
      "blur_val": 10,
      "overflow_hidden": true,
      "modify_position": true
    }
  }
});

1.7. Content

You can use the prepared data for colorizing, use the "content" field for this.

JS
jQuery.fn.chameleon({
  "content": {
    "root": "#example1-7 .CodeExamples__exampleResult",
    "items": [
      {
        "container": {
          "tag": "div",
        },
        "elements": [
          {
            "tag": "div",
            "ignore": true,
            "children": [
              {
                "tag": "div",
                "ignore": true,
                "children": [
                  {
                    "tag": "h1",
                    "class": "chmln__title",
                    "content": "Chameleon.js"
                  },
                  {
                    "tag": "blockquote",
                    "class": "chmln__blockquote",
                    "content": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
                    "children": [
                      {
                        "tag": "cite",
                        "class": "chmln__cite",
                        "content": "Lorem ipsum."
                      }
                    ]
                  },
                  {
                    "tag": "p",
                    "class": "chmln__paragraph",
                    "content": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."
                  }
                ]
              },
              {
                "tag": "div",
                "ignore": true,
                "children": [
                  {
                    "tag": "img",
                    "main_img": true,
                    "src": "/img/src/bundles/template/page/lab/chameleon-js/img/chmln-img.png"
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
});

2. $.fn.chameleon("getImageColors")

With method getImageColors, you can easily get and use colors from any image that is available to you.

Parameters:

NameDefaultDescription
sort_type
"disabled"
Sorting colors.

Allowed values: disabled, hue, sat, val, chroma, alpha.
color_format
"hex"
The format of color that is used in color element.

Allowed values: hex, rgb, rgba.
img_src
""
The url of the image from which the colors will be extracted, if possible.

Can be empty.
color_alpha
200
The minimum permissible value of the alpha channel of color.

Min: 0, max: 255.
color_difference
120
The minimum allowed difference in colors. For example, if we compare colors: rgb(0, 0, 0) and rgb(255, 255, 255), then "color_difference" of them is 765. Math.abs(0 - 255 + 0 - 255 + 0 - 255) = 765.

Min: 50, max: 765.
canvas_side
400
The maximum possible size of the canvas side (px). If the image dimensions are larger, it will be adapted to the canvas dimensions. The smaller canvas is processed more quickly, but the number of extracted colors of course is reduced, because the resolution of the image is reduced.

Min: 50, max: 10000.
debug
false
Output to the console possible errors, warnings and the like.
onGetColorsSuccess
function(c, $c, s) {}
The function that is called after the colors are taken from the image.
onGetColorsError
function(c, e, $c, s, is) {}
The function that is called if an error occurred while loading the image.

Examples:

2.1. Basic usage

Get image colors.

HTML
<div>
  <div class="chmln">
    <img class="chmln__img" src="/img/src/bundles/template/page/lab/chameleon-js/img/chmln-img.png" alt="Chameleon Image">
  </div>
  <div class="chmln">
    <img class="chmln__img" src="/img/src/bundles/template/page/lab/chameleon-js/img/chmln-img-1.png" alt="Chameleon Image">
  </div>
  <div class="chmln">
    <img class="chmln__img" src="/img/src/bundles/template/page/lab/chameleon-js/img/chmln-img-2.png" alt="Chameleon Image">
  </div>
  <div class="chmln">
    <img class="chmln__img" src="/img/src/bundles/template/page/lab/chameleon-js/img/chmln-img-3.png" alt="Chameleon Image">
  </div>
  <div class="chmln">
    <img class="chmln__img" src="/img/src/bundles/template/page/lab/chameleon-js/img/chmln-img-4.png" alt="Chameleon Image">
  </div>
  <div>
    <strong>Colors:</strong>
    <div class="chmlnDemo__colors"></div>
  </div>
</div>

JS
jQuery('#example2-1').on('click', '.chmln', function(e) {
  const $currentTarget = jQuery(e.currentTarget);

  if ($currentTarget.hasClass('_done')) {
    return;
  }

  $currentTarget
    .addClass('_colorizing')
    .find('img')
    .chameleon("getImageColors", {
      "sort_type": "disabled",
      "color_format": "hex",
      "img_src": "",
      "color_alpha": 200,
      "color_difference": 120,
      "canvas_side": 300,
      "debug": false,
      "onGetColorsSuccess": function(colors, $container, s) {
        const $colors = jQuery.fn.chameleon('wrapColor', colors, s.color_format);

        jQuery('#example2-1 .chmlnDemo__colors').html($colors);
        $container
          .removeClass('_colorizing')
          .addClass('_done')
          .siblings()
          .removeClass('_done');
      },
      "onGetColorsError": function(colors, err, $container, s, img_src) {
        console.error(err, img_src);
        $container
          .removeClass('_colorizing')
          .addClass('_err');
      }
    });
});

jQuery('#example2-1 .chmln')
  .first()
  .click();

3. $.fn.chameleon("wrapColor")

Use method wrapColor to get a jQuery element for colors.

Parameters:

NameDefaultDescription
color_format
"hex"
The format of color that is used in color element.

Allowed values: hex, rgb, rgba.
wrap_color_mode
"tile"
The mode of wrapping a color in an element.

Allowed values: tile, text.
wrap_arrow_mode
"arrow"
The mode of arrow in the color element.

Allowed values: arrow, gradient.
Value "gradient" working only if "wrap_color_mode" is "tile".
color_html
""
The color element inner html.

Can be empty.
source_color_html
""
The source color element inner html.

Can be empty.
color
"#000000"
The color.

A string (hex, rgb or rgba), an object, or an array.
source_color
""
The color, that will be used as the color from which the "color" was obtained.

A string (hex, rgb or rgba), an object, or an array.
Can be empty.
debug
false
Output to the console possible errors, warnings and the like.

Examples:

3.1. Basic usage

Wrap color.

JS
const $color = jQuery.fn.chameleon("wrapColor", "000");
const $colorText = jQuery.fn.chameleon("wrapColor", {
  "color": "#ffff00",
  "color_html": "yellow (::color::)",
  "wrap_color_mode": "text"
});
const $colorRgba = jQuery.fn.chameleon("wrapColor", "rgba(139, 195, 74, .5)", "rgba");
const $arrayColors = jQuery.fn.chameleon("wrapColor", [
  "rgb(139, 195, 74)",
  {
    "color": "rgb(64, 224, 208)",
    "source_color": "rgb(220, 20, 60)",
    "color_html": "Turquoise",
    "source_color_html": "Crimson"
  },
  {
    "color": "40e0d0",
    "source_color": "rgb(220, 20, 60)",
    "color_format": "rgb",
    "wrap_arrow_mode": "gradient"
  }
], "hex");

jQuery('#example3-1 .CodeExamples__exampleResult')
    .append($color)
    .append($colorText)
    .append($colorRgba)
    .append($arrayColors);