color

AMD: require(["esri/smartMapping/symbology/color"], (colorSchemes) => { /* code goes here */ });
ESM: import * as colorSchemes from "@arcgis/core/smartMapping/symbology/color.js";
Object: esri/smartMapping/symbology/color
Since: ArcGIS Maps SDK for JavaScript 4.2

Object containing helper methods for generating optimal symbols for data-driven color visualizations. The getSchemes() method is used to generate symbol properties best suited to the given geometry type and basemap.

Method Overview

Name Return Type Summary Object
ColorScheme

Clones a color scheme object.

color
ColorScheme

Flips the colors in reverse order of the input color scheme.

color
ColorScheme[]

Returns all schemes matching the given color ramp.

color
ColorScheme

Returns a color scheme with the provided name.

color
ColorSchemes

Returns a primary scheme and secondary schemes defining symbol properties for data-driven color visualizations in a FeatureLayer.

color
ColorScheme[]

Returns an array of color schemes with the provided tags.

color
Theme[]

Returns metadata for the available themes.

color

Method Details

cloneScheme

Method
cloneScheme(scheme){ColorScheme}

Clones a color scheme object.

Parameter
scheme ColorScheme

The color scheme object to clone.

Returns
Type Description
ColorScheme Returns a clone of the given color scheme object.
Example
// clones the primary scheme returned from the getSchemes() method
let colorScheme = primaryScheme.clone();

flipColors

Method
flipColors(scheme){ColorScheme}

Flips the colors in reverse order of the input color scheme.

Parameter
scheme ColorScheme

The color scheme to reverse.

Returns
Type Description
ColorScheme Returns the input color scheme with its colors in reverse order.
Example
// reverses the order of colors in a primary scheme
// obtained from the getSchemes() method
let flippedScheme = colorSchemes.flipColors(primaryScheme);

getMatchingSchemes

Method
getMatchingSchemes(params){ColorScheme[]}
Since: ArcGIS Maps SDK for JavaScript 4.9 color since 4.2, getMatchingSchemes added at 4.9.

Returns all schemes matching the given color ramp.

Parameters
Specification
params Object

See the table below for details of each parameter that may be passed to this function.

Specification
theme String

The name of the theme from which to get color schemes.

Possible Values:"high-to-low"|"above-and-below"|"centered-on"|"extremes"

colors Color[]

An array of colors used to match with schemes for the given theme.

geometryType String

The geometry type of the layer for which the color scheme will be applied.

worldScale Boolean
optional

Indicates whether 3D volumetric symbols will be used in the visualization.

view SceneView
optional

The SceneView instance used to calculate the suggested sizes of the symbols. This is required for 3D visualizations.

Returns
Type Description
ColorScheme[] An array of color schemes that match the given colors.

getSchemeByName

Method
getSchemeByName(params){ColorScheme}
Since: ArcGIS Maps SDK for JavaScript 4.12 color since 4.2, getSchemeByName added at 4.12.

Returns a color scheme with the provided name.

Parameters
Specification
params Object

See the table below for details of each parameter that may be passed to this function.

Specification
name String

The name of the scheme to retrieve.

basemap String|Basemap
optional

The basemap to pair with the visualization. This value indicates the best symbol colors for visualizing features against the given basemap.

basemapTheme String
optional

If you have a non-Esri basemap (e.g. a VectorTileLayer basemap with a custom style) or no basemap at all, use this parameter to indicate whether the background of the visualization is light or dark.

Possible Values:"light"|"dark"

geometryType String

The geometry type of the features to visualize.

Possible Values:"point"|"multipoint"|"polyline"|"polygon"|"mesh"|"multipatch"

theme String

The theme determines which values will be emphasized in the continuous ramp and the map. Possible values are listed below.

Value Description Example
high-to-low High values are emphasized with strong colors. high-to-low
above-and-below Values centered around a given point (e.g. the average) are visualized with weak colors while other values are emphasized with strong colors. above-and-below
centered-on Values centered around a given point (e.g. the average) are emphasized with strong colors while other values are visualized with weak colors. centered-on
extremes High and low values are emphasized with strong colors. All others are visualized with weak colors. extremes

Possible Values:"high-to-low"|"above-and-below"|"centered-on"|"extremes"

view SceneView
optional

