jQuery MiniColors 2.0

A project by Cory LaViska of A Beautiful Site.

MiniColors is a tiny color picker built on jQuery. It's easy to use and works well on touch-enabled devices. Completely re-written for 2.0.

Demo

Standard Controls

Hue Saturation Brightness Wheel

Inline Controls

Download

You can download the source on GitHub. Help contribute to this project by posting bug reports, feature requests, and code improvements!

Usage

$('INPUT.minicolors').minicolors(settings);

Settings

All available settings are shown below with default values:

{
    animationSpeed: 100,
    animationEasing: 'swing',
    change: null,
    changeDelay: 0,
    control: 'hue',
    defaultValue: '',
    hide: null,
    hideSpeed: 100,
    inline: false,
    letterCase: 'lowercase',
    opacity: false,
    position: 'default',
    show: null,
    showSpeed: 100,
    swatchPosition: 'left',
    textfield: true,
    theme: 'default'
}

animationSpeed

The animation speed of the sliders when the user taps or clicks a new color. Set to 0 for no animation.

animationEasing

The easing to use when animating the sliders.

changeDelay

The time, in milliseconds, to defer the change event from firing while the user makes a selection. This is useful for preventing the change event from firing frequently as the user drags the color picker around.

The default value is 0 (no delay). If your change callback features an AJAX request, you’ll probably want to set this to at least 200.

control

Determines the type of control. Valid options are hue, brightness, saturation, and wheel.

defaultValue

To force a default color, set this to a valid hex string. When the user clears the control, it will revert to this color.

Default value: #ffcc00

hideSpeed & showSpeed

The speed at which to hide and show the color picker.

inline

Set to true to force the color picker to appear inline.

letterCase

Determines the letter case of the hex code value. Valid options are uppercase or lowercase.

Uppercase Lowercase

opacity

Set to true to enable the opacity slider. (Use the input element's data-opacity attribute to set a preset value.)

position

Sets the position of the dropdown. Valid options are default, top, left, and top left.

default top left top left

swatchPosition

Determines which side of the textfield the color swatch will appear. Valid options are left and right.

left right

textfield

Whether or not to show the textfield. Set to false for a swatch-only control:

theme

A string containing the name of the custom theme to be applied. In your CSS, prefix your selectors like this:

.minicolors-theme-yourThemeName { ... }

Then set your theme like this:

$(selector).minicolors({
    theme: 'yourThemeName'
});

Here are a few examples:

Default theme (default)


Bootstrap theme (bootstrap)


No theme (none)

A note about writing themes

When writing a theme, please make sure it supports both swatch positions (swatchPosition) and all panel positions (position). If you've written a theme and would like to have it included with MiniColors, feel free to submit it to the project on GitHub.

Methods

Use this syntax for calling methods:

$(selector).minicolors('method', [data]);

create

Initializes the control for all items matching your selector. This is the default method, so data may be passed in as the only argument.

To set a preset color value, populate the value attribute of the original input element.

destroy

Returns the input element to its original, uninitialized state.

opacity

Gets or sets a control's opacity level. To use this method as a setter, pass data in as a value between 0 and 1. (You can also obtain this value by checking the input element's data-opacity attribute.)

To set a preset opacity value, populate the data-opacity attribute of the original input element.

rgbObject

Returns an object containing red, green, blue, and alpha properties that correspond to the control's current value. Example:

{ r: 0, g: 82, b: 148, a: 0.75 }

rgbString & rgbaString

Returns an RGB or RGBA string suitable for use in your CSS. Examples:

rgb(0, 82, 148)
rgba(0, 82, 148, .75)

settings

Gets or sets a control's settings. If new settings are passed in, the control will destroy and re-initialize itself with any new settings overriding the old ones.

value

Gets or sets a control's color value. To use this method as a setter, pass data in as a hex value. (You can also obtain this value by checking the input element's value attribute.)

Events

change

Fires when the value of the color picker changes. The this keyword will reference the original input element. Warning: This event will fire a lot if the user drags the color picker around.

$(selector).minicolors({
    change: function(hex, opacity) {
        console.log(hex + ' - ' + opacity);
    }
});

hide

Fires when the color picker is hidden. The this keyword will reference the original input element.

$(selector).minicolors({
    hide: function() {
        console.log('Hide event triggered!');
    }
});

show

Fires when the color picker is shown. The this keyword will reference the original input element.

$(selector).minicolors({
    show: function() {
        console.log('Show event triggered!');
    }
});