mtomek/jquery-simple-color

A dead-simple jQuery color picker.

About

jQuery Simple Color is a very simple color-picker plugin that displays a square grid of selectable colors. I found a lot of the other color-picker plugins quite heavy, so I ended up writing this to provide a dead-simple alternative. The list of colors it uses can be customized, and the layout size etc can be configured to a certain extent. jQuery Simple Color is licensed under the MIT license.

Installation

You'll need to download the jQuery library, and include it before jquery.simple-color.js in your HTML source. See the examples folder for examples.

This library is also available as a bower component under the name jquery-simple-color.

Usage

Simple Color transparently converts regular text input fields into color pickers.

First, add a text element:

<input class='simple_color' value='#cc3333'/>

Simple Color will automatically pick up the value attribute and display it as the default color.

Once you have one or more text elements set up, just use the simpleColor() function to set up the color picker:

$('.simple_color').simpleColor();

You can use any valid jQuery selector instead of '.simple_color' if you wish.

Simple Color also supports various options to customize the color picker:

$('.simple_color').simpleColor({
    cellWidth: 9,
    cellHeight: 9,
    callback: function(hex, element) {
        alert("color picked! " + hex + " for input #" + element.attr('class'));
    }
});

If you wish to programatically close a color chooser, use the closeChooser() function:

$('.simple_color').closeChooser();

If you wish to programatically set the color, use the setColor() function:

$('.simple_color').setColor('#cc3333');

Options

defaultColor:       Default (initially selected) color.
                     default value: '#FFF'

border:             CSS border properties.
                     default value: '1px solid #000'

cellWidth:          Width of each individual color cell.
                     default value: 10

cellHeight:         Height of each individual color cell.
                     default value: 10

cellMargin:         Margin of each individual color cell.
                     default value: 1

boxWidth:           Width of the color display box.
                     default value: 115px

boxHeight:          Height of the color display box.
                     default value: 20px

columns:            Number of columns to display. Color order may look strange if this is altered.
                     default value: 16

insert:             The position to insert the color picker. 'before' or 'after'.
                     default value: 'after'

colors:             An array of colors to display, if you want to customize the default color set.
                     default value: default color set - see 'default_colors' below.

displayColorCode:   Display the color code (eg #333333) as text inside the button. true or false.
                     default value: false

colorCodeAlign:     Text alignment used to display the color code inside the button. Only used if
                    'displayColorCode' is true. Possible values are 'left', 'center' or 'right',
                     default value: 'center'

colorCodeColor:     Text color of the color code inside the button. Only used if 'displayColorCode'
                    is true.
                     default value: '#FFF' or '#000', decided based on the color selected in the chooser.

onSelect:           Function to be called when a color is selected. The hex code is passed into the
                    function. The callback function will be passed two arguments - the hex code of
                    the selected color, and the input element that triggered the chooser.
                     default value: null

onCellEnter:        Callback function that excecutes when the mouse enters a cell. The callback
                    function will be passed two arguments - the hex code of the current color, and
                    the input element that triggered the chooser.
                     default value: null
                     returns: hex value

onClose:            Callback function that executes when the chooser is closed. The callback
                    function will be passed one argument - the input element that triggered the chooser.
                     default value: null

hideInput           If true, hides the original input when displaying the color picker.
                     default value: true

livePreview:        The color display will change to show the color currently under the mouse. The
                    display will revert if no color is selected.
                     default value: false

chooserCSS:         An associative array of CSS properties that will be applied to the pop-up color
                    picker.
                    Default value: see options.chooserCSS in the source

displayCSS:         An associative array of CSS properties that will be applied to the color display
                    box.
                    Default value: see options.chooserCSS in the source

inputCSS            An associative array of CSS properties that will be applied to the form input.
                    Default value: see options.inputCSS in the source

Building From Scratch

Use npm install to install the dependencies, and grunt to run the build.

Change history

• Version 1.2.0 (2013-10-12) :
  • Fix line-height bug when boxHeight option is used.
  • Fix color selection bug when chooser is closed without selecting a color.
  • Add a setColor() method to select a color programatically.
• Version 1.1.5 (2013-10-12) :
  • Add bower support.
  • Add displayCSS and chooserCSS options, and remove the border option.
  • Pass the original input element as an argument to callback functions.
  • Use CamelCase in source, plus general cleanup.
• Version 1.1.4 (2013-05-30) : Add support for jQuery 1.9.1 (thanks napcs).
• Version 1.1.3 (2013-04-07) : Rename callback option to onSelect.
• Version 1.1.2 (2013-04-06) : Add onCellEnter, onClose and livePreview options (thanks jbergen).
• Version 1.1.1 (2013-03-29) : Add callback option (thanks jbergen).
• Version 1.1.0 (2012-10-14) : Remove select and cancel buttons (thanks wesnolte).
• Version 1.0.1 (2011-08-15) : Trigger change() event when a color is selected (thanks firstclown), and make colored display box clickable to select colors.
• Version 1.0.0 (2011-05-21) : 1.0 release.

Bug Reports

If you come across any problems, please create a ticket and we'll try to get it fixed as soon as possible.

Contributing

Once you've made your commits:

1. Fork jquery-simple-color
2. Create a topic branch - git checkout -b my_branch
3. Push to your branch - git push origin my_branch
4. Create a Pull Request from your branch
5. That's it!

Author

Dave Perrett :: [email protected] :: @daveperrett

Copyright

Copyright (c) 2010 Dave Perrett. See License for details.