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 version previous to V1.0.12, you MUST read the docs below to implement some small changes to the Color object returned by the callback functions.
View John Dyer's prototype plugin here.
View jPicker details a docs below.
Download jPicker V1.0.13 (215 KB)
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({ hex: '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="e2ddcfff" />
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="e2ddcfff" /><br />
<input class="Multiple" type="text" value="888888ff" /><br />
<input class="Multiple" type="text" value="fda0f7ff" />
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'); // you don't
//want it searching this on every live callback!!!
$('#Callbacks').jPicker(
{},
function(color)
{
var hex = color.get_Hex();
alert('Color chosen - hex: #' + hex + ' - alpha: ' + color.get_A() + '%');
$('#Commit').css(
{
backgroundColor: hex && hex.length == 6 ? '#' + hex : 'transparent'
}); // prevent IE from throwing exception if hex is empty
},
function(color)
{
LiveCallbackElement.css(
{
var hex = color.get_Hex();
backgroundColor: hex && hex.length == 6 ? '#' + hex : 'transparent'
}); // prevent IE from throwing exception if hex is empty
},
function(color)
{
alert('"Cancel" Button Clicked');
});
});
</script>
<input id="Callbacks" type="text" value="e2ddcfff" />
<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>
Commit
Live
jPicker Settings And Colors
Get the jPicker object by index and retrieve active color.
(jQuery).jPicker.List[index]
<script type="text/javascript">
$(document).ready(
function()
{
$('#GetColors').jPicker();
$('#ActiveColor').click(
function()
{
alert($.jPicker.List[0].settings.color.active.get_Rgba());
});
});
</script>
<input id="GetColors" type="text" value="e2ddcfff" /><br />
<input id="ActiveColor" type="button" value="Active Color" />
Download jPicker V1.0.13 ZIP File
Both a full source (89.7 KB) and a minified (33.6 KB) js file are included in this download.
Download jPicker V1.0.13 (215 KB)
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
},
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)'
}
}
}
}
Callback Pattern
function(jPicker.Color color){...}
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({ r: (0-255), g: (0-255), b: (0-255), [a: (0-100)] })
(jQuery).jPicker.Color({ h: (0-360), s: (0-100), v: (0-100), [a: (0-100)] })
(jQuery).jPicker.Color({ hex: 'ffffff', [a: (0-100)] })
{
get_R: // gets "Red" value
function()
returns (0-255),
get_G: // gets "Green" value
function()
returns (0-255),
get_B: // gets "Blue" value
function()
returns (0-255),
get_A: // gets "Alpha" value
function()
returns (0-100),
get_H: // gets "Hue" value
function()
returns (0-360),
get_S: // gets "Saturation" value
function()
returns (0-100),
get_V: // gets "Brightness" value
function()
returns (0-100),
get_Hex: // gets 6-digit "Hex" value
function()
returns (000000-ffffff),
get_Rgba: // gets 8-digit "Hex" (w/Alpha) value
function()
returns (00000000-ffffffff),
fromRgb: function(r, g, b),
fromHsv: function(h, s, v),
fromHex: function(hex)
}
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-100) }
(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-100) })
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
-
Attaching multiple jPicker objects on a single page will slow performance.
- jPicker creates a new instance of the picker for every element. Performance will suffer when binding dozens of instances.
-
Internet Explorer 8 Standards Mode is slow on dragging markers.
- While profiling using IE8 Dev kit it indicates it takes MUCH longer to apply the style changes while dragging the markers.
- There is no current solution I am aware of to fix this.
Coming Soon
-
V1.1.0
- Will consider supporting jQuery ThemeRoller CSS API for theming the UI if demand exists.
-
Move the jPicker object to a single instance that all selection instances point to.
- This will result in much faster operation and initialization for pages with multiple pickers.
- This will also remove the requirement for Internet Explorer to hide the picker icons for elements higher in the DOM (IE calculates its own z-index for embedded, positioned elements).
- Add activateCallback option for calling a callback function when the jPicker is activated or its binding is switched to a different picker element.
Change Log
-
V1.0.13:
- Updated transparency algorithm for red/green/blue color modes. The algorithm from John Dyers' color picker was close but incorrect. Bar colors are now pixel perfect with the new algorithm.
- Changed from using "background-position" on the color maps to an element of full height using the "top" attribute for image-map location using "overflow: hidden" to hide overdraw.
- IE7/8 ignores opacity on elements taller than 4096px. Image maps therefore no longer include a blank first map so the Bar is just under 4096. Blank is now accomplished by setting the "top" setting to below the map display.
- New colorBar picker image that does not draw outside of the element since the elements now hide overdraw.
- Added IE5.5/6 support for the picker. This is why it now uses maps of full height and the "top" attribute for map locations.
- Moved the images in the maps to 4 pixels apart from each other. IE7/8 change the first pixel of the bottom-border of 2px to partially transparent showing a portion of a different color map without this.
-
V1.0.12:
- Added minified CSS file.
- Added IE7/8 Quirks Mode support.
- Added configurable string constants for all text and tooltips. You can now change the default values for different languages.
- Privatized the RGBA values in the Color object for better NULL handling. YOU MUST USE THE NEW GET FUNCTIONS TO ACCESS THE COLOR PROPERTIES.
- Better NULL color handling and an additional "No Color Selected" quick pick color.
- More consistent behavior across multiple versions of browsers.
- Added alpha response to the binded color picker icon.
- Removed "alphaSupport" variable. It is now always supported.
-
V1.0.11b:
- Corrected NULL behavior in IE. jQuery was getting an exception when attempting to assign a backgroundColor style of '#'. Now assigns 'transparent' if color is NULL.
- Can now create new Color object WITH OR WITHOUT the '#' prefix.
-
V1.0.11:
- Added ability for NULL colors (delete the hex value). Color will be returned as color.hex == ''. Can set the default color to an empty hex string as well.
- cancelCallback now returns the original color for use in programming responses.
-
V1.0.10:
- Corrected table layout and tweaked display for more consisent presentation. Nice catch from Jonathan Pasquier.
-
V1.0.9:
- Added optional title variable for each jPicker window.
-
V1.0.8:
- Moved all images into a few sprites - now using backgroundPosition to change color maps and bars instead of changing the image - this should be faster to download and run.
-
V1.0.7:
- RENAMED CSS FILE TO INCLUDE VERSION NUMBER!!! YOU MUST USE THIS VERSIONED CSS FILE!!! There will be no need to do your own CSS version number increments from now on.
- Added opacity feedback to color preview boxes.
- Removed reliance on "id" value of containing object. Subobjects are now found by class and container instead of id's. This drastically reduces injected code.
- Removed (jQuery).jPicker.getListElementById(id) function since "id" is no longer incorporated or required.
-
V1.0.6:
- Corrected picker bugs introduced with 1.0.5.
- Removed alpha slider bar until activated - default behavior for alpha is now OFF.
- Corrected Color constructor bug not allowing values of 0 for initial value (it was evaluating false and missing the init code - Thanks Pavol).
- Removed title tags (tooltips) from color maps and bars - They get in the way in some browsers (e.g. IE - dragging marker does NOT prevent or hide the tooltip).
- THERE WERE CSS FILE CHANGES WITH THIS UPDATE!!! IF YOU USE NEVER-EXPIRE HEADERS, YOU WILL NEED TO INCREMENT YOUR CSS FILE VERSION NUMBER!!!
-
V1.0.5:
- Added opacity support to picker and color/callback methods. New property "a" (alpha - range from 0-100) in all color objects now - defaults to 100% opaque. (Thank you Pavol)
- Added title attributes to input elements - gives short tooltip directions on what button or field does.
- Commit callback used to fire on control initialization (twice actually) - This has been corrected, it does not fire on initialization.
- THERE WERE CSS FILE CHANGES WITH THIS UPDATE!!! IF YOU USE NEVER-EXPIRE HEADERS, YOU WILL NEED TO INCREMENT YOUR CSS FILE VERSION NUMBER!!!
-
V1.0.4:
- Added ability for smaller picker icon with expandable window on any DOM element (not just input).
- "draggable" property renamed to "expandable" and its scope increased to create small picker icon or large static picker.
-
V1.0.3
- Added cancelCallback function for registering an external function when user clicks cancel button. (Thank you Jeff and Pavol)
-
V1.0.2
- Random bug fixes - speed concerns.
-
V1.0.1
- Corrected closure based memeory leak - there may be others?
-
V1.0.0
