iDropper

Fork me on GitHub

About

What is iDropper?

iDropper is a color picker plugin for jQuery. It was built out of frustration from the lack of basic features in existing color pickers (mainly dimension setting). In short, iDropper is a result of real practical needs and its features were implemented with direct UI and UX designer feedbacks.

  • iDropper doesn't assumed a fixed layout or element positioning; it's so flexible that containers can be moved around and even outside of the instantiated element context and all functionality will still be intact. As mentioned above, even the dimension of iDropper can be set.
  • iDropper works across all major browsers. It even works as far back as Internet Explorer 6.
  • iDropper chains and provides proper context inside callbacks so you can write cleaner code and instatiate on multiple-element selectors return multiple elements.
  • iDropper uses the bind and trigger paradigm so you can attach multiple callbacks to a single event.
  • iDropper has exposed math functions so you can get creative with your implementation

Links

iDropper Demo

Here's a little demo of what iDropper can do. This particular instance of iDropper is tailored in such a way that the saturation/value scale is gone. It essentially means the contrast of a color is locked and the user can only change the hue of the color. Color math is done to the color we get from the drag callback and some cool CSS rules are applied from this information to give this page a completely new theme.

Add To Cart $ 9.99

Note: This is an implementation of a design from Premium Pixels which uses quite a bit of CSS magic. A bunch of color math functions are performed on-the-fly during each mousemove event which could be a huge hit on the browser. It goes without saying that you should try this demo in a modern browser like Chrome or Firefox.

Basic Usage

Instantiating

All you need to do to create an instance of iDropper is call jQuery's iDropper() prototype method on the container which you want iDropper to append to. Further, after instantiating iDropper, you can get its instance by grabbing the "iDropper" data attribute from the element you instatiated with.

var
iDropperContainer = $('#container').iDropper(),
iDropperInstance = iDropperContainer.data("iDropper");
To set the initial color, instantiate iDropper with an object and set the "color" key to a valid hex color.
var
iDropperContainer = $('#container').iDropper({
   color: "#64c7d9"
});
iDropper creates a text input field which displays the active color and allows users to also input colors. At default, this input field displays the hash symbol. You can turn this off and have iDropper only display the 6-digit hex by setting hideHash to true.
var
iDropperContainer = $('#container').iDropper({
   hideHash: true
});

Callbacks/Event Bindings

There are four iDropper events to bind to.

  • called during a mouseup after a drag and valid input keyup
  • called during a drag start
  • called at each step of a drag
  • called during a mouse up after a drag
There are two ways to bind events; by passing in callbacks during instatiation and by calling the bind method after instatiation. The benefit of binding is that you can attach callbacks after instatiation, in case you don't have that information ahead of time. Also, by using bind, you can attach multiple callbacks to a single event. These callback functions receive the iDropper instance as context, and the jQuery element that iDropper was instatiated on can be referenced through the instance's "el" key.

// Callbacks passed in during instatiation 
$('#container').iDropper({
   onChange: function(hex) { console.log(hex); },
   onStart: function(hex) { console.log(hex); },
   onDrag: function(hex) { console.log(hex); },
   onEnd: function(hex) { console.log(hex); }
});

// Binding callbacks after instatiation
var iDropperInstance = $('#container').iDropper().data("iDropper");
iDropperInstance.bind("change", function(hex) { console.log(hex); });
iDropperInstance.bind("start", function(hex) { console.log(hex); });
iDropperInstance.bind("drag", function(hex) { console.log(hex); });
iDropperInstance.bind("end", function(hex) { console.log(hex); });

// Bind method returns instance, so you can chain like so
$('#container').iDropper().data("iDropper")
   .bind("change", function(hex) { console.log(hex); })
   .bind("start", function(hex) { console.log(hex); })
   .bind("drag", function(hex) { console.log(hex); })
   .bind("end", function(hex) { console.log(hex); });

Basic Usage Demo

// This is the instatiation call that produced the demo below
var
exChange = $("#iDx-ex-usage-change"),
exStart = $("#iDx-ex-usage-start"),
exDrag = $("#iDx-ex-usage-drag"),
exEnd = $("#iDx-ex-usage-end");

$('#iDx-ex-usage').iDropper({
   color: "#64c7d9",
   onChange: function(hex) { exChange.html(hex).css("border-color", hex); },
   onStart: function(hex) { exStart.html(hex).css("border-color", hex); },
   onDrag: function(hex) { exDrag.html(hex).css("border-color", hex); },
   onEnd: function(hex) { exEnd.html(hex).css("border-color", hex); }
});

Dimension

