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

Category: Color , Javascript , Recommended | July 6, 2021
Views Total:4,349 views
Official Page:Go to website
Last Update:July 6, 2021


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, 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:


$ 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=""></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;
// set

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
// sets active color
// sets color
colorWheel.setColors([], activeColorIndex);
// resizes the color picker to a new size
// resets the color picker
// updates the color picker

Color methods.

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


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


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


  • v3.5.5: hotfix for hsl string parsing bug


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


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


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


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


  • v3.4.3: fix touch scrolling intervention in chrome


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


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

You Might Be Interested In:

5 thoughts on “Advanced & Beautiful HTML5 / Javascript Color Picker – iro.js

  1. pablo79

    Thank you for this script.
    Is it possible to send three RGB values to a POST function for some php script?

  2. James Daniel

    iro.js author here again — versions v5.3.2 onwards were released in 2021, not 2020. please could you fix this admin?


Leave a Reply