jPicker - A jQuery Color Picker Plugin.

jPicker is a fast, lightweight jQuery plugin for including an advanced color picker in your web projects. It has been painstakenly ported from John Dyers' awesome work on his picker using the Prototype framework.

jPicker supports all current browsers and has been extensively tested in Chrome, Firefox, IE5.5+, Safari, and Opera.

If you are updating a current version, you MUST always use the CSS and image files from the download as there may have been changes.

If you are moving from a V1.0.* version, you MUST read the docs below to implement some changes to the Color object returned by the callback functions.

View John Dyer's prototype plugin here.

View jPicker details a docs below.

Check out the source from Google Code.


jPicker Inline Example

jPicker can be used inline by binding to any block level element.

jPicker() -- no arguments 

<script type="text/javascript">        
  $(document).ready(
    function()
    {
      $('#Inline').jPicker();
    });
</script>
<div id="Inline"></div>


jPicker Expandable Example

jPicker can also display only a small picker icon that opens a popup for editing.

jPicker({ window: { expandable: true }}) 

<script type="text/javascript">
  $(document).ready(
    function()
    {
      $('#Expandable').jPicker(
        {
          window:
          {
            expandable: true
          }
        });
    });
</script>
<span id="Expandable"></span>


jPicker Alpha Channel Example

jPicker can also pick colors with alpha (transparency) values.

jPicker({ window: { expandable: true }}) 

<script type="text/javascript">        
  $(document).ready(
    function()
    {
      $('#Alpha').jPicker(
        {
          window:
          {
            expandable: true
          },
          color:
          {
            alphaSupport: true,
            active: new $.jPicker.Color({ ahex: '99330099' })
          }
        });
    });
</script>
<span id="Alpha"></span>


jPicker Binded Example

jPicker can also be binded to an input element.

jPicker() -- no arguments 

<script type="text/javascript">        
  $(document).ready(
    function()
    {
      $('#Binded').jPicker();
    });
</script>
<input id="Binded" type="text" value="e2ddcf" />


Multiple jPicker Binded Example

jPicker can also be binded to multiple elements at a time.

jPicker() -- no arguments 

<script type="text/javascript">        
  $(document).ready(
    function()
    {
      $('.Multiple').jPicker();
    });
</script>
<input class="Multiple" type="text" value="e2ddcf" /><br />
<input class="Multiple" type="text" value="" /><br />
<input class="Multiple" type="text" value="fda0f7" />




jPicker Callback Functions

Register for callback function to have it interact with your page.

jPicker([settings, [commitCallback, [liveCallback, [cancelCallback]]]]) 

<script type="text/javascript">
  $(document).ready(
    function()
    {
      var LiveCallbackElement = $('#Live'),
          LiveCallbackButton = $('#LiveButton');  // you don't want it searching this
                                                  // on every live callback!!!
      $('#Callbacks').jPicker(
        {},
        function(color, context)
        {
          var all = color.val('all');
          alert('Color chosen - hex: ' + (all && '#' + all.hex || 'none') +
            ' - alpha: ' + (all && all.a + '%' || 'none'));
          $('#Commit').css(
            {
              backgroundColor: all && '#' + all.hex || 'transparent'
            }); // prevent IE from throwing exception if hex is empty
        },
        function(color, context)
        {
          if (context == LiveCallbackButton.get(0)) alert('Color set from button');
          var hex = color.val('hex');
          LiveCallbackElement.css(
            {
              backgroundColor: hex && '#' + hex || 'transparent'
            }); // prevent IE from throwing exception if hex is empty
        },
        function(color, context)
        {
          alert('"Cancel" Button Clicked');
        });      
      $('#LiveButton').click(
        function()
        {
          $.jPicker.List[0].color.active.val('hex', 'e2ddcf', this);
        });
    });
</script>
<input id="Callbacks" type="text" value="e2ddcf" />
<span id="Commit" style="background-color: #e2ddcf; display: block; --
          float: left; height: 50px; margin: 10px; width: 50px;"> --
          Commit</span>
<span id="Live" style="display: block; float: left; height: 50px; --
          margin: 10px; width: 50px;">Live</span>
<input id="LiveButton" type="button" value="Set To #e2ddcf" />

Commit Live


jPicker Settings And Colors

Use the "val" method on the active color for interaction with the picker.

(jQuery).jPicker.List[index] 