The SceneView instance in which the scheme will be used. This property is only applicable when the scheme will be used in conjunction with 3D symbols.

worldScale Boolean
optional

Indicates if the size units of the scheme will be in meters. This should be true when the scheme is intended for 3D volumetric symbology. A view must be provided if this property is set to true.

Returns
Type Description
ColorScheme Returns the color scheme with the given name.
Example
// Returns the Red Extremes 1 scheme
const redExtremesScheme = colorSchemes.getSchemeByName({
  basemapTheme: "light",
  geometryType: featureLayer.geometryType,
  theme: "extremes",
  name: "Red Extremes 1"
});

getSchemes

Method
getSchemes(params){ColorSchemes}

Returns a primary scheme and secondary schemes defining symbol properties for data-driven color visualizations in a FeatureLayer. The basemap parameter determines the color schemes of the graphics used to visualize each feature. The geometryType determines which type of symbol to return.

Parameters
Specification
params Object

See the table below for details of each parameter that may be passed to this function.

Specification
basemap String|Basemap
optional

The Esri basemap to pair with the visualization. This value indicates the best symbol colors for visualizing features against the given basemap. If you have a non-Esri basemap (e.g. a VectorTileLayer basemap with a custom style) or no basemap at all, then use the basemapTheme parameter instead of this parameter.

basemapTheme String
optional

If you have a non-Esri basemap (e.g. a VectorTileLayer basemap with a custom style) or no basemap at all, use this parameter to indicate whether the background of the visualization is light or dark.

Possible Values:"light"|"dark"

geometryType String

The geometry type of the features to visualize.

Possible Values:"point"|"multipoint"|"polyline"|"polygon"|"mesh"|"multipatch"

theme String

The theme determines which values will be emphasized in the continuous ramp and the map. Possible values are listed below.

Value Description Example
high-to-low High values are emphasized with strong colors. high-to-low
above-and-below Values centered around a given point (e.g. the average) are visualized with weak colors while other values are emphasized with strong colors. above-and-below
centered-on Values centered around a given point (e.g. the average) are emphasized with strong colors while other values are visualized with weak colors. centered-on
extremes High and low values are emphasized with strong colors. All others are visualized with weak colors. extremes

Possible Values:"high-to-low"|"above-and-below"|"centered-on"|"extremes"

view SceneView
optional

The SceneView instance in which the scheme will be used. This property is only applicable when the scheme will be used in conjunction with 3D symbols.

worldScale Boolean
optional

Indicates if the size units of the scheme will be in meters. This should be true when the scheme is intended for 3D volumetric symbology. A view must be provided if this property is set to true.

Returns
Type Description
ColorSchemes Returns an object containing the optimal color scheme to use for the given basemap and secondary schemes that may also be used.
Example
// gets the primary scheme for the features of the given geometry type and basemap
let schemes = colorSchemes.getSchemes({
  basemap: map.basemap,
  geometryType: featureLayer.geometryType,
  theme: "extremes"
});

// the best default scheme for the layer, basemap, and theme
let primaryScheme = schemes.primaryScheme;

getSchemesByTag

Method
getSchemesByTag(params){ColorScheme[]}
Since: ArcGIS Maps SDK for JavaScript 4.12 color since 4.2, getSchemesByTag added at 4.12.

Returns an array of color schemes with the provided tags. These schemes define symbol properties for data-driven color visualizations in any layer that can be rendered with a Renderer.

Parameters
Specification
params Object

See the table below for details of each parameter that may be passed to this function.

Specification
includedTags String[]
optional

When provided, only schemes containing all the matching tags will be returned.

Known Tags: light | dark | reds | yellows | oranges | greens | blues | purples | pinks | browns | grays | bright | subdued | colorblind-friendly | diverging | sequential | 3d

excludedTags String[]
optional

When provided, only schemes missing all the provided tags will be returned.

Known Tags: light | dark | reds | yellows | oranges | greens | blues | purples | pinks | browns | grays | bright | subdued | colorblind-friendly | diverging | sequential | 3d

basemap String|Basemap
optional

The basemap to pair with the visualization. This value indicates the best symbol colors for visualizing features against the given basemap.

basemapTheme String
optional

