require(["esri/Color"], (Color) => { /* code goes here */ });
import Color from "@arcgis/core/Color.js";
esri/Color
Creates 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
let color = new Color("lime"); // named value
let color = new Color("#0F0"); // shortened three digit hexadecimal value
let color = new Color("#00FF00"); // six digit hexadecimal value
let color = new Color("hsl(120, 100%, 50%)"); // hsl
let 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
let color = new Color([0, 255, 0]);
let color = new Color([0, 255, 0, 0.5]);
let color = new Color("rgb(0, 255, 0)");
let color = new Color("rgba(0, 255, 0, 0.5)");
let color = new Color({r: 0, g: 255, b: 0});
let 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).
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 let color = new Color("green"); // Creates a green Color object using a hex value let color = new Color("#00FF00"); // Creates a new Color object using an array of r, g, b values let color = new Color([125, 255, 13]); // Add a fourth value to the array to add opacity (range between 0 and 1) let color = new Color([125, 255, 13, 0.5]); // Creates a new Color object using an object let 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 | Color | |
Number | The blue value. more details | Color | |
Number | The green value. more details | Color | |
Number | The red value. more details | Color |
Property Details
-
a Number
-
The alpha value. This value can be any number between
0
and1
and represents the opacity of the Color.0
indicates the color is fully transparent and1
indicates it is fully opaque.
-
b Number
-
The blue value. This value can range between
0
and255
.
-
g Number
-
The green value. This value can range between
0
and255
.
-
r Number
-
The red value. This value can range between
0
and255
.
Method Overview
Name | Return Type | Summary | Class |
---|---|---|---|
Color | Creates a Color instance by blending two colors using a weight factor. more details | Color | |
Color | Creates a deep clone of the Color instance. 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 | Color | |
Color | Creates a Color from hexadecimal string. more details | Color | |
Color | Creates a new Color instance, and initializes it with values from a JSON object. more details | Color | |
Color | Creates a Color instance from a string of the form "rgb()" or "rgba()". more details | Color | |
Color | Creates a Color instance by parsing a generic string. more details | Color | |
Color | Takes an array of rgb(a) values, named string, hex string or an hsl(a) string, an object with | Color | |
String | Returns a CSS color string in rgba form representing the Color instance. more details | Color | |
String | Returns the color in hexadecimal format. more details | Color | |
Object | Returns a JSON object with all the values from a Color instance. more details | Color | |
Number[] | Returns a 3-component array of rgb values that represent the Color instance. more details | Color | |
Number[] | Returns a 4-component array of rgba values that represent the Color instance. 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.
Parametersstart 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.
ReturnsType Description Color Returns a new Color object. Exampleconst startColor = new Color("#0000FF"); const endColor = new Color("#CA0013"); const blendedColor = Color.blendColors(startColor, endColor, 0.5);
-
clone(){Color}
-
Creates a deep clone of the Color instance.
ReturnsType Description Color A deep clone of the Color instance. Example// Creates a deep clone of the graphic's color let 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.
ParametersThe input array.
t ColoroptionalA previously allocated Color object to reuse for the result.
ReturnsType Description Color Returns a new Color object. Examplelet redColor = Color.fromArray([201, 0, 19]);
-
-
Creates a Color from hexadecimal string.
Colors can be expressed as:
- Hex triplet, a six or eight digit hexidecimal number. For example:
- "#FFFF00" for Yellow, or
- "#DC143C20" for a semi-transparent Crimson
- Shorthand variant, a three or four digit hexidecimal number. For example:
- "#F0F" for Fuchsia, or
- "#FFF8" for semi-transparent white
Hexadecimal numbers must be prefixed with the number (or "hash") sign (#). Strings can be upper or lower case.
This static method returns a new Color object. Optionally the method accepts an existing color instance that is updated and returned.
Parametershex StringThe input color in a hexadecimal string.
color ColoroptionalA previously allocated Color object to reuse for the result.
ReturnsType Description Color Returns a new Color object or updated color object (if parsed). Exampleconst red = Color.fromHex("#FF0000"); // Color from hex triplet const blue = Color.fromHex("#00F"); // Color from hex shorthand const green = Color.fromHex("#00FF0080"); // Color with 50% transparency
- Hex triplet, a six or eight digit hexidecimal number. For example:
-
-
Creates a new Color instance, and initializes it with values from a JSON object.
Parameterjson ObjectA JSON representation of the instance.
ReturnsType 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.
Parameterscolor StringThe input color in a string of the form "rgb()" or "rgba()".
out ColoroptionalA previously allocated Color object to reuse for the result.
ReturnsType Description Color Returns a new Color object. Exampleconst 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.
Parametersstr StringThe input value.
obj ColoroptionalA previously allocated Color object to reuse for the result.
ReturnsType Description Color Returns a new Color object. Examplelet blueColor = 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
, anda
properties, or a Color object and sets this color instance to the input value.ParameterThe 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.
ReturnsType 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.
ParameterincludeAlpha BooleanoptionalIf
true
, the alpha value will be included in the result.ReturnsType Description String A CSS color string in rgba form that represents the Color instance used to call this method.
-
toHex(options){String}
-
Returns the color in hexadecimal format.
ParametersSpecificationoptions ObjectoptionalAdditional options.
Specificationcapitalize BooleanoptionalDefault Value: falseWhen
true
, the hexadecimal number will be capitalized.digits NumberoptionalDefault Value: 6The intended size of the output hexadecimal number. Valid values are 3, 4, 6 and 8. The default value is 6. Values 3 and 4 represent the shortened variant. Values 4 and 8 include an alpha channel.
ReturnsType Description String A three, four, six or eight-digit hexadecimal number. - See also
Example// Three digit notation const hex = Color.fromString("red").toHex({ digits: 3 }); // returns "#f00" const hex = Color.fromString("red").toHex({ digits: 3, capitalize: true }); // returns "#F00" // Four digit notation const hex = Color.fromString("red").toHex({ digits: 4 }); // returns "#f00f" const hex = Color.fromString("red").toHex({ digits: 4, capitalize: true }); // returns "#F00F" // Six digit notation const hex = Color.fromString("red").toHex({ digits: 6 }); // returns "#ff0000" const hex = Color.fromString("red").toHex({ digits: 6, capitalize: true }); // returns "#FF0000" // Eight digit notation const hex = Color.fromString("red").toHex({ digits: 8 }); // returns "#ff0000ff" const hex = Color.fromString("red").toHex({ digits: 8, capitalize: true }); // returns "#FF0000FF"
-
toJSON(){Object}
-
Returns a JSON object with all the values from a Color instance.
ReturnsType Description Object A JSON representation of the Color instance.