# 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.

The MiniColors API was completely overhauled in 2.0. You will need to change your code if you are upgrading from a previous version!

## 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`.