<input type='color' value='#f594d0' />
Why A Colorpicker?
I wasn't satisfied with the solutions available for colorpicking. Many of them included a ton of images, were hard to skin or customize, or were very large plugins. Here are the goals I had when making a new one:
Small Footprint
see a working jsFiddle example
Just include the needed CSS and JavaScript files, and you are ready to go!
<script src='spectrum.js'></script><link rel='stylesheet' href='spectrum.css' />
We don't need no stinkin' images!
Nobody wants to add a bunch of code into their project. Spectrum is contained in two files, and both are careful not to mess with your existing code.
Polyfill
I wanted an option for the most basic use case, a polyfill for the input[type=color] HTML5 control. This mode needs to work without JavaScript enabled - and fallback to an input[type=text] like other HTML5 inputs.
If you don't want this behavior to happen, but still want to use spectrum elsewhere on the page, you can set $.fn.spectrum.load = false;
right after loading the script file.
Customizable
Just because you don't have to change anything to get it to work, doesn't mean you can't! It is easy to skin and customize the plugin with CSS, and there are a wide range of modes and options to explore.
Mobile Support
Along with desktop browser support, I wanted a mobile colorpicker that was touch friendly, worked in iOS and Android, and used standards that maximize future mobile support.
Devtools
Believe it or not, this colorpicker lives inside of Chrome and Safari devtools to make picking colors easier for web developers and designers.
When I started the project, I wrote about developer tools concept colorpicker implementation. After that, I was contacted on the devtools mailing list and got some initial feedback about the possibility of integrating it with devtools. Then I pulled the jQuery dependency out of a branch and I submitted a patch to the WebKit project.
From there, I opened a development case, entitled Web Inspector: Add colorpicker functionality to color swatches in Styles Sidebar. 50+ comments and 10 patches later, the case landed in WebKit. Thanks to all the WebKit developers who helped me along the way with getting the code and UI ready for committing.
Modes
input[type=color]
If you just want to provide a polyfill for the native color input, the easiest way is to create an input with the type of color. Once a user's browser supports a native color control, it will opt to use their native control instead.
Unlike the other modes, your value must be a 6 character hex value starting with a '#'. Why? Because the spec says so, that's why.
<input type='color' name='color' /><input type='color' name='color2' value='#3355cc' />
That's it! The field will degrade to a text input if the user does not have JavaScript enabled, so that they will still be able to manually enter a color. You don't need to add a single line of code.
Custom
If you want to get more into the functionality, just create a normal input and initialize it as a normal jQuery plugin. You can set a lot of options when initializing the colorpicker. See the 'Options' section below.
<input type='text' id="custom" />
<script>$("#custom").spectrum({ color: "#f00"});</script>
Flat
Flat This means that it will always show up at full size, and be positioned as an inline-block element. Look to the left for a full sized flat picker.
<input type='text' id="flat" /><br/><input type='text' id="flat" />
$("#flat").spectrum({ flat: true, showInput: true});$("#flatClearable").spectrum({ flat: true, showInput: true, allowEmpty:true});
Options
$("#picker").spectrum({ color: tinycolor, flat: bool, showInput: bool, showInitial: bool, allowEmpty: bool, showAlpha: bool, disabled: bool, localStorageKey: string, showPalette: bool, showPaletteOnly: bool, showSelectionPalette: bool, clickoutFiresChange: bool, cancelText: string, chooseText: string, containerClassName: string, replacerClassName: string, preferredFormat: string, maxSelectionSize: int, palette: [[string]], selectionPalette: [string]});
Tip: options can be specified in an options object in the spectrum
initializer, like $(element).spectrum({showAlpha: true })
or on the element's markup, like <input data-show-alpha="true" />
.
Color
The initial color will be set with the color
option. If you don't pass in a color, Spectrum will use the value
attribute on the input.
The color parsing is based on the TinyColor plugin. This should parse any color string you throw at it.
<input type='text' class='basic' value='red' /><input type='text' class='basic' value='#0f0' /><input type='text' class='basic' value='blue' /><br /><input type='text' class='override' /><br /><input type='text' class='startEmpty' value='' />
<script>$(".basic").spectrum();$(".override").spectrum({ color: "yellow"});(".startEmpty").spectrum({ allowEmpty: true});</script>
Show Input
You can add an input to allow free form typing. The color parsing is very permissive in the allowed strings. See TinyColor for more details.
$("#showInput").spectrum({ showInput: true});$("#showInputWithClear").spectrum({ showInput: true, allowEmpty:true});
Show Alpha
You can allow alpha transparency selection. Check out these examples:
$("#showAlpha").spectrum({ showAlpha: true});
Disabled
Spectrum can be automatically disabled if you pass in the disabled
flag. Additionally, if the input that you initialize spectrum on is disabled, this will be the default value. Note: you cannot enable spectrum if the input is disabled (see below).
$("#disabled").spectrum({ disabled: true});$("input:disabled").spectrum({});
Show Palette
Spectrum can show a palette below the colorpicker to make it convenient for users to choose from frequently or recently used colors. When the colorpicker is closed, the current color will be added to the palette if it isn't there already. Check it out here:
$("#showPalette").spectrum({ showPalette: true, palette: [ ['black', 'white', 'blanchedalmond'], ['rgb(255, 128, 0);', 'hsv 100 70 50', 'lightyellow'] ]});
Show Palette Only
see a working jsFiddle example
If you'd like, spectrum can show the palettes you specify, and nothing else.
$("#showPaletteOnly").spectrum({ showPaletteOnly: true, showPalette:true, color: 'blanchedalmond', palette: [ ['black', 'white', 'blanchedalmond', 'rgb(255, 128, 0);', 'hsv 100 70 50'], ['red', 'yellow', 'green', 'blue', 'violet'] ]});
Result
Show Selection Palette
Spectrum can keep track of what has been selected by the user with the showSelectionPalette
option.
If the localStorageKey
option is defined, the selection will be saved in the browser's localStorage object
$("#showSelectionPalette").spectrum({ showPalette: true, showSelectionPalette: true, // true by default palette: [ ]});$("#showSelectionPaletteStorage").spectrum({ showPalette: true, showSelectionPalette: true, palette: [ ], localStorageKey: "spectrum.homepage", // Any Spectrum with the same string will share selection});
This colorpicker will store what you pick:
Try switching between the two colorpickers or reloading your page, the chosen colors are always available:
Clickout Fires Change
When clicking outside of the colorpicker, you can force it to fire a change
event rather than having it revert the change.
$("#clickoutFiresChange").spectrum({ clickoutFiresChange: true});$("#clickoutDoesntChange").spectrum({});
Show Initial
Spectrum can show the color that was initially set when opening. This provides an easy way to click back to what was set when opened.
$("#showInitial").spectrum({ showInitial: true});
Show Input and Initial
If you specify both the showInput
and showInitial
options, the CSS keeps things in order by wrapping the buttons to the bottom row, and shrinking the input. Note: this is all customizable via CSS.
$("#showInputAndInitial").spectrum({ showInitial: true, showInput: true});
Show Input, Initial, and Clear
If you specify both the showInput
, showInitial
, and allowEmpty
options, the CSS keeps things in order by wrapping the buttons to the bottom row, and shrinking the input. Note: this is all customizable via CSS.
$("#showInputInitialClear").spectrum({ allowEmpty:true, showInitial: true, showInput: true});
Button Text
You can set the button's text using cancelText
and chooseText
properties.
$("#buttonText").spectrum({ allowEmpty:true, chooseText: "Alright", cancelText: "No way"});
Show Buttons
You can show or hide the buttons using the showButtons
property. If there are no buttons, the behavior will be to fire the `change` event (and update the original input) when the picker is closed.
$("#hideButtons").spectrum({ showButtons: false});
Container Class Name
You can add an additional class name to the just the container element using the containerClassName
property.
$("#containerClassName").spectrum({ containerClassName: 'awesome'});
.awesome { background: purple;}
Replacer Class Name
You can add an additional class name to just the replacer element using the replacerClassName
property.
$("#replacerClassName").spectrum({ replacerClassName: 'awesome'});
.awesome { background: purple;}
Preferred Format
You can set the format that is displayed in the text box.
This will also change the format that is displayed in the titles from the palette swatches.
$("#preferredHex").spectrum({ preferredFormat: "hex", showInput: true, showPalette: true, palette: [["red", "rgba(0, 255, 0, .5)", "rgb(0, 0, 255)"]]});$("#preferredHex3").spectrum({ preferredFormat: "hex3", showInput: true, showPalette: true, palette: [["red", "rgba(0, 255, 0, .5)", "rgb(0, 0, 255)"]]});$("#preferredHsl").spectrum({ preferredFormat: "hsl", showInput: true, showPalette: true, palette: [["red", "rgba(0, 255, 0, .5)", "rgb(0, 0, 255)"]]});$("#preferredRgb").spectrum({ preferredFormat: "rgb", showInput: true, showPalette: true, palette: [["red", "rgba(0, 255, 0, .5)", "rgb(0, 0, 255)"]]});$("#preferredName").spectrum({ preferredFormat: "name", showInput: true, showPalette: true, palette: [["red", "rgba(0, 255, 0, .5)", "rgb(0, 0, 255)"]]});$("#preferredNone").spectrum({ showInput: true, showPalette: true, palette: [["red", "rgba(0, 255, 0, .5)", "rgb(0, 0, 255)"]]});
Hex
Hex (3 Characters If Possible)
Hsl
Rgb
Name (Falls back to hex)
None (Depends on input - try changing formats with the text box)
Events
$("#picker").spectrum({ move: function(tinycolor) { }, show: function(tinycolor) { }, hide: function(tinycolor) { }, beforeShow: function(tinycolor) { },});
change
Called as the original input changes. Only happens when the input is closed or the 'Choose' button is clicked.
change: function(color) { color.toHexString(); // #ff0000}
move
Called as the user moves around within the colorpicker
move: function(color) { color.toHexString(); // #ff0000}
hide
Called after the colorpicker is hidden. This happens when clicking outside of the picker while it is open. Note, when any colorpicker on the page is shown it will hide any that are already open. This event is ignored on a flat colorpicker.
hide: function(color) { color.toHexString(); // #ff0000}
show
Called after the colorpicker is opened. This is ignored on a flat colorpicker. Note, when any colorpicker on the page is shown it will hide any that are already open.
show: function(color) { color.toHexString(); // #ff0000}
beforeShow
You can prevent the colorpicker from showing up if you return false in the beforeShow event. This event is ignored on a flat colorpicker.
beforeShow: function(color) { return false; // Will never show up}
dragstart
Called at the beginning of a drag event on either hue slider, alpha slider, or main color picker areas
$(element).on("dragstart.spectrum"): function(e, color) { color.toHexString(); // #ff0000}
dragstop
Called at the end of a drag event on either hue slider, alpha slider, or main color picker areas
$(element).on("dragstop.spectrum"): function(e, color) { color.toHexString(); // #ff0000}
Methods
$("#picker").spectrum("show");$("#picker").spectrum("hide");$("#picker").spectrum("toggle");$("#picker").spectrum("get");$("#picker").spectrum("set", colorString);$("#picker").spectrum("container");$("#picker").spectrum("reflow");$("#picker").spectrum("destroy");$("#picker").spectrum("enable");$("#picker").spectrum("disable");$("#picker").spectrum("option", optionName);$("#picker").spectrum("option", optionName, newOptionValue);
show
Shows the colorpicker.
hide
Hides the colorpicker.
toggle
Toggles the colorpicker.
Warning: If you are calling toggle from a click handler, make sure you return false
to prevent the colorpicker from immediately hiding after it is toggled.
$("#btn-toggle").click(function() { $("#toggle").spectrum("toggle"); return false;});
get
Gets the current value from the colorpicker.
set
Setting the colorpicker programmatically will update the original input.
Note: this will not fire the change
event, to prevent infinite loops from calling set
from within change
.
<input type='text' value='blanchedalmond' name='triggerSet' id='triggerSet' /><input type='text' placeholder='Enter A Color' id='enterAColor' /><button id='btnEnterAColor'>Trigger Set</button><script>$("#triggerSet").spectrum();// Show the original input to demonstrate the value changing when calling `set`$("#triggerSet").show();$("#btnEnterAColor").click(function() { $("#triggerSet").spectrum("set", $("#enterAColor").val());});</script>
container
Retrieves the container element of the colorpicker, in case you want to manaully position it or do other things.
reflow
Resets the positioning of the container element. This could be used was hidden when initialized, or if the colorpicker is inside of a moving area.
destroy
Removes the colorpicker functionality and restores the element to its original state.
enable
Allows selection of the colorpicker component. If it is already enabled, this method does nothing.
Additionally, this will cause the original (now hidden) input to be set as disabled.
disable
Disables selection of the colorpicker component. Adds the sp-disabled
class onto the replacer element. If it is already disabled, this method does nothing.
Additionally, this will remove the disabled
property on the original (now hidden).
option
Calling option
with an option name will return the current value of that option. So, for example:
$("input").spectrum({ showInput: true});$("input").spectrum("option", "showInput"); // true
Calling option
with an option name and an option value will set the option to the new value.
$("input").spectrum({ showInput: true});$("input").spectrum("option", "showInput", false);$("input").spectrum("option", "showInput"); // false
Skinning
Since it is all built with HTML/CSS, you can skin it easily. There are two parts to the spectrum.css file, the core rules (at the top of the file), and the themable rules (at the bottom). Feel free to tweak these rules to make it look how you want.
Non-input elements
You can use any element you would like to trigger the colorpicker: Click me to open a colorpicker, though it is strongly recommended to stick with <input>
tags.
Nitty Gritty
Browser Support
I wanted this to work in the latest and greatest browsers, but also target backwords compatibility and mobile support. Here are the currently supported browers:
- IE 6+
- Chrome 4+
- Firefox 3.6+
- Safari 4+
- Opera 11.1+
- iOS
IE Implementation
IE Support is provided using proprietary filters. Other browsers use CSS gradients.
Accepted Color Inputs
Spectrum will use the color passed in to initialize. If there is no color passed in, it will try to parse a color based on the value
of the input. The color parsing is based on the TinyColor plugin, and accepts many forms of input:
red#ffffff#ffffffffffffrgb(255, 0, 0)rgb 255 0 0hsl(0, 100, 50)hsl(0, 100%, 50%)hsl 0 100 50hsl 0 100% 50%hsv(0, 100%, 100%)hsv(0, 100, 100)hsv 0 100% 100%hsv 0 100 100
It also provides the following forms of output:
var t = $("#element").spectrum("get");t.toHex() // "ff0000"t.toHexString() // "#ff0000"t.toRgb() // {"r":255,"g":0,"b":0}t.toRgbString() // "rgb(255, 0, 0)"t.toHsv() // {"h":0,"s":1,"v":1}t.toHsvString() // "hsv(0, 100%, 100%)"t.toHsl() // {"h":0,"s":1,"l":0.5}t.toHslString() // "hsl(0, 100%, 50%)"t.toName() // "red"
Share
If you've made it this far, please share one of these links to help others find this project!
JavaScript Colorpicker | jQuery Colorpicker | Mobile Colorpicker | Spectrum colorpicker
Thanks to all the spectrum contributors for committing code, documentation, and translations.
If you want to let me (@bgrins) know you are using it, send me a link where it can be seen or add it to the list of projects using Spectrum!