Small, fast, dependency free JavaScript color library with support for the RGB, RYB, and HSL color models and easy interaction with HTML, CSS, and third party frameworks.
Features
- Internal calls don't allocate memory, reducing garbage collector activity.
- Color conversion between color models.
- Support for color mixing and color alteration (mix, add, subtract, brighten, darken, grayscale, etc.)
- Hue shifting around the more traditional artistic RYB (red, yellow, blue) color wheel, creating much more natural complementary colors and intuitive palettes, see online example.
- Works alongside other popular frameworks, such as Three.js. See example below of passing data between
IrisandTHREE.Color.
- Option 1: Copy file
Iris.jsto project, import from file...
import { Iris } from 'Iris.js';- Option 2: Install from npm, import from '@scidian/iris'...
npm install @scidian/iris
import { Iris } from '@scidian/iris';- Option 3: Import directly from CDN...
import { Iris } from 'https://unpkg.com/@scidian/iris/build/iris.module.js';new Iris(); // Defaults to white, 0xffffff
new Iris(0xff0000); // Hexadecimal (0xff0000, i.e. 16711680)
new Iris(1.0, 0.0, 0.0); // RGB Values (0.0 to 1.0)
new Iris(255, 0, 0, 'rgb'); // RGB Values (0 to 255)
new Iris(255, 0, 0, 'ryb'); // RYB Values (0 to 255)
new Iris(360, 1.0, 0.5, 'hsl'); // HSL Values (H: 0 to 360, SL: 0.0 to 1.0)
new Iris({ r: 1.0, g: 0.0, b: 0.0 }); // Object, RGB Properties (0.0 to 1.0)
new Iris({ r: 1.0, y: 0.0, b: 0.0 }); // Object, RYB Properties (0.0 to 1.0)
new Iris({ h: 1.0, s: 1.0, l: 0.5 }); // Object, HSL Properties (0.0 to 1.0)
new Iris([ 1.0, 0.0, 0.0 ], offset); // RGB Array (0.0 to 1.0), optional offset
new Iris('#ff0000'); // Hex String (also 3 digits: '#f00')
new Iris('rgb(255, 0, 0)'); // CSS Color String
new Iris('red'); // X11 Color Name
new Iris(myIrisColor); // Copy from Iris Color Object
new Iris(myThreeColor); // Copy from Three.js Color Objectconst color = new Iris(0xff0000);
console.log(color.rybRotateHue(270).darken(0.5).hexString().toUpperCase());-
output
#2E007F
const color = new Iris(0xff0000);
// To find the RYB color wheel complement (opposite) color
const complement = new Iris.set(color).rybComplementary();
// To adjust hue a specific number of degrees (0 to 360) around the RYB color wheel
const tetrad1 = new Iris.set(color).rybRotateHue(90);
const tetrad2 = new Iris.set(color).rybRotateHue(270);Example usage alongside Three.js
// Some possible ways to initialize Iris using THREE.Color
const eyeColor = new Iris(threeColor);
const eyeColor = new Iris(threeColor.getHex());
const eyeColor = new Iris(threeColor.toArray());
// Some possible ways to initialize THREE.Color using Iris
const threeColor = new THREE.Color(eyeColor);
const threeColor = new THREE.Color(eyeColor.hex());
const threeColor = new THREE.Color(eyeColor.hexString());
// Some possible ways to copy the values of the THREE.Color back to Iris
eyeColor.copy(threeColor);
eyeColor.set(threeColor.getHex());
eyeColor.setRGBF(threeColor.r, threeColor.g, threeColor.b);
// Some possible ways to copy the values of the Iris back to THREE.Color
threeColor.copy(eyeColor);
threeColor.setHex(eyeColor.hex());
threeColor.setRGB(eyeColor.r, eyeColor.g, eyeColor.b);.r : Float
Red channel value between 0.0 and 1.0, default is 1.
.g : Float
Green channel value between 0.0 and 1.0, default is 1.
.b : Float
Blue channel value between 0.0 and 1.0, default is 1.
.copy ( colorObject : Iris or THREE.Color ) ( ) : this
Copies the r, g, b properties from colorObject. This Object can be any type as long as it has r, g, b properties containing numeric values ranging from 0.0 to 1.0.
.clone ( ) : Iris
Returns a new Iris Object with the same color value as this Iris Object.
.set ( r: Number or Object or Array or String, g : Number, b : Number, type : String ) : this
All arguments are optional. Sets this color based on a wide range of possible inputs, all options are the same as with the constructor.
.setColorName ( style : String ) : this
Sets this color based on a X11 color name.
.setHex ( hexColor : Integer ) : this
Sets this color based on a hexidecimal / decimal value (i.e. 0xff0000 or 16711680).
.setHSL ( h : Integer, s: Float, l: Float ) : this
Sets this color based on hue (0 to 360), saturation (0.0 to 1.0), and lightness (0.0 to 1.0) values.
.setRandom ( ) : this
Sets this color to a random color.
.setRGB ( r : Number, g: Number, b: Number ) : this
Sets this color based on a red, green, and blue values ranging from 0 to 255.
.setRGBF ( r : Float, g: Float, b: Float ) : this
Sets this color based on a red, green, and blue values ranging from 0.0 to 1.0.
.setRYB ( r : Integer, g: Integer, b: : Integer ) : this
Sets this color based on a red, yellow, and blue values ranging from 0 to 255.
.setScalar ( scalar: Integer ) : this
Sets this colors red, green, and blue values all equal to a singular value ranging from 0 to 255.
.setScalarF ( scalar : Float ) : this
Sets this colors red, green, and blue values all equal to a singular value ranging from 0.0 to 1.0.
.setStyle ( style : String ) : this
Sets this color based on CSS ('rgb(255,0,0)' / 'hsl(360,50%,50%)'), Hex ('#FF0000'), or X11 ('darkred') strings.
.cssString ( alpha : Integer ) : String
Returns string for use with CSS, for example "rgb(255, 0, 0)". Optionally include an alpha value from 0 to 255 to be included with the string, for example "rgba(255, 0, 0, 255)".
.hex ( ) : Integer
Returns value as hexidecimal.
.hexString ( hexColor : Integer ) : String
Returns value as hex string for use in CSS, HTML, etc. Example: "#ff0000". If optional hexColor is supplied, the returned string will be for the supplied color, not the underlying value of the current Iris Object.
.rgbString ( alpha : Integer ) : String
Returns value as inner section of cssString(). For example "255, 0, 0". This allows you to write to CSS variables for use with custom alpha channels in your CSS. Optional alpha value.
.toJSON ( ) : Integer
Returns value as hexidecimal, JSON friendly data.
.getHSL ( target ) : Object
Provide an optional target to copy hue, saturation, lightness values into, they will be in the range 0.0 to 1.0. If no target is provided a new Object with h, s, l properties is returned.
.getRGB ( target ) : Object
Provide an optional target to copy red, green, blue values into, they will be in the range 0.0 to 1.0. If no target is provided a new Object with r, g, b properties is returned.
.getRYB ( target ) : Object
Provide an optional target to copy red, yellow, blue values into, they will be in the range 0.0 to 1.0. If no target is provided a new Object with r, y, b properties is returned.
.toArray ( array : Array, offset : Integer ) : Array
Provide an optional array to copy red, green, blue values into, they will be in the range 0.0 to 1.0. Optionally provide an offset to specify where in the array to write the data. If no array is provided a new Array will be returned.
.red ( ) : Integer
Returns red value of current Iris object in range 0 to 255.
.green ( ) : Integer
Returns green value of current Iris object in range 0 to 255.
.blue ( ) : Integer
Returns blue value of current Iris object in range 0 to 255.
.redF ( ) : Float
Returns red value of current Iris object in range 0.0 to 1.0.
.greenF ( ) : Float
Returns green value of current Iris object in range 0.0 to 1.0.
.blueF ( ) : Float
Returns blue value of current Iris object in range 0.0 to 1.0.
.hue ( ) : Integer
Returns hue value of current Iris object in range 0 to 360.
.saturation ( ) : Float
Returns saturation value of current Iris object in range 0.0 to 1.0.
.lightness ( ) : Float
Returns lightness value of current Iris object in range 0.0 to 1.0.
.hueF ( ) : Float
Returns hue value of current Iris object in range 0.0 to 1.0.
.hueRYB ( ) : Integer
Returns the RYB adjusted hue value of current Iris object in range 0 to 360.
.add ( color : Iris ) : this
Adds the red, green, blue values from color to this Iris Object's values.
.addScalar ( scalar : Integer ) : this
Adds the value scalar to the red, green, blue of this Iris Object, scalar should be in range -255 to 255.
.addScalarF ( scalar : Float ) : this
Adds the value scalar to the red, green, blue of this Iris Object, scalar should be in range -1.0 to 1.0.
.brighten ( amount : Float ) : this
Increases the lightness of this Iris Object by amount as a percentage of the remainder of 100% lightness less the current lightness. For example, if the current hsl lightness value is 0.6 (between 0.0 and 1.0), an amount of 0.5 will increase the lightness value to 0.6 + ((1.0 - 0.6) * 0.5) = 0.8, an amount value of 1.0 will always bring lightness value up to 1.0 (100%).
.darken ( amount : Float ) : this
Decreases the lightness of this Iris Object by amount. A value of 0.5 (default) will decrease lightness by 50%, a value of 2.0 will double lightness.
.grayscale ( percent : Float, type : String ) : this
Changes color into grayscale by percent ranging from 0.0 to 1.0. This can be done by type 'average' which takes an average of the red, green, blue values. Or by default type of 'luminosity' which scales red, green, blue values according to how human eyes see color (see details at GIMP).
.hslOffset ( h : Integer, s : Float, l : Float ) : this
Change the HSL values of this Iris object by h (-360 to 360), s (-1.0 to 1.0), and l (-1.0 to 1.0).
.mix ( mixColor : Iris, percent : Float ) : this
Mixes in another Iris Object's color value to this Iris Object by percent (default of 0.5, i.e. 50%).
.multiply ( color : Iris ) : this
Multiplies another Iris Object's RGB values to this Iris Object's RGB values.
.multiplyScalar ( scalar : Float ) : this
Multiplies this Iris Object's RGB values by scalar. There is no range for scalar, however, color values will be clamped between 0.0 and 1.0 after multiplication.
.rgbComplementary ( ) : this
Adjusts this color to be 180 degress (opposite) of the current color on the RGB color wheel.
.rgbRotateHue ( degrees : Integer ) : this
Adjusts this color to be degress of the current color on the RGB color wheel, range from -360 to 360.
.rybAdjust ( ) : this
Adjusts the RGB values to fit in the RYB spectrum as best as possible.
.rybComplementary ( ) : this
Adjusts this color to be 180 degress (opposite) of the current color on the RYB color wheel.
.rybRotateHue ( degrees : Integer ) : this
Adjusts this color to be degress of the current color on the RYB color wheel, range from -360 to 360.
.subtract ( color : Iris ) : this
Subtracts the red, green, blue values from color to this Iris Object's values.
.equals ( color : Iris ) : Boolean
Returns true if the RGB values of color are the same as those of this Object.
.isDark ( color : Iris ) : Boolean
Returns true if this Iris Object's color value would be considered "dark", helpful for determining whether of not to use black or white text with this color as a background.
.isLight ( color : Iris ) : Boolean
Returns true if this Iris Object's color value would be considered "light", helpful for determining whether of not to use black or white text with this color as a background.