Color | References | ArcGIS Maps SDK for JavaScript

import Color from "@arcgis/core/Color.js";

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

Constructor

Parameters

Parameter	Type	Description	Required
color	`ColorLike`	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
});

Properties

Property	Type	Class
`a`	`number`
`b`	`number`
`g`	`number`
`r`	`number`

a

Property

Type: 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.

Default value: 1

b

Property

Type: number

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

Default value: 255

g

Property

Type: number

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

Default value: 255

r

Property

Type: number

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

Default value: 255

Methods

Method	Signature	Class
`blendColors` static	`blendColors(start: Color, end: Color, weight: number, out?: Color): Color`
`fromArray` static	`fromArray(a: ColorJSON \| readonly number[], t?: Color): Color`
`fromHex` static	`fromHex(hex: string, out?: Color): Color \| null \| undefined`
`fromJSON` static	`fromJSON(json: ColorJSON \| null \| undefined): Color \| null \| undefined`
`fromRgb` static	`fromRgb(color: string, out?: Color): Color \| null \| undefined`
`fromString` static	`fromString(color: string, obj?: Color): Color \| null \| undefined`
`clone`	`clone(): Color`
`equals`	`equals(other: Color \| null \| undefined): boolean`
`setColor`	`setColor(color: string \| ColorLike \| ColorJSON \| number[]): this`
`toCss`	`toCss(includeAlpha?: boolean): string`
`toHex`	`toHex(options?: HexOutputOptions): string`
`toJSON`	`toJSON(): ColorJSON`
`toRgb`	`toRgb(): [ number, number, number ]`
`toRgba`	`toRgba(): [ number, number, number, number ]`

blendColors

static Method

Signature: blendColors (start: Color, end: Color, weight: number, out?: Color): Color

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

Parameter	Type	Description
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`	A previously allocated Color object to reuse for the result.

Returns: 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);

fromArray

static Method

Signature: fromArray (a: ColorJSON | readonly number[], t?: 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. Optionally accepts a Color object to update with the color value and return instead of creating a new object.

Parameters

Parameter	Type	Description	Required
a	`ColorJSON \| readonly number[]`	The input array.
t	`Color`	A previously allocated Color object to reuse for the result.

Returns: Color
Returns a new Color object.

Example

let redColor = Color.fromArray([201, 0, 19]);

fromHex

static Method

Signature: fromHex (hex: string, out?: Color): Color | null | undefined

Creates a Color from hexadecimal string.

Colors can be expressed as:

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

Parameter	Type	Description	Required
hex	`string`	The input color in a hexadecimal string.
out	`Color`	A previously allocated Color object to reuse for the result.

Returns: Color | null | undefined
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

static Method

Signature: fromJSON (json: ColorJSON | null | undefined): Color | null | undefined

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

Parameters

Parameter	Type	Description	Required
json	`ColorJSON \| null \| undefined`	A JSON representation of the instance.

Returns: Color | null | undefined
A new Color instance.

fromRgb

static Method

Signature: fromRgb (color: string, out?: Color): Color | null | undefined

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

Parameter	Type	Description	Required
color	`string`	The input color in a string of the form "rgb()" or "rgba()".
out	`Color`	A previously allocated Color object to reuse for the result.

Returns: Color | null | undefined
Returns a new Color object.

Example

const redColor = Color.fromRgb("rgb(202,0,19)");

fromString

static Method

Signature: fromString (color: string, obj?: Color): Color | null | undefined

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

Parameter	Type	Description	Required
color	`string`	The input value.
obj	`Color`	A previously allocated Color object to reuse for the result.

Returns: Color | null | undefined
Returns a new Color object.

Example

let blueColor = Color.fromString("blue");

clone

Method

Signature: clone (): Color

Creates a deep clone of the Color instance.

Returns: Color
A deep clone of the Color instance.

Example

// Creates a deep clone of the graphic's color
let colorClone = graphic.symbol.color.clone();

equals

Method

Signature: equals (other: Color | null | undefined): boolean

Since: ArcGIS Maps SDK for JavaScript 4.33

Checks equality of the Color instance with another Color instance.

Parameters

Parameter	Type	Description	Required
other	`Color \| null \| undefined`	Another color, or null or undefined.

Returns: boolean
true if the other color is the same as this one (r, g, b, and a values are identical).

setColor

Method

Signature: setColor (color: string | ColorLike | ColorJSON | number[]): this

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.

Parameters

Parameter	Type	Description	Required
color	`string \| ColorLike \| ColorJSON \| number[]`	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: this
Sets the Color instance used to call this method to the new color.

toCss

Method

Signature: toCss (includeAlpha?: boolean): string

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

Parameters

Parameter	Type	Description	Required
includeAlpha	`boolean`	If `true`, the alpha value will be included in the result.

Returns: string
A CSS color string in rgba form that represents the Color instance used to call this method.

toHex

Method

Signature: toHex (options?: HexOutputOptions): string

Returns the color in hexadecimal format.

See also

RGB Hexadecimal Notations

Parameters

Parameter	Type	Description	Required
options	`HexOutputOptions`	Additional options.

Returns: 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

Signature: toJSON (): ColorJSON

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

Returns: ColorJSON
A JSON representation of the Color instance.

toRgb

Method

Signature: toRgb (): [ number, number, number ]

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

Returns: [ number, number, number ]
A 3-component array of rgb values.

toRgba

Method

Signature: toRgba (): [ number, number, number, number ]

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

Returns: [ number, number, number, number ]
A 4-component array of rgba values.

Type definitions

HexOutputOptions

Type definition

Additional options to set when converting a Color to a hexadecimal string via toHex() method.

capitalize

Property

Type: boolean | undefined

When true, the hexadecimal number will be capitalized.

Default value: false

digits

Property

Type: 3 | 4 | 6 | 8 | undefined

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.

Default value: 6

ColorLike

Type definition

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.

See also