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 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 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 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 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" />
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" />
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" />
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 function - returns the jQuery object.
jPicker([settings, [commitCallback, [liveCallback, [cancelCallback]]]])
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
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)'
}
}
}
}
function(jPicker.Color color, object context){...}
The list of active jPicker objects.
(jQuery).jPicker.List[]
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
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) }