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:
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.
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.
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.
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.
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.
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.
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 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
});
$("#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]
});
spectrum initializer, like $(element).spectrum({showAlpha: true }) or on the element's markup, like <input data-show-alpha="true" />.
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>
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
});
You can allow alpha transparency selection. Check out these examples:
$("#showAlpha").spectrum({
showAlpha: true
});
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({
});
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']
]
});
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']
]
});
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
});
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({
});
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
});
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
});
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
});
You can set the button's text using cancelText and chooseText properties.
$("#buttonText").spectrum({
allowEmpty:true,
chooseText: "Alright",
cancelText: "No way"
});
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
});
You can add an additional class name to the just the container element using the containerClassName property.
$("#containerClassName").spectrum({
containerClassName: 'awesome'
});
.awesome {
background: purple;
}
You can add an additional class name to just the replacer element using the replacerClassName property.
$("#replacerClassName").spectrum({
replacerClassName: 'awesome'
});
.awesome {
background: purple;
}
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)"]]
});
$("#picker").spectrum({
move: function(tinycolor) { },
show: function(tinycolor) { },
hide: function(tinycolor) { },
beforeShow: function(tinycolor) { },
});
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
}
Called as the user moves around within the colorpicker
move: function(color) {
color.toHexString(); // #ff0000
}
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
}
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
}
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
}
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
}
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
}
$("#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);
Shows the colorpicker.
Hides the colorpicker.
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;
});
Gets the current value from the colorpicker.
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>
Retrieves the container element of the colorpicker, in case you want to manaully position it or do other things.
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.
Removes the colorpicker functionality and restores the element to its original state.
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.
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).
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
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.
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.
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 Support is provided using proprietary filters. Other browsers use CSS gradients.
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 #fff fff #ffffff ffffff rgb(255, 0, 0) rgb 255 0 0 hsl(0, 100, 50) hsl(0, 100%, 50%) hsl 0 100 50 hsl 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"