If you have a non-Esri basemap (e.g. a VectorTileLayer basemap with a custom style) or no basemap at all, use this parameter to indicate whether the background of the visualization is light or dark.

Possible Values:"light"|"dark"

geometryType String

The geometry type of the features to visualize.

Possible Values:"point"|"multipoint"|"polyline"|"polygon"|"mesh"|"multipatch"

theme String

The theme determines which values will be emphasized in the continuous ramp and the map. Possible values are listed below.

Value Description Example
high-to-low High values are emphasized with strong colors. high-to-low
above-and-below Values centered around a given point (e.g. the average) are visualized with weak colors while other values are emphasized with strong colors. above-and-below
centered-on Values centered around a given point (e.g. the average) are emphasized with strong colors while other values are visualized with weak colors. centered-on
extremes High and low values are emphasized with strong colors. All others are visualized with weak colors. extremes

Possible Values:"high-to-low"|"above-and-below"|"centered-on"|"extremes"

view SceneView
optional

The SceneView instance in which the scheme will be used. This property is only applicable when the scheme will be used in conjunction with 3D symbols.

worldScale Boolean
optional

Indicates if the size units of the scheme will be in meters. This should be true when the scheme is intended for 3D volumetric symbology. A view must be provided if this property is set to true.

Returns
Type Description
ColorScheme[] Returns an array of color schemes either including or excluding the provided tags.
Example
// Returns all the red color schemes that are color-blind friendly
let schemes = colorSchemes.getSchemesByTag({
  basemap: map.basemap,
  geometryType: featureLayer.geometryType,
  theme: "extremes",
  includedTags: [ "reds", "colorblind-friendly" ]
});

getThemes

Method
getThemes(basemap){Theme[]}

Returns metadata for the available themes. If a basemap is provided, returns themes that work best with the given basemap.

Parameter
basemap String|Basemap
optional

The Esri basemap string or object that will be used with the returned theme(s).

Returns
Type Description
Theme[] Returns an object containing information about the available themes for the given basemap.

Type Definitions

Properties defining the symbology scheme used to visualize features with attribute data-driven color.

ColorSchemeForMesh

Type Definition
ColorSchemeForMesh

Properties defining the symbology scheme used to visualize mesh features with attribute data-driven color.

Properties
name String

The unique name of the scheme.

tags String[]

Tags associated with the scheme.

id String

The unique id of the color scheme to use in the visualization. The id is assigned based on the following template: <themeName>/<basemapName>/<schemeName>.

theme String

Indicates which values will be emphasized in the continuous ramp and the map. Possible values are listed below.

Value Description Example
high-to-low High values are emphasized with strong colors. high-to-low
above-and-below Values centered around a given point (e.g. the average) are visualized with weak colors while other values are emphasized with strong colors. above-and-below
centered-on Values centered around a given point (e.g. the average) are emphasized with strong colors while other values are visualized with weak colors. centered-on
extremes High and low values are emphasized with strong colors. All others are visualized with weak colors. extremes
colors Color[]

The continuous color ramp that will be applied to the visualization.

noDataColor Color

The color of the symbol used to indicate features with no data and features that are out of range.

colorsForClassBreaks Object[]

Predefined classed color schemes to use for the visualization.

Specification
colors Color[]

An array of hex color strings. Each color is assigned to a specific break in classed color visualizations.

numClasses Number

The number of classes used in the classed color visualization.

opacity Number

The opacity of the symbol.

ColorSchemeForPoint

Type Definition
ColorSchemeForPoint

Properties defining the symbology scheme used to visualize point features with attribute data-driven color.

Properties
name String

The unique name of the scheme.

tags String[]

Tags associated with the scheme.

id String

The unique id of the color scheme to use in the visualization. The id is assigned based on the following template: <themeName>/<basemapName>/<schemeName>.

theme String

Indicates which values will be emphasized in the continuous ramp and the map. Possible values are listed below.

Value Description Example
high-to-low High values are emphasized with strong colors. high-to-low
above-and-below Values centered around a given point (e.g. the average) are visualized with weak colors while other values are emphasized with strong colors. above-and-below
centered-on Values centered around a given point (e.g. the average) are emphasized with strong colors while other values are visualized with weak colors. centered-on
extremes High and low values are emphasized with strong colors. All others are visualized with weak colors. extremes
colors Color[]

