Color

AMD: require(["esri/Color"], (Color) => { /* code goes here */ });
ESM: import Color from "@arcgis/core/Color.js";
Class: esri/Color
Since: ArcGIS Maps SDK for JavaScript 4.0

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).

See also

Constructors

Color

Constructor
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

The alpha value.

Color

The blue value.

Color

The green value.

Color

The red value.

Color

Property Details

a

Property
a Number

The alpha value. This value can be any number between 0 and 1 and represents the opacity of the Color. 0 indicates the color is fully transparent and 1 indicates it is fully opaque.

b

Property
b Number

The blue value. This value can range between 0 and 255.

g

Property
g Number

The green value. This value can range between 0 and 255.

r

Property
r Number

The red value. This value can range between 0 and 255.

Method Overview

Name Return Type Summary Class

Creates a Color instance by blending two colors using a weight factor.

Color

Creates a deep clone of the Color instance.

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.

Color

Creates a Color from hexadecimal string.

Color

Creates a new Color instance, and initializes it with values from a JSON object.

Color

Creates a Color instance from a string of the form "rgb()" or "rgba()".

Color

Creates a Color instance by parsing a generic string.

Color

Takes an array of rgb(a) values, named string, hex string or an hsl(a) string, an object with r, g, b, and a properties, or a Color object and sets this color instance to the input value.

Color

Returns a CSS color string in rgba form representing the Color instance.

Color

Returns the color in hexadecimal format.

Color

Returns a JSON object with all the values from a Color instance.

Color

Returns a 3-component array of rgb values that represent the Color instance.

Color

Returns a 4-component array of rgba values that represent the Color instance.

Color

Method Details

blendColors

Method
blendColors(start, end, weight, out){Color}static

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 Color

The start color.

end Color

The end color.

weight Number

The weight value is a number from 0 to 1, with 0.5 being a 50/50 blend.

out Color
optional

A previously allocated Color object to reuse for the result.

Returns
Type Description
Color Returns a new Color object.
Example
const startColor = new Color("#0000ff");
const endColor = new Color("#ca0013");
const blendedColor = Color.blendColors(startColor, endColor, 0.5);

clone

Method
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
let colorClone = graphic.symbol.color.clone();

fromArray

Method
fromArray(a, t){Color}static

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.

t Color
optional

A previously allocated Color object to reuse for the result.

Returns
Type Description
Color Returns a new Color object.
Example
let redColor = Color.fromArray([201, 0, 19]);

fromHex

Method
fromHex(hex, color){Color}static

Creates a Color from hexadecimal string.

Colors can be expressed as:

  1. Hex triplet, a six or eight digit hexadecimal number. For example:
    • "#ffff00" for Yellow, or
    • "#dc143c20" for a semi-transparent Crimson
  2. Shorthand variant, a three or four digit hexadecimal 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.

Parameters
hex String

The input color in a hexadecimal string.

color Color
optional

A previously allocated Color object to reuse for the result.

Returns
Type Description
Color Returns a new Color object or updated color object (if parsed).
Example
const 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

fromJSON

Method
fromJSON(json){Color}static

Creates a new Color instance, and initializes it with values from a JSON object.

Parameter
json Object

A JSON representation of the instance.

Returns
Type Description
Color A new Color instance.

fromRgb

Method
fromRgb(color, out){Color}static

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 String

The input color in a string of the form "rgb()" or "rgba()".

out Color
optional

A previously allocated Color object to reuse for the result.

Returns
Type Description
Color Returns a new Color object.
Example
const redColor = Color.fromRgb("rgb(202,0,19)");

fromString

Method
fromString(str, obj){Color}static

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 String

The input value.

obj Color
optional

A previously allocated Color object to reuse for the result.

Returns
Type Description
Color Returns a new Color object.
Example
let blueColor = Color.fromString("blue");

setColor

Method
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, and a properties, 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

Method
toCss(includeAlpha){String}

Returns a CSS color string in rgba form representing the Color instance.

Parameter
includeAlpha Boolean
optional

If 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

Method
toHex(options){String}

Returns the color in hexadecimal format.

Parameters
Specification
options Object
optional

Additional options.

Specification
capitalize Boolean
optional
Default Value: false

When true, the hexadecimal number will be capitalized.

digits Number
optional
Default Value: 6

The 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.

Returns
Type Description
String A three, four, six or eight-digit hexadecimal number.
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

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.

toRgb

Method
toRgb(){Number[]}

Returns a 3-component array of rgb values that represent the Color instance.

Returns
Type Description
Number[] A 3-component array of rgb values.

toRgba

Method
toRgba(){Number[]}

Returns a 4-component array of rgba values that represent the Color instance.

Returns
Type Description
Number[] A 4-component array of rgba values.

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.

The developer dashboard has moved

You can no longer sign into this site. Go to your ArcGIS portal or the ArcGIS Location Platform dashboard to perform management tasks.

Your ArcGIS portal

Create, manage, and access API keys and OAuth 2.0 developer credentials, hosted layers, and data services.

Your ArcGIS Location Platform dashboard

Manage billing, monitor service usage, and access additional resources.

Learn more about these changes in the What's new in Esri Developers June 2024 blog post.

Close