<script type="text/javascript">        
  $(document).ready(
    function()
    {
      $('#AlterColors').jPicker();
      $('#GetActiveColor').click(
        function()
        {
          alert($.jPicker.List[0].color.active.val('ahex'));
        });
      $('#GetRG').click(
        function()
        {
          var rg=$.jPicker.List[0].color.active.val('rg');
          alert('red: ' + rg.r + ', green: ' + rg.g);
        });
      $('#SetHue').click(
        function()
        {
          $.jPicker.List[0].color.active.val('h', 133);
        });
      $('#SetValue').click(
        function()
        {
          $.jPicker.List[0].color.active.val('v', 38);
        });
      $('#SetRG').click(
        function()
        {
          $.jPicker.List[0].color.active.val('rg', { r: 213, g: 118 });
        });
    });
</script>
<input id="AlterColors" type="text" value="e2ddcf" /><br />
<input id="GetActiveColor" type="button" value="Get Active Color" /><br />
<input id="GetRG" type="button" value="Get Red/Green Value" /><br />
<input id="SetHue" type="button" value="Set Hue To 133" /><br />
<input id="SetValue" type="button" value="Set Value To 38" /><br />
<input id="SetRG" type="button" value="Set Red/Green To 213, 118" />






jPicker Core

jPicker Core function - returns the jQuery object.

jPicker([settings, [commitCallback, [liveCallback, [cancelCallback]]]])


Settings

settings [object]: (with defaults)

{
  window: // used to define the position of the popup window
          // only useful in binded mode
  {
    title: null, // any title for the jPicker window itself - displays
                 // "Drag Markers To Pick A Color" if left null
    position:
    {
      x: 'screenCenter', // acceptable values "left", "center", "right",
                         // "screenCenter", or relative px value
      y: 'top', // acceptable values "top", "bottom", "center", or relative px
                // value
    },
    expandable: false, // default to large static picker - set to true to make an
                       // expandable picker (small icon with popup) - set
                       // automatically when binded to input element
    liveUpdate: true, // set false if you want the user to click "OK" before the
                      // binded input box updates values (always "true" for
                      // expandable picker)
    alphaSupport: false, // set to true to enable alpha picking
    alphaPrecision: 0, // set decimal precision for alpha percentage display -
                       // hex codes do not map directly to percentage integers -
                       // range 0-2
    updateInputColor: true // set to false to prevent binded input colors from
                           // changing
  },
  color:
  {
    mode: 'h', // acceptable values "h" (hue), "s" (saturation), "v" (brightness),
               // "r" (red), "g" (green), "b" (blue), "a" (alpha)
    active: new $.jPicker.Color({ hex: 'ffc000' }), // accepts any declared
               // jPicker.Color object or hex string WITH OR WITHOUT '#'
    quickList: // this list of quick pick colors - override for a different list
      [
        new $.jPicker.Color({ h: 360, s: 33, v: 100}), // accepts any declared
               // jPicker.Color object or hex string WITH OR WITHOUT '#'
        new $.jPicker.Color({ h: 360, s: 66, v: 100}),
        (...) // removed for brevity
        new $.jPicker.Color({ h: 330, s: 100, v: 50}),
        new $.jPicker.Color()
      ]
  },
  images
  {
    clientPath: '/jPicker/images/', // Path to image files
    colorMap: // colorMap size and arrow icon
    {
      width: 256, // Map width - don't override unless using a smaller image set
      height: 256, // Map height - don't override unles using a smaller image set
      arrow:
      {
        file: 'mappoint.gif', // Arrow icon image file
        width: 15, // Arrow icon width
        height: 15 // Arrow icon height
      }
    },
    colorBar: // colorBar size and arrow icon
    {
      width: 20, // Bar width - don't override unless using a smaller image set
      height: 256, // Bar height - don't override unless using a smaller image set
      arrow:
      {
        file: 'rangearrows.gif', // Arrow icon image file
        width: 40, // Arrow icon width
        height: 9 // Arrow icon height
      }
    },
    picker: // picker icon and size
    {
      file: 'picker.gif', // Picker icon image file
      width: 25, // Picker width - don't override unless using a smaller image set
      height: 24 // Picker height - don't override unless using a smaller image set
    }
  },
  localization:
  {
    text:
    {
      title: 'Drag Markers To Pick A Color',
      newColor: 'new',
      currentColor: 'current',
      ok: 'OK',
      cancel: 'Cancel'
    },
    tooltips:
    {
      colors:
      {
        newColor: 'New Color - Press “OK” To Commit',
        currentColor: 'Click To Revert To Original Color'
      },
      buttons:
      {
        ok: 'Commit To This Color Selection',
        cancel: 'Cancel And Revert To Original Color'
      },
      hue:
      {
        radio: 'Set To “Hue” Color Mode',
        textbox: 'Enter A “Hue” Value (0-360°)'
      },
      saturation:
      {
        radio: 'Set To “Saturation” Color Mode',
        textbox: 'Enter A “Saturation” Value (0-100%)'
      },
      brightness:
      {
        radio: 'Set To “Brightness” Color Mode',
        textbox: 'Enter A “Brightness” Value (0-100%)'
      },
      red:
      {
        radio: 'Set To “Red” Color Mode',
        textbox: 'Enter A “Red” Value (0-255)'
      },
      green:
      {
        radio: 'Set To “Green” Color Mode',
        textbox: 'Enter A “Green” Value (0-255)'
      },
      blue:
      {
        radio: 'Set To “Blue” Color Mode',
        textbox: 'Enter A “Blue” Value (0-255)'
      },
      alpha:
      {
        radio: 'Set To “Alpha” Color Mode',
        textbox: 'Enter A “Alpha” Value (0-100)'
      },
      hex:
      {
        textbox: 'Enter A “Hex” Color Value (#000000-#ffffff)',
        alpha: 'Enter A “Alpha” Value (#00-#ff)'
      }
    }
  }
}