The continuous color ramp that will be applied to the visualization.

noDataColor Color

The color of the symbol used to indicate features with no data and features that are out of range.

colorsForClassBreaks Object[]

Predefined classed color schemes to use for the visualization.

Specification
colors Color[]

An array of hex color strings. Each color is assigned to a specific break in classed color visualizations.

numClasses Number

The number of classes used in the classed color visualization.

outline Object

Properties for defining the outline of the symbol.

Specification
color Color

The outline color of the symbol.

width Number

The width of the symbol in pixels or points.

size Number

The default size of the symbol in pixels or points.

opacity Number

The opacity of the symbol.

ColorSchemeForPolygon

Type Definition
ColorSchemeForPolygon

Properties defining the symbology scheme used to visualize polygon features with attribute data-driven color.

Properties
name String

The unique name of the scheme.

tags String[]

Tags associated with the scheme.

id String

The unique id of the color scheme to use in the visualization. The id is assigned based on the following template: <themeName>/<basemapName>/<schemeName>.

theme String

Indicates which values will be emphasized in the continuous ramp and the map. Possible values are listed below.

Value Description Example
high-to-low High values are emphasized with strong colors. high-to-low
above-and-below Values centered around a given point (e.g. the average) are visualized with weak colors while other values are emphasized with strong colors. above-and-below
centered-on Values centered around a given point (e.g. the average) are emphasized with strong colors while other values are visualized with weak colors. centered-on
extremes High and low values are emphasized with strong colors. All others are visualized with weak colors. extremes
colors Color[]

The continuous color ramp that will be applied to the visualization.

noDataColor Color

The color of the symbol used to indicate features with no data and features that are out of range.

colorsForClassBreaks Object[]

Predefined classed color schemes to use for the visualization.

Specification
colors Color[]

An array of hex color strings. Each color is assigned to a specific break in classed color visualizations.

numClasses Number

The number of classes used in the classed color visualization.

outline Object

Properties for defining the outline of the symbol.

Specification
color Color

The outline color of the symbol.

width Number

The width of the symbol in pixels or points.

opacity Number

The opacity of the symbol.

ColorSchemeForPolyline

Type Definition
ColorSchemeForPolyline

Properties defining the symbology scheme used to visualize polyline features with attribute data-driven color.

Properties
name String

The unique name of the scheme.

tags String[]

Tags associated with the scheme.

id String

The unique id of the color scheme to use in the visualization. The id is assigned based on the following template: <themeName>/<basemapName>/<schemeName>.

theme String

Indicates which values will be emphasized in the continuous ramp and the map. Possible values are listed below.

Value Description Example
high-to-low High values are emphasized with strong colors. high-to-low
above-and-below Values centered around a given point (e.g. the average) are visualized with weak colors while other values are emphasized with strong colors. above-and-below
centered-on Values centered around a given point (e.g. the average) are emphasized with strong colors while other values are visualized with weak colors. centered-on
extremes High and low values are emphasized with strong colors. All others are visualized with weak colors. extremes
colors Color[]

The continuous color ramp that will be applied to the visualization.

noDataColor Color

The color of the symbol used to indicate features with no data and features that are out of range.

colorsForClassBreaks Object[]

Predefined classed color schemes to use for the visualization.

Specification
colors Color[]

An array of hex color strings. Each color is assigned to a specific break in classed color visualizations.

numClasses Number

The number of classes used in the classed color visualization.

width Number

The default width of the symbol in pixels or points.

opacity Number

The opacity of the symbol.

ColorSchemes

Type Definition
ColorSchemes

The return object of the getSchemes() method.

Properties
primaryScheme ColorScheme

The color scheme best suited for the given basemap and geometry type.

secondarySchemes ColorScheme[]

Additional color schemes that may be used to visualize data of the given geometry type overlaid on the given basemap.

basemapId String

The ID of the basemap associated with the given schemes.

basemapTheme String

Indicates whether the average basemap color is light or dark.

Theme

Type Definition
Theme

Describes a theme that pairs well with the given basemaps. See the table below for more details of the properties in this object.

Properties
name String

The name of the theme.

label String

The label identifying the theme in UI elements.

description String

Text describing the theme in the UI.

basemaps String[]

The Esri basemaps that pair well with the given theme.

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