Advanced & Beautiful HTML5 / Javascript Color Picker – iro.js

Preview:

Description:

iro.js is a sleek, HSV color based JavaScript color picker for generating a pretty, HTML5 canvas based color wheel UI with touch support.

Also provides API methods that allow you to set, update, convert between colors.

More Features:

• Supports any color formats: Hex, Hex alpha, RGB, RGBA, RGB object, RGBA object, HSL, HSLA, HSL object, HSLA object, HSV object, HSVA.
• Multi-color Selections.
• Supports 3 layouts: Wheel, Slider, Box.

Table Of Contents:

• Basic Usage
• Options
• Set & Get Colors
• API Methods
• Events

Installation:

# NPM
$ npm install @jaames/iro --save

How to use it:

Import the iro.js as an ES module.

import iro from "@jaames/iro";

Or add the core JavaScript library to the html page:

<!-- From dist folder -->
<script src="dist/iro.js"></script>
<!-- Or from a CDN -->
<script src="https://cdn.jsdelivr.net/npm/@jaames/iro"></script>

Create a placeholder element for the color picker.

<div class="wheel" id="colorWheelDemo"></div>

Generate a basic color picker inside the container ‘colorWheelDemo’.

var colorWheel = new iro.ColorPicker("#colorWheelDemo", {
    // options here
});

Customize the layout of the color picker. It currently comes with 3 layouts:

• Wheel
• Slider
• Box

var colorWheel = new iro.ColorPicker("#colorWheelDemo", {
    layout: [
    { 
      component: iro.ui.Wheel,
      options: {
        wheelLightness: true,
        wheelAngle: 0,
        wheelDirection: "anticlockwise"
      } 
    },
    {
      component: iro.ui.Box,
      options: {
        // see below
      }
    },
    {
      component: iro.ui.Slider,
      options: {
        sliderType: 'hue' // can also be 'saturation', 'value', 'alpha' or 'kelvin',
        sliderShape: 'circle',
        activeIndex: 2
      }
    }
    ]
  
});

Possible options to customize your color picker.

var colorWheel = new iro.ColorPicker("#colorWheelDemo", {
    // width of the color picker
    width: 300,
    // initial color
    color: '#fff',
    // initial colors used for multi-color selections.
    colors: null,
    // CSS display value
    display: 'block', 
    // unique id of the color picker
    id: null,
    // custom the layout
    layout: null,
    // or 'horizontal'
    layoutDirection: "vertical",
    // border width
    borderWidth: 0,
    // border color
    borderColor: '#fff',
    // space between handles
    padding: 4,
    // radius of handles
    handleRadius: 8,
    // override the radius of active color handles
    activeHandleRadius: null,
    // Custom handle SVG
    handleSvg: null,
    // custom handle props
    handleProps: {
      x: 0,
      y: 0
    },
    // fade to black when the lightness decreases
    wheelLightness: true,
    // starting angle 
    wheelAngle: 0, 
    // clockwise/anticlockwise
    wheelDirection: 'anticlockwise', 
    // slider size
    sliderSize: undefined,
    // distance between the wheel and the slider controls
    sliderMargin: 12
  
});

Get & set the color in a given format. Supported color formats:

• hexString: “#ff0000”
• hex8String: “#ff0000ff”
• rgb: { r: 255, g: 0, b: 0 }
• rgba: { r: 255, g: 0, b: 0, a: 1 }
• rgbString: “rgb(255, 0, 0)”
• rgbaString: “rgb(255, 0, 0, 1)”
• hsl: { h: 360, s: 100, l: 50 }
• hsla: { h: 360, s: 100, l: 50, a: 1 }
• hslString: “hsl(360, 100%, 50%)”
• hslaString: “hsla(360, 100%, 50%, 1)”
• hsv: { h: 360, s: 100, v: 100 }
• hsva: { h: 360, s: 100, v: 100, a: 1 }
• red: 0 to 255
• green: 0 to 255
• blue: 0 to 255
• alpha: 0 to 1
• hue: 0 to 360
• saturation: 0 to 100
• value: 0 to 100
• kelvin: 1000 to 40000

// get
var myColor = colorWheel.color.COLORFORMAT;
console.log(myColor);
// set
colorWheel.color.COLORFORMAT = STRING OR OBJECT

Event handlers available.

colorWheel.on('color:change', function(color, changes){
  // when the color has changed, the callback gets passed the color object and an object providing which color channels (out of H, S, V) have changed.
})
colorWheel.on('color:init', function(color){
  // same as color:change, but only fired once with the initial color value provided to the color picker.
})
colorWheel.on('color:remove', function(color){
  // when a color is removed from the color picker
})
colorWheel.on('input:change', function(color, changes){
  // Similar to color:change, except this is only fired whenever the color is changed with direct user input. 
})
colorWheel.on('input:start', function(color){
  // when the user starts interacting with the color picker, the callback gets passed the color object
})
colorWheel.on('input:move', function(color){
  // when the user moves their pointer/mouse after beginning interaction
})
colorWheel.on('input:end', function(color){
  // when the user has finished interacting with the color picker, the callback gets passed the color object
})
colorWheel.on('mount', function(color){
  // fired once the color picker UI has been mounted into the DOM
})

Color picker methods.

// adds color
colorWheel.addColor(IroColorValue, colorIndex(optional));
// removes color
colorWheel.removeColor(colorIndex);
// sets active color
colorWheel.setActiveColor(colorIndex);
// sets color
colorWheel.setColors([], activeColorIndex);
// resizes the color picker to a new size
colorWheel.resize(width);
// resets the color picker
colorWheel.reset();
// updates the color picker
colorWheel.forceUpdat();

Color methods.

// sets color
myColor.set(color);
// sets color chanel
// myColor.setChannel(format, channel, value);
myColor.setChannel('rgb', 'r', 255);
// clones color
myColor.clone(color);
// resets color
myColor.reset();
// converts HSV to RGB
myColor.hsvToRgb(HSV);
// converts RGB to HSV
myColor.rgbToHsv(RGB);
// converts HSV to HSL
myColor.hsvToHsl(HSV);
// converts HSL to HSV
myColor.hslToHsv(HSL);
// converts kelvin temperature to RGB
myColor.kelvinToRgb(kelvin temperature);
// converts RGB to kelvin temperature
myColor.kelvinToRgb(RGB);

Changelog:

v5.5.2 (07/06/2021)

• Fixed an issue where the alpha channel wasn’t being copied over when creating a new iro.Color instance from the value of an old one
• Fixed an issue where the iro.Color hslaString attribute wasn’t returning a hsla string

v5.5.1 (04/10/2021)

• fix handle glitch

v5.5.0 (03/27/2021)

• Added activeHandleRadius ColorPicker option for overriding the radius of active color handles.
• Added kelvin object option for a Color’s constructor and set() method.
• Fixed an issue where calling a ColorPicker’s resize() or setOptions() methods directly after another state update (e.g addColor, removeColor, setColors, etc) would cause the color picker to lock up.
• Prevented ColorWheel events from being registered if they began inside the wheel’s square hitbox, but not inside the circular boundaries of the wheel.

v5.4.0 (03/21/2021)

• refactor UI to use HTML, misc fixes

v5.3.2 (02/19/2021)

• Adds optional second activeColorIndex param to ColorPicker.setColors()
• Fixes IE11 event issue

v5.3.1 (11/26/2020)

• NPM package for 5.3.0 missing iro-core 1.0.5 updates

v5.3.0 (09/08/2020)

• Added optional boxHeight option for setting the height of the box component
• Added id option for all components, which will get passed to the input:start, input:move and input:end event callbacks as a second param
• Various fixes

v5.2.3 (09/08/2020)

• Bumps iro-core version to fix server-side environment issues

v5.2.2 (08/27/2020)

• fix dist/ColorPicker.d.ts filename

v5.2.1 (08/26/2020)

• fix touch events on touchscreen PC/laptop

v5.2.0 (08/16/2020)

• Add slider types for red, green and blue color channels

v5.1.10 (08/15/2020)

• Fixes issue with kelvin -> RGB conversion that resulted in the red channel overflowing the 0-255 range in certain cases.

v5.1.9 (08/01/2020)

• Adds activeIndex option for Slider and Box components, for manually specifying which color to use in multi-color setups

v5.1.8 (04/30/2020)

• Fixes Typescript issues
• Re-adds iro.version since it was accidentally omitted in 5.1.7

v5.1.6 (04/18/2020)

• Fixes package.json to include Typescript typedef files

v5.1.5 (03/02/2020)

• Added margin color picker option for setting the gap between individual components.
• sliderMargin will also work for now, but will be deprecated in a later version.

v5.1.4 (03/01/2020)

• internal tweaks to prevent all events from causing infinite loops

v5.1.3 (02/29/2020)

• Added transparency option, made it easier to style handles individually

v5.1.2 (02/27/2020)

• Rewritten in typescript.
• Options, events, methods updated.
• Doc updated.
• Demo updated

v4.5.3 (10/22/2019)

• fix SVG gradient rendering for iOS WebViews

v4.5.2 (10/19/2019)

• Fix SVG gradient rendering when used in an Ionic Webview

v4.5.1 (06/09/2019)

• Hotfix: fixes rendering bug caused when the color was updated before the picker was mounted into the DOM

v4.5.0 (05/27/2019)

• Added a new param for iro.ColorPicker: id – HTML ID for the color picker root element, also available as a prop on the color picker instance
• Color picker event callbacks this context is now set to the active color picker instance

v4.3.4 (05/10/2019)

• Added wheelAngle – starting angle for the color wheel’s hue gradient
• Added wheelAnglewheelDirection – direction of the color wheel’s hue gradient (clockwise/anticlockwise)

v4.3.3 (04/14/2019)

• Fixes an issue where the alpha component wasn’t being parsed correctly from rgba and hsla strings.

v4.3.2 (04/12/2019)

• hotfix: input:change wasn’t firing

v4.3.1 (04/09/2019)

• Fixes a few issues related to how color alpha/transparency was handled internally, which was causing problems with iro-transparency-plugin. Setting a color to a value without an alpha component (e.g hexString = “#fff”) will now set the alpha value to 1, and the alpha component will no longer be undefined when using new iro.Color.

v4.3.0 (04/08/2019)

• Added input:change – The same as color:change, but only fires when the color has been set with user input
• Added color:init – Same as color:change, but fired once with the initial color value
• on and off methods can now take arrays of eventTypes as well as strings
• New deferredEmit method (should only be used by plugins)
• The color:change event no longer fires with the initial color value, as this was catching a few people out. make sure to listen for both color:init and color:change events with the same listener

v4.2.2 (03/27/2019)

• Makes sure that input:start fires before color:update and that input:end fires after color:update.

v4.2.1 (03/19/2019)

• Fixes color picker DOM event handling in IE11

v4.2.0 (03/12/2019)

• Internal plugin API changes to allow for plugins to customise the slider type
• Adds support for hue and saturation sliders

v4.0.3 (03/07/2019)

• add slider getValueFromPoint to make plugin dev a bit easier

v4.0.2 (03/02/2019)

• fire color:change if registered before color picker was mounted

v4.0.0 (02/23/2019)

• Custom SVG handles
• Custom layout config options
• Updated Plugin API
• Code tests
• Rewritten codebase, is now much cleaner
• Color picker components are now built using preact
• Rewritten documentaion and readme, which huge focus on making things easier to follow

02/02/2019

• v3.5.6: hotfix for svg url generation in older iOS webviews

01/28/2019

• v3.5.5: hotfix for hsl string parsing bug

12/23/2018

• v3.5.4: hotfix for black output on mobile and desktop Safari

10/02/2018

• v3.5.3: Fixed small issue with parent container size

09/24/2018

• v3.5.2: Improve workaround for broken gradient URLs in Safari

08/17/2018

• v3.5.0: Rewritten API classes using the es6 syntax

08/12/2018

• v3.4.3: fix touch scrolling intervention in chrome

08/08/2018

• v3.4.2: Fixes a warning caused by some recent Chrome changes

08/02/2018

• v3.4.1: Fixed rounding issues when converting between color models, particularly when converting certain colors from RGB hex -> HSL -> RGB hex.