Callback Pattern

function(jPicker.Color color, object context){...}


jPicker List

The list of active jPicker objects.

(jQuery).jPicker.List[]


jPicker Color Class

Definition of the jPicker.Color class.

(jQuery).jPicker.Color()
(jQuery).jPicker.Color({ ahex: 'ffffffff' })
(jQuery).jPicker.Color({ hex: 'ffffff', [a: (0-255)] })
(jQuery).jPicker.Color({ r: (0-255), g: (0-255), b: (0-255), [a: (0-255)] })
(jQuery).jPicker.Color({ h: (0-360), s: (0-100), v: (0-100), [a: (0-255)] })
{
  val: function(name, value, context),
  bind: function(callback) where callback is function(color, [context]),
  unbind: function(callback)
}

method "val" usage

val(name) : get value

  'r':     red         (0-255)
  'g':     green       (0-255)
  'b':     blue        (0-255)
  'a':     alpha       (0-255)
  'h':     hue         (0-360)
  's':     saturation  (0-100)
  'v':     value       (0-100)
  'hex':   hex         (000000-ffffff)
  'ahex':  ahex        (00000000-ffffffff)
  'all':   all         all
  
  ex. Usage

    val('r'):     (0-255)
    val('h'):     (0-360)
    val('hex'):   (000000-ffffff)
    val('rg'):    { r: (0-255), g: (0-255) }
    val('rgba'):  { r: (0-255), g: (0-255), b: (0-255), a: (0-255) }
    val('hvga'):  { h: (0-255), v: (0-100), g: (0-255), a: (0-255) }
    val('all'):   { r: (0-255), g: (0-255), b: (0-255), a: (0-255), h: (0-360) --
                    s: (0-100), v: (0-100), hex: (000000-ffffff), --
                    ahex: (00000000-ffffffff) }

val(name, value, [context]) : set value

  'r':     red         (0-255)
  'g':     green       (0-255)
  'b':     blue        (0-255)
  'a':     alpha       (0-255)
  'h':     hue         (0-360)
  's':     saturation  (0-100)
  'v':     value       (0-100)
  'hex':   hex         (000000-ffffff)
  'ahex':  ahex        (00000000-ffffffff)
  
  ex. Usage

    val('r', (0-255)) || val('r', { r: (0-255) })
    val('h', (0-360)) || val('h', { h: (0-360) })
    val('hex', (000000-ffffff)) || val('hex', { hex: (000000-ffffff) })
    val('rg', { r: (0-255), g: (0-255) })
    val('rgba', { r: (-255), g: (0-255), b: (0-255), a: (0-255) })
    val(null, { r: (0-255), g: (0-255) })
    val('hvga'):  incorrect usage - cannot set hsv AND rgb as they will conflict


jPicker ColorMethod Utility Class

Static methods for altering and retrieving different color spaces.

(jQuery).jPicker.ColorMethods.hexToRgba:
    function(hex)
    returns { r: (0-255), g: (0-255), b: (0-255), a: (0-255) }
    
(jQuery).jPicker.ColorMethods.validateHex:
    function(hex)
    returns new hex string
    
(jQuery).jPicker.ColorMethods.rgbaToHex:
    function({ r: (0-255), g: (0-255), b: (0-255), a: (0-255) })
    returns hex string
    
(jQuery).jPicker.ColorMethods.intToHex:
    function(number)
    returns hex string
    
(jQuery).jPicker.ColorMethods.hexToInt:
    function(hex)
    return integer

(jQuery).jPicker.ColorMethods.rgbToHsv:
    function({ r: (0-255), g: (0-255), b: (0-255) })
    returns { h: (0-360), s: (0-100), v: (0-100) }

(jQuery).jPicker.ColorMethods.hsvToRgb:
    function({ h: (0-360), s: (0-100), v: (0-100) })
    returns { r: (0-255), g: (0-255), b: (0-255) }


Known Issues

Coming Soon

Planned For Future Release

Change Log