jQuery MiniColors 2.0 beta

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.

Download

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

Usage

The plugin will automatically initialize all inputs of type minicolors:

<input type="minicolors" />

This results in the default color picker:

To set an initial value, use the value attribute:

<input type="minicolors" value="#00cc00" />

This results in the default color picker with a preset value:

You can obtain the selected value any time by grabbing the original input element's value.

Options

Options are set for each control using one or more of the HTML5 data- attributes mentioned below.

Slider Variations

MiniColors has four slider variations. Set the data-slider attribute to use them. Valid options are hue (default), saturation, brightness, and wheel.

<input type="minicolors" data-slider="saturation" />

Default Values

Use the data-default attribute to force a default hex value. Try clearing the box—it will revert to its default value. Note that the default value does not have to be the same as the initial value (set with the value attribute).

<input type="minicolors" data-default="#ffffff" />

No Text Field

Turn the color picker into a stand-alone color swatch by setting data-textfield to false:

<input type="minicolors" data-textfield="false" />

Opacity Slider

Enable the opacity slider by adding the data-opacity attribute:

<input type="minicolors" data-opacity=".75" />

To obtain the opacity value, grab the data-opacity attribute of your input element. Keep in mind that this value will not submit along with other form data, so it's best to use the change callback to update a hidden element in your form if you need it to be submitted.

Inline Controls

Force the color picker to appear inline by setting data-control to inline:

<input type="minicolors" data-control="inline" />

Dropdown Position

Change the position of the dropdown panel by setting the data-position attribute. Valid options are top, left, and top left.

<input type="minicolors" data-position="top" />

Swatch Position

Force the color swatch to appear on the left by setting data-swatch-position to left:

<input type="minicolors" data-swatch-position="left" />

Classes & Styles

Use data-class and data-style to apply classes and styles to the parent element of the resulting control:

<input type="minicolors" data-class="my-class" data-style="margin: 20px;" />

Utility Functions

$.minicolors.init()

Call this function to initialize controls that are created dynamically. You do not need to specify a selector when calling this function. Example:

$.minicolors.remove(input)

Call this function to remove a control from the DOM. (You can also remove any of the control's parent elements with the same effect.)

$.minicolors.refresh()

Call this function if you programmatically change the value of one or more controls.

$.minicolors.show(input)

Show the control attached to the specified input element. Only one control may be shown at once. (Doesn't apply to inline controls.)

$.minicolors.hide()

Hides any control that may be showing. (Doesn't apply to inline controls.)

$.minicolors.rgbObject(input)

Returns an object with r, g, b, and a properties. The a property will only be present if opacity is enabled on the specified control.

$.minicolors.rgbString(input)

Returns an RGB or RGBA string suitable for use in your CSS. If opacity is enabled on the specified control, an RGBA string will be returned. Otherwise an RGB string will be returned.

Callbacks

change

Attach your change callback to the original input element. You can access the value and opacity of the control using the value and data-opacity attributes, respectively.

To convert a control's hex value to RGB or RGBA, use the $.minicolors.rgbObject() or $.minicolors.rgbString() utility functions.

Settings

Adjust plugin defaults by setting $.minicolors.settings.settingName, where settingName is one of the following:

animationSpeed & animationEasing

The animation speed and easing effect to use when making a color selection. Defaults to 100 (milliseconds) and swing, respectively. Set animationSpeed to 0 to disabled animation.

defaultSlider

Sets the slider variation for all controls that don't specify it through data-slider. Default value is hue.

letterCase

Forces the hex color's letter case to uppercase or lowercase. Possible values are lowercase (default) and uppercase.

hideSpeed & showSpeed

The hide/show speed for dropdown controls. Default is 100 (milliseconds).

Styling Tips

If you change the input element's height or width via CSS, you'll also need to adjust certain style properties in .minicolors-swatch, .minicolors-panel, .minicolors-position-top, and .minicolors-position-left.