# Spectrum

## The No Hassle jQuery Colorpicker

Download Zip View the Source code. Spectrum is a project by @bgrins.

    <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,
        className: 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
    });

### className

You can add an additional class name to the replacer and container element using the `className` property.

    $("#className").spectrum({
        className: 'awesome'
    });

    .awesome {
        background: purple;
    }

### Preferred Format

You can set the format that is displayed

    $("#preferredHex").spectrum({
        preferredFormat: "hex",
        showInput: true
    });
    $("#preferredHex6").spectrum({
        preferredFormat: "hex6",
        showInput: true
    });
    $("#preferredHsl").spectrum({
        preferredFormat: "hsl",
        showInput: true
    });
    $("#preferredRgb").spectrum({
        preferredFormat: "rgb",
        showInput: true
    });
    $("#preferredName").spectrum({
        preferredFormat: "name",
        showInput: true
    });
    $("#preferredNone").spectrum({
        showInput: true
    });

Hex
Hex (6 Characters Always)
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 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
    #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"