One of the cool unique features in iDropper is that it supports setting dimension. To set the dimension of iDropper, set the "size" key when initializing with an integer. The width and height of the hue-saturation scale will be set to this value. Now, iDropper can be tailored to fit into any design you're trying to build out!

$("#iDx-ex-dim80").iDropper({
	size: 80,
	color: "#ff0000"
});
$("#iDx-ex-dim120").iDropper({
	size: 120,
	color: "#00ff00"
});
$("#iDx-ex-dim160").iDropper({
	size: 160,
	color: "#0000ff"
});

Layout

iDropper supports two layouts; bar and ring. The default is bar (shown above).
To use the ring layout, simply set "ring" on the object parameter's "layout" key. The ring layout uses the same saturation-value image as the bar layout. In order to wrap the hue ring around it, the default dimension of this layout is actually quite big; you probably want to set the dimension to be something smaller.

// This is the instatiation call that produced the demo below
var exLayout = $("#iDx-ex-layout-change");
$('#iDx-ex-usage').iDropper({
   color: "#7dd1c3",
   layout: "ring",
   size: 125,
   onDrag: function(hex) { exLayout.html(hex); }
});
"Change" callback was fired with the color:

Color math

Color Math overview

iDropper ships with color math functions that can alter the color input with the HSL-transformation. For this reason, the color input can be a HEX string OR an array that represents an HSL color. Using HEX as input is meant for functional purposes and using HSL is meant for instance purposes; this is because an HSL value is available as a function parameter inside a callback. For performance reasons, you should use HSL as input when available to reduce heavy conversions, especially during a drag event.

In iDropper, HSL is defined by an array where HSL[0] is the hue, HSL[1] is the saturation, and HSL[2] is the lightness. The HSL scale is used in favor over the HSV scale because HSL acts more independently with regards to the saturation and value domain. More information on HSL & HSV. The HSL ranges are as follows.

  • [0, 360)
  • [0, 1)
  • [0, 1)

The color math functions available in iDropper are outlined below. These functions adhere to the domain ranges outlined above; hue scale will be [0, 360), all others will be [0, 1).

  • Makes color darker by a certain percent
  • Makes color lighter by a certain percent
  • Makes color more saturate by a certain percent
  • Makes color less saturate by a certain percent
  • Shifts the hue by a certain degree
  • Shifts the hue by 180 degrees
  • Custom color transformation
changeColor takes an object with the keys "h", "s", and "l" representing the change in hue, saturation, and lightness. Further, you can set "wrap" to true if you want to wrap the value when a range limit is reached. Fox example, a color has a hue of 300 and a hue shift of 80 is performed. Without setting "wrap" will put the hue at 359 degrees, but with "wrap" set, the hue will be 20 degrees.

Color Math on a Functional level

Color math can be performed on any color and without ever instatiating iDropper by referencing them inside the $.iDropper object. If iDropper is instatiated, you can get color math functions inside a function callback simply by looking at the "this.utils" object. It's the same number of characters so you're not saving any bytes, in fact the utils object is a direct reference to $.iDropper. Using one or the other is just personal preference.

// Darkens #828e25 by 20%, returns #373d0f
$.iDropper.darken("#828e25", .2);

// Saturate #828e25 by 40%, returns #9db101
$.iDropper.saturate("#828e25", .4);

// Color: #828e25
// Hue shift 200 degrees, saturate 40%, and up lightness 20%, wrap range
// returns #801bfd
$.iDropper.changeColor("#828e25", {h: 200, s: .4, l: .2, wrap: true});

Color Math on an Instance level

Inside a callback, you can call these color math methods directly from "this", just omit the color input since the current actice color will be used. Example below.

var $id1 = $('#iDx-ex-colormath'),
    $id1Change = $('#id1_change'),
    $id1Hueshift = $('#id1_hueshift'),
    $id1Darken = $('#id1_darken'),
    $id1Lighten = $('#id1_lighten'),
    $id1Saturate = $('#id1_sat'),
    $id1Desaturate = $('#id1_desat');

$id1.iDropper({
   color: '#b4bb83',
   onDrag: function(hex) {
      var
      hue = this.changeHue(180),
      dar = this.darken(.25),
      lig = this.lighten(.25),
      sat = this.saturate(.25),
      des = this.desaturate(.25);

      $id1Change.html(hex).css({'border-color': hex});
      $id1Hueshift.html(hue).css({'border-color': hue});
      $id1Lighten.html(lig).css({'border-color': lig});
      $id1Darken.html(dar).css({'border-color': dar});
      $id1Saturate.html(sat).css({'border-color': sat});
      $id1Desaturate.html(des).css({'border-color': des});
   }
});