pickr: A JavaScript repository from ekeller

Flat, Simple, Hackable Color-Picker.

Fully Featured demo

Features

Simple usage
No jQuery
No dependencies
Multiple color representations
Color comparison
Opacity control
Responsive and auto-positioning
Supports touch devices
Lightweight, 7KB gzipped

Setup

Node

Install package:

$ npm install pickr-widget --save

Include code and style:

import '/node_modules/pickr-widget/dist/pickr.min.css';           // Styles
import Pickr from '/node_modules/pickr-widget/dist/pickr.min';  // Javascript
...your awesome code

Browser

jsdelivr:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/pickr-widget/dist/pickr.min.css"/>
<script src="https://cdn.jsdelivr.net/npm/pickr-widget/dist/pickr.min.js"></script>

Directly:

<link rel="stylesheet" href="node_modules/pickr-widget/dist/pickr.min.css"/>
<script src="node_modules/pickr-widget/dist/pickr.min.js"></script>

Be sure to load the pickr.min.js after pickr.min.css. Moreover the script tag doesn't work with the defer attribute.

Usage

// Simple example, see optional options for more configuration.
const pickr = Pickr.create({
    el: '.color-picker',

    components: {

        // Main components
        preview: true,
        opacity: true,
        hue: true,

        // Input / output Options
        interaction: {
            hex: true,
            rgba: true,
            hsla: true,
            hsva: true,
            cmyk: true,
            input: true,
            clear: true,
            save: true
        }
    }
});

Optional options

const pickr = new Pickr({

    // Selector or element which will be replaced with the actual color-picker.
    // Can be a HTMLElement.
    el: '.color-picker',

    // Using the 'el' Element as button, won't replace it with the pickr-button.
    // If true, appendToBody will also be automatically true.
    useAsButton: false,

    // Start state. If true 'disabled' will be added to the button's classlist.
    disabled: false,

    // If set to false it would directly apply the selected color on the button and preview.
    comparison: true,

    // Default color
    default: 'fff',

    // Default color representation.
    // Valid options are `HEX`, `RGBA`, `HSVA`, `HSLA` and `CMYK`.
    defaultRepresentation: 'HEX',

    // Option to keep the color picker always visible. You can still hide / show it via
    // 'pickr.hide()' and 'pickr.show()'. The save button keeps his functionality, so if
    // you click it, it will fire the onSave event.
    showAlways: false,

    // Defines a parent for pickr, if useAsButton is true and a parent is NOT defined
    // 'body' will be used as fallback.
    parent: null,

    // Close pickr with this specific key.
    // Default is 'Escape'. Can be the event key or code.
    closeWithKey: 'Escape',

    // Defines the position of the color-picker. Available options are
    // top, left and middle relativ to the picker button.
    // If clipping occurs, the color picker will automatically choose his position.
    position: 'middle',

    // Enables the ability to change numbers in an input field with the scroll-wheel.
    // To use it set the cursor on a position where a number is and scroll, use ctrl to make steps of five
    adjustableNumbers: true,

    // Show or hide specific components.
    // By default only the palette (and the save button) is visible.
    components: {

        preview: true, // Left side color comparison
        opacity: true, // Opacity slider
        hue: true,     // Hue slider

        // Bottom interaction bar, theoretically you could use 'true' as propery.
        // But this would also hide the save-button.
        interaction: {
            hex: true,  // hex option  (hexadecimal representation of the rgba value)
            rgba: true, // rgba option (red green blue and alpha)
            hsla: true, // hsla option (hue saturation lightness and alpha)
            hsva: true, // hsva option (hue saturation value and alpha)
            cmyk: true, // cmyk option (cyan mangenta yellow key )

            input: true, // input / output element
            clear: true, // Button which provides the ability to select no color,
            save: true   // Save button
        },
    },

    // Button strings, brings the possibility to use a language other than English.
    strings: {
       save: 'Save',  // Default for save button
       clear: 'Clear' // Default for clear button
    },

    // User has changed the color
    onChange(hsva, instance) {
        hsva;     // HSVa color object, if cleared null
        instance; // Current Pickr instance
    },

    // User has clicked the save button
    onSave(hsva, instance) {
        // same as onChange
    }
});

The HSVaColor object

As default color representation is hsva (hue, saturation, value and alpha) used, but you can also convert it to other formats as listed below.

hsva.toHSVA() - Converts the object to a hsva array.
hsva.toHSLA() - Converts the object to a hsla array.
hsva.toRGBA() - Converts the object to a rgba array.
hsva.toHEX() - Converts the object to a hexa-decimal array.
hsva.toCMYK() - Converts the object to a cymk array.
hsva.clone() - Clones the color object.

The toString() is overriden so you can get a color representaion string.

hsva.toRGBA(); // Returns [r, g, b, a]
hsva.toRGBA().toString(); // Returns rgba(r, g, b, a)

Methods

pickr.setHSVA(h:Number,s:Number,v:Number,a:Float, silent:Boolean) - Set an color, returns true if the color has been accepted.
pickr.setColor(string:String, silent:Boolean) - Parses a string which represents a color (e.g. #fff, rgb(10, 156, 23)), returns true if the color has been accepted. null will clear the color.

If silent is true (Default is false), the button won't change the current color.

pickr.show() - Shows the color-picker, returns instance.
pickr.hide() - Hides the color-picker, returns instance.
pickr.disable() - Disables pickr and adds the disabled class to the button, returns instance.
pickr.enable() - Enables pickr and removes the disabled class from the button, returns instance.
pickr.isOpen() - Returns true if the color picker is currently open.
pickr.getRoot():HTMLElement - Returns the root DOM-Element of the color-picker.
pickr.getColor():HSVaColor - Returns the current HSVaColor object.
pickr.destroy():HSVaColor - Destroy's all functionality.
pickr.destroyAndRemove():HSVaColor - Destroy's all functionality, moreover it removes the pickr element including the button.
pickr.setColorRepresentation(type:String) - Change the current color-representation. Valid options are HEX, RGBA, HSVA, HSLA and CMYK, returns false if type was invalid.

Static methods

Pickr

Pickr.create(options:Object):Pickr - Creates a new instance.

Pickr.utils

once(element:HTMLElement, event:String, fn:Function[, options :Object]) - Attach an event handle which will be fired only once
on(elements:HTMLElement(s), events:String(s), fn:Function[, options :Object]) - Attach an event handler function.
off(elements:HTMLElement(s), event:String(s), fn:Function[, options :Object]) - Remove an event handler.
createElementFromString(html:String):HTMLElement - Creates an new HTML Element out of this string.
eventPath(evt:Event):[HTMLElement] - A polyfill for the event-path event propery.
removeAttribute(el:HTMLElement, name:String) - Removes an attribute from a HTMLElement and returns the value.
createFromTemplate(str:String) - See inline doumentation
adjustableInputNumbers(el:InputElement, negative:boolean) - Creates the possibility to change the numbers in an inputfield via mouse scrolling.

Contributing

If you want to open a issue, create a Pull Request or simply want to know how you can run it on your local machine, please read the Contributing guide.

ekeller/pickr