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

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, and convert between colors.

You can also use an AI color palette generator to explore palette directions before final UI cleanup.

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.

Alternatives:

• Accessible Color Picker – Coloris.js
• A Nicer Color Palette For The Web – Colors.css
• 10 Best Color Picker Plugins In JavaScript

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.