Skip to Content | Skip to Navigation


dojo/_base/Color

Authors:Marcus Reimann, Bill Keese, JJ Kress
Developers:Eugene Lazutkin, Adam Peller, Alex Russell

dojo._base.Color contains functions for setting Colors.

The Color object provides a unified way to store colors, which holds the color in rgba form. This simplifies dealing with the different ways to define colors as everyone can use the format they are most comfortable with. Color objects can be used directly as a value to the various color attributes.

Usage

As with the rest of dojo/_base modules, if you are running the Dojo loader in legacy mode (async: false) this module is automatically loaded. Even if it is automatically loaded, you should require it in to have access to its features:

require(["dojo/_base/Color"], function(Color){
  // Color contains functions
});

Features

Methods

MethodReturnsDescription
blendColors(start,end,weight,obj)undefined

Blend colors end and start with weight from 0 to 1, 0.5 being a 50/50 blend, can reuse a previously allocated Color object for the result

constructor(color)dojo/_base/Color

Takes a named string, hex string, array of rgb or rgba values, an object with r, g, b, and a properties, or another Color object and creates a new Color instance to work from.

fromArray(a,obj)any|undefined

Builds a Color from a 3 or 4 element array, mapping each element in sequence to the rgb(a) values of the color.

fromHex(color,obj)any

Converts a hex string with a '#' prefix to a color object. Supports 12-bit #rgb shorthand. Optionally accepts a Color object to update with the parsed value.

fromString(str,obj)any

Parses str for a color value. Accepts hex, rgb, and rgba style color values.

Acceptable input values for str may include arrays of any form accepted by dojo.colorFromArray, hex strings such as "#aaaaaa", or rgb or rgba strings such as "rgb(133, 200, 16)" or "rgba(10, 10, 10, 50)"

setColor(color)function

Takes a named string, hex string, array of rgb or rgba values, an object with r, g, b, and a properties, or another Color object and sets this color instance to that value.

toCss(includeAlpha)string

Returns a css color string in rgb(a) representation

toHex()string

Returns a CSS color string in hexadecimal representation

toRgb()Array

Returns 3 component array of rgb values

toRgba()Array

Returns a 4 component array of rgba values from the color represented by this object.

toString()undefined

Returns a visual representation of the color

Properties

PropertyTypeDescription
namedobject

Dictionary list of all CSS named colors, by name. Values are 3-item arrays with corresponding RG and B values.

Note: named only contains the 16 named colors defined by the HTML4 standard. If you need all named colors from the CSS3 standard you have to require dojo/colors.

Examples

Creating with the Constructor

A new color object is either created by using the constructor or any of the utility functions. Next are some examples of using the constructor with different arguments:

require(["dojo/_base/Color"], function(Color){ // AMD allows us to use the color functions under the alias name
"Color"

  // Creates an empty color object for later use
  var emptyColor = new Color();

  // Constructor accepts named colors
  var namedColor = new Color("purple");

  // Hex Strings work also
  var hexColor = new Color("#cdefa0");

  // One can also pass arrays containing 3 or 4 values
  var a3Color = new Color([123, 123, 234]);
  var a4Color = new Color([123, 123, 234, 0.6]);

  // Finally, objects with r,g,b and a values work as well
  var objColor = new Color({ r:23, g:45, b:67, a:0.7 });
});

Using the from Utility Functions

All these expressions result in the same value, a dojo/_base/Color object representing red with no transparency ( full opacity):

require(["dojo/_base/Color"],function(Color){
  Color.fromHex("#FF0000");
  Color.fromHex("#F00");
  Color.fromArray([255, 0, 0]);
  Color.fromArray([255, 0, 0, 1]);
  Color.fromRgb("rgb(255, 0, 0)");
  Color.fromRgb("rgba(255, 0, 0, 1)");
  Color.fromString("red");
  // as mentioned above, you could also pass a hex string or an rgb(a) string
});

Blending Colors

dojo/_base/Color supports a blend function that can blend two Color instances together with a weighting, to produce a new color.

require(["dojo/_base/Color"], function(Color){
  Color.blendColors(start, end, weight, color);
});

Return a Specific Format

The Color object also provides some methods to return the color in a desired format: toRgb(), toRgba(), toHex(), toCss() and toString().

require(["dojo/_base/Color"], function(Color){
  // First create a color object, containing red
  var myColor = Color.colorFromString("red");

  // Now return the color with the object methods
  myColor.toRgb();  // returns the Array [255,0,0]
  myColor.toRgba(); // returns the Array [255,0,0,1]
  myColor.toHex(); // returns the String "#ff0000"
  myColor.toCss(false); // returns the String "rgb(255,0,0)"
  myColor.toCss(true); // returns the String "rgba(255,0,0,1)"
  myColor.toString(); // returns the String "rgba(255,0,0,1)"
});

Although the last two lines are equivalent, you should use the method that fits to the context to maintain readability.

Using the Color Object as a Value

The last example shows how one can use the Color object directly to change the properties of an element:

require(["dojo/_base/Color", "dom-stlye"], function(Color, style){
  var myColor = Color.fromString("red");
  style.set("someId", "backgroundColor", myColor);
  // This changes the background-color of the element "someId" to the color specified in myColor
});

See Also