Color
require(["esri/Color"], function(Color) { /* code goes here */ });esri/ColorCreates a new color object by passing either a hex, rgb(a), hsl(a) or named color value. Hex, hsl(a) and named color values can be passed as a string:
// Examples for green
var color = new Color("green"); // named value
var color = new Color("#00FF00"); // hex value
var color = new Color("hsl(120, 100%, 50%)"); // hsl
var color = new Color("hsla(120, 100%, 50%, 0.5)"); // hsla
RGB values can be passed in as either an array, a string or an object:
// Examples for green
var color = new Color([0, 255, 0]);
var color = new Color([0, 255, 0, 0.5]);
var color = new Color("rgb(0, 255, 0)");
var color = new Color("rgba(0, 255, 0, 0.5)");
var color = new Color({r: 0, g: 255, b: 0});
var color = new Color({r: 0, g: 255, b: 0, a: 0.5});
The alpha-channel (opacity) in rgba and hsla can have a value between 0.0 (fully transparent) and 1.0 (fully opaque).
Autocasting support
As of version 4.5 of the ArcGIS API for JavaScript, autocasting is universally supported for color in the API. So there is no need to include this module in the require() and define() module loaders of your application unless you intend to use the static method(s) of this module.
For example, when creating a SimpleFillSymbol, you can define the color of the fill symbol with a Color object created from this class, or you can define it directly on the property with an hex, rgb(a) or hsl(a) value. See sample snippet below.
// Define symbol color using Color object
var sfs = {
type: "simple-fill", // autocasts as new SimpleFillSymbol()
color: new Color("#FF0000")
};
// Define symbol color directly using hex string
var sfs = {
type: "simple-fill", // autocasts as new SimpleFillSymbol()
color: "#FF0000" // autocasts as new Color()
};
Constructors
- new Color(color)
- Parameter:
The color to create. This parameter can be a string representing a named color or a hex value; an array of three or four numbers representing r, g, b, a values; or an object with r, g, b, a properties.
Example:// Creates a green Color object using a named value var color = new Color("green"); // Creates a green Color object using a hex value var color = new Color("00FF00"); // Creates a new Color object using an array of r, g, b values var color = new Color([125, 255, 13]); // Add a fourth value to the array to add opacity (range between 0 and 1) var color = new Color([125, 255, 13, 0.5]); // Creates a new Color object using an object var color = new Color({ r: 125, g: 255, b: 13, a: 0.3 // Optional });
Property Overview
| Name | Type | Summary | Class | |
|---|---|---|---|---|
| Number | The alpha value. more details | more details | Color | |
| Number | The blue value. more details | more details | Color | |
| Number | The green value. more details | more details | Color | |
| Number | The red value. more details | more details | Color |
Property Details
- a Number
The alpha value. This value can be any number between
0and1and represents the opacity of the Color.0indicates the color is fully transparent and1indicates it is fully opaque.
- b Number
The blue value. This value can range between
0and255.
- g Number
The green value. This value can range between
0and255.
- r Number
The red value. This value can range between
0and255.
Method Overview
| Name | Return Type | Summary | Class | |
|---|---|---|---|---|
| Color | Creates a Color instance by blending two colors using a weight factor. more details | more details | Color | |
| Color | Creates a deep clone of the Color instance. more details | more details | Color | |
| Color | Creates a Color instance using a 3 or 4 element array, mapping each element in sequence to the rgb(a) values of the color. more details | more details | Color | |
| Color | Creates a Color instance from a hex string with a '#' prefix. more details | more details | Color | |
| Color | Creates a new Color instance, and initializes it with values from a JSON object. more details | more details | Color | |
| Color | Creates a Color instance from a string of the form "rgb()" or "rgba()". more details | more details | Color | |
| Color | Creates a Color instance by parsing a generic string. more details | more details | Color | |
| Color | Takes an array of rgb(a) values, named string, hex string or an hsl(a) string, an object with | more details | Color | |
| String | Returns a CSS color string in rgba form representing the Color instance. more details | more details | Color | |
| String | Returns a CSS color string in hexadecimal form that represents the Color instance. more details | more details | Color | |
| Object | Returns a JSON object with all the values from a Color instance. more details | more details | Color | |
| Number[] | Returns a 3-component array of rgb values that represent the Color instance. more details | more details | Color | |
| Number[] | Returns a 4-component array of rgba values that represent the Color instance. more details | more details | Color |
Method Details
Creates a Color instance by blending two colors using a weight factor. Optionally accepts a Color object to update and return instead of creating a new object.
Parameters:start ColorThe start color.
end ColorThe end color.
weight NumberThe weight value is a number from 0 to 1, with 0.5 being a 50/50 blend.
out ColoroptionalA previously allocated Color object to reuse for the result.
Returns:Type Description Color Returns a new Color object. Example:var startColor = new Color("#0000FF"); var endColor = new Color("#CA0013"); var blendedColor = Color.blendColors(startColor, endColor, 0.5);
- clone(){Color}
Creates a deep clone of the Color instance.
Returns:Type Description Color A deep clone of the Color instance. Example:// Creates a deep clone of the graphic's color var colorClone = graphic.symbol.color.clone();
Creates a Color instance using a 3 or 4 element array, mapping each element in sequence to the rgb(a) values of the color. Optionally accepts a Color object to update with the color value and return instead of creating a new object.
Parameters:The input array.
obj ColoroptionalA previously allocated Color object to reuse for the result.
Returns:Type Description Color Returns a new Color object. Example:var redColor = Color.fromArray([201, 0, 19]);
Creates a Color instance from a hex string with a '#' prefix. Supports 12-bit #rgb shorthand. Optionally accepts a Color object to update with the parsed value and return instead of creating a new object.
Parameters:color StringThe input color in a hex string.
obj ColoroptionalA previously allocated Color object to reuse for the result.
Returns:Type Description Color Returns a new Color object. Example:var redColor = Color.fromHex("#CA0013");
Creates a new Color instance, and initializes it with values from a JSON object.
Parameter:json ObjectA JSON representation of the instance.
Returns:Type Description Color A new Color instance.
Creates a Color instance from a string of the form "rgb()" or "rgba()". Optionally accepts a Color object to update with the parsed value and return instead of creating a new object.
Parameters:color StringThe input color in a string of the form "rgb()" or "rgba()".
out ColoroptionalA previously allocated Color object to reuse for the result.
Returns:Type Description Color Returns a new Color object. Example:var redColor = Color.fromRgb("rgb(202,0,19)");
Creates a Color instance by parsing a generic string. Accepts hex, rgb, and rgba style color values. Optionally accepts a Color object to update with the parsed value and return instead of creating a new object.
Parameters:str StringThe input value.
obj ColoroptionalA previously allocated Color object to reuse for the result.
Returns:Type Description Color Returns a new Color object. Example:var redColor = Color.fromString("blue");
- setColor(color){Color}
Takes an array of rgb(a) values, named string, hex string or an hsl(a) string, an object with
r,g,b, andaproperties, or a Color object and sets this color instance to the input value.Parameter:The new color value. This parameter can be a string representing a named color or a hex value; an array of three or four numbers representing r, g, b, a values; or an object with r, g, b, a properties.
Returns:Type Description Color Sets the Color instance used to call this method to the new color.
- toCss(includeAlpha){String}
Returns a CSS color string in rgba form representing the Color instance.
Parameter:includeAlpha BooleanoptionalIf
true, the alpha value will be included in the result.Returns:Type Description String A CSS color string in rgba form that represents the Color instance used to call this method.
- toHex(){String}
Returns a CSS color string in hexadecimal form that represents the Color instance.
Returns:Type Description String A CSS color string in hexadecimal form that represents the Color instance used to call this method.
- toJSON(){Object}
Returns a JSON object with all the values from a Color instance.
Returns:Type Description Object A JSON representation of the Color instance.