symbolUtils | API Reference | ArcGIS Maps SDK for JavaScript 4.33

Method Overview

Return Type	Summary	Object
Promise<(Color\|null\|undefined)>	Returns a color representing the input graphic's symbol.	symbolUtils
Promise<(SymbolUnion\|null\|undefined)>	Returns a symbol representing the input Graphic.	symbolUtils
Promise<(String\|null\|undefined)>	Returns a label corresponding to the symbol of the input Graphic as displayed in the Legend.	symbolUtils
HTMLElement	Generates a preview image of a color ramp to display in a DOM element.	symbolUtils
HTMLElement\|null\|undefined	Generates an HTML element representing the legend of a PieChartRenderer.	symbolUtils
Promise<(HTMLElement\|null\|undefined)>	Generates a preview image of a given symbol that can be displayed in a DOM element.	symbolUtils
HTMLElement\|null\|undefined	Generates an HTML element representing the square or diamond legend element of a relationship renderer.	symbolUtils

Method Details

getDisplayedColor Method getDisplayedColor(graphic, options){Promise<(Color|null|undefined)>} Since: ArcGIS Maps SDK for JavaScript 4.19 symbolUtils since 4.11, getDisplayedColor added at 4.19.

Returns a color representing the input graphic's symbol. This method is useful when you need to know the exact color of a Graphic's symbol, particularly when the graphic comes from the result of a hitTest() and its symbol properties may be empty. A symbol's properties won't be populated when a Renderer defines the visualization of a layer rather than symbols set individually on each graphic of a layer. This is the case for FeatureLayer, and any other layer that has a renderer property.

Parameters

Specification

graphic Graphic

The graphic from which to retrieve the displayed color. This commonly comes from a hitTest() or layer view query operation.

options Object|null

optional

Options for generating the display color of the input graphic. These must be specified if the input graphic comes from a layer with a renderer that has visual variables applied. See the object specification below.

Specification

scale Number

optional

The view scale at which the graphic is displayed.

viewingMode String

optional

The viewingMode of the view, if the graphic is displayed in a SceneView.

spatialReference SpatialReference

optional

The spatial reference of the view in which the graphic is displayed.

renderer RendererUnion

optional

The renderer of the layer associated with the graphic.

resolution Number

optional

The resolution of the view at which the graphic is displayed.

webStyleAcceptedFormats String []

optional

Default Value: ["web", "cim"]

A list of accepted formats when resolving web style symbols. The symbol will resolve to the first accepted format in the list.

Possible Values:"web"|"cim"

Returns

Type	Description
Promise<(Color\|null\|undefined)>	Returns the color representing the input graphic.

Example

view.on("click", async (event) => {
  const { results } = await view.hitTest(event, { include: layer });
  const graphic = results[0].graphic;

  // do something with the result color
  const color = await symbolUtils.getDisplayedColor(graphic);
});

getDisplayedSymbol Method getDisplayedSymbol(graphic, options){Promise<(SymbolUnion|null|undefined)>}

Returns a symbol representing the input Graphic. This method is useful when you need to know the exact visual properties of a Graphic's symbol, particularly when the graphic comes from the result of a hitTest() and its symbol properties may be empty. A symbol's properties won't be populated when a RendererUnion defines the visualization of a layer rather than symbols set individually on each graphic of a layer. This is the case for FeatureLayer, and any other layer that has a renderer property.

Parameters

Specification

graphic Graphic

The graphic from which to retrieve the displayed symbol. This commonly comes from a hitTest() operation.

options Object|null

optional

Options for generating the display symbol of the input graphic. These must be specified if the input graphic comes from a layer with a renderer that has visual variables applied. See the object specification below.

Specification

scale Number

optional

The view scale at which the symbol is displayed.

viewingMode String

optional

The viewingMode of the view, if the symbol is displayed in a SceneView.

spatialReference SpatialReference

optional

The spatial reference of the view in which the symbol is displayed.

renderer RendererUnion

optional

The renderer of the layer associated with the graphic.

resolution Number

optional

The resolution of the view at which the symbol is displayed.

webStyleAcceptedFormats String []

optional

Default Value: ["web", "cim"]

A list of accepted formats when resolving web style symbols. The symbol will resolve to the first accepted format in the list.

Possible Values:"web"|"cim"

Returns

Type	Description
Promise<(SymbolUnion\|null\|undefined)>	Returns the symbol representing the input graphic.

Example

view.on("click", async (event) => {
  const { results } = await view.hitTest(event, { include: layer });
  const graphic = results[0].graphic;

  // do something with the result symbol
  const symbol = await symbolUtils.getDisplayedSymbol(graphic, {
    scale: view.scale,
    spatialReference: view.spatialReference,
    resolution: view.resolution
  });
});

getLegendLabel Method getLegendLabel(graphic, view, options){Promise<(String|null|undefined)>} Since: ArcGIS Maps SDK for JavaScript 4.29 symbolUtils since 4.11, getLegendLabel added at 4.29.

Returns a label corresponding to the symbol of the input Graphic as displayed in the Legend.

Parameters

Specification

graphic Graphic

The graphic from which to retrieve its associated label as displayed in the legend widget. This commonly comes from a hitTest() operation.

view MapView|SceneView

optional

The graphic from which to retrieve the displayed symbol. This commonly comes from a hitTest() operation.

options Object|null

optional

Options for generating the legend label of the input graphic. These must be specified if the input graphic comes from a layer with a renderer that has visual variables applied. See the object specification below.

Specification

scale Number

optional

The view scale at which the symbol is displayed.

viewingMode String

optional

The viewingMode of the view, if the symbol is displayed in a SceneView.

spatialReference SpatialReference

optional

The spatial reference of the view in which the symbol is displayed.

renderer RendererUnion

optional

The renderer of the layer associated with the graphic.

resolution Number

optional

The resolution of the view at which the symbol is displayed.

Returns

Type	Description
Promise<(String\|null\|undefined)>	Returns the label representing the input graphic in the legend.

Example

view.on("click", async (event) => {
  const { results } = await view.hitTest(event, { include: layer });
  const graphic = results[0].graphic;

  // do something with the result symbol
  const label = await symbolUtils.getLegendLabel(graphic, view, {
    scale: view.scale,
    spatialReference: view.spatialReference,
    resolution: view.resolution
  });
});

renderColorRampPreviewHTML Method renderColorRampPreviewHTML(colors, options){HTMLElement} Since: ArcGIS Maps SDK for JavaScript 4.13 symbolUtils since 4.11, renderColorRampPreviewHTML added at 4.13.

Generates a preview image of a color ramp to display in a DOM element.

Parameters

Specification

colors Color []

An array of colors from which to construct the color ramp.

options Object

optional

Formatting options for the color ramp.

Specification

align String

optional

Default Value: vertical

Specifies the alignment of the color ramp.

Possible Values:"horizontal"|"vertical"

gradient Boolean

optional

Default Value: true

Indicates whether to render the color ramp with a continuous gradient. When false, distinct colors will appear in the ramp without a gradient.

width Number

optional

The width of the ramp in pixels.

height Number

optional

The height of the ramp in pixels.

Returns

Type	Description
HTMLElement	Returns a preview of the color ramp for display in the DOM.

Examples

const colors = [
  "#d6ffe1",
  "#8ceda6",
  "#2ee860",
  "#00e33d"
];

const colorRamp = symbolUtils.renderColorRampPreviewHTML(colors, {
  align: "vertical"
});

body.appendChild(colorRamp);

// Primary color scheme from colorSchemes.getSchemes()
const schemes = colorSchemes.getSchemes({
  basemap: "gray-vector",
  geometryType: "polygon",
  theme: "above-and-below"
});

const colorRamp = symbolUtils.renderColorRampPreviewHTML(schemes.primaryScheme.colors, {
  align: "horizontal"
});

body.appendChild(colorRamp);

renderPieChartPreviewHTML Method renderPieChartPreviewHTML(colors, options){HTMLElement |null |undefined} Since: ArcGIS Maps SDK for JavaScript 4.26 symbolUtils since 4.11, renderPieChartPreviewHTML added at 4.26.

Generates an HTML element representing the legend of a PieChartRenderer. Use this method to display the pie chart legend element in a DOM element.

Parameters

Specification

colors Color []

A list of colors used to render the pie chart.

options Object

optional

Options for creating the legend element.

Specification

radius Number

optional

Default Value: 40

The radius of the pie chart in pixels.

holePercentage Number

optional

Default Value: 0

The hole percentage of the chart on a scale of 0-1. A percentage of 0 creates a pie chart. Any other value creates a donut chart. This value indicates the percentage of the chart to remove from the center.

values Number []

optional

The values used to indicate the area each color should represent as a percentage when creating the pie chart. The number of values should match the number of colors. Value positions correspond with the positions of colors in the colors array. For example, if the first color in the colors array is red and the first value in the values array is 50, then 50% of the chart should be represented with red. The sum of all values defined here must equal 100. By default all colors are given an equal area.

outline SimpleLineSymbol

optional

The outline of the pie chart.

Returns

Type	Description
HTMLElement \| null \| undefined	Returns the of the pie chart legend element to display in the DOM.

Example

const { attributes, size, holePercentage, outline } = layer.renderer;
const colors = attributes.map( attribute => attribute.color );

const element = symbolUtils.renderPieChartPreviewHTML(colors, {
  radius: size * 0.5,
  holePercentage,
  values: [10,70,20],
  outline
});

legendElement.appendChild(element);

renderPreviewHTML Method renderPreviewHTML(symbol, options){Promise<(HTMLElement|null|undefined)>}

Generates a preview image of a given symbol that can be displayed in a DOM element.

Parameters

Specification

symbol SymbolUnion

The symbol for which to generate a preview image.

options Object

optional

Formatting options for the symbol preview image.

Specification

node HTMLElement

optional

The parent node to append to the symbol.

size Number|Object

optional

Use a number to set the size (in points) of the symbol preview for any symbol representing a point. Starting at version 4.23, you can provide an object with width and height properties when creating symbol previews for simple symbols. At version 4.25, the width and height properties are supported on all symbols.

Specification

width Number

The width of the symbol preview in points. Previews for SimpleFillSymbol must have isSquareFill enabled in symbolConfig for this property to take effect.

height Number

The height of the symbol preview in points. Previews for SimpleFillSymbol must have isSquareFill enabled in symbolConfig for this property to take effect.

maxSize Number

optional

The maximum size of the symbol preview in points.

opacity Number

optional

The opacity of the layer represented by the symbol. Must be a number between 0 and 1.

scale Boolean

optional

Default Value: true

When true the size of the symbol preview will include the outline in the measurement of the entire symbol. When false, the symbol preview will not include the outline in the size measurement, thus matching the symbol size in the view.

disableUpsampling Boolean

optional

Indicates whether to disable upsampling for raster images.

symbolConfig Object|String

optional

Options for setting the shape of a fill symbol preview. This can be a single string value (tall is the only option), or an object with config options. See the table below for specifics on the configuration options available.

Possible Values:"tall"

Specification

isTall Boolean

optional

Default Value: false

Set to true for "tall" symbols in portrait view. This is typically used for 3D cylinder object symbols.

isSquareFill Boolean

optional

Default Value: false

Set to true to render the preview as a square instead of a generic polygon shape.

rotation Number

optional

The rotation of the symbol.

overrideText String

optional

Since 4.25 The text that will be displayed in the symbol preview of a TextSymbol. This will override any existing text defined on the symbol.

Returns

Type	Description
Promise<(HTMLElement\|null\|undefined)>	Returns a preview of the given symbol to display to the DOM.

Example

// symbol from SimpleRenderer;
const symbol = layer.renderer.symbol.clone();

symbolUtils.renderPreviewHTML(symbol, {
  node: document.getElementById("preview"),
  size: 8
});

renderRelationshipRampPreviewHTML Method renderRelationshipRampPreviewHTML(renderer, options){HTMLElement |null |undefined} Since: ArcGIS Maps SDK for JavaScript 4.26 symbolUtils since 4.11, renderRelationshipRampPreviewHTML added at 4.26.

Generates an HTML element representing the square or diamond legend element of a relationship renderer. Use this method to display the relationship legend element in a DOM element.

Parameters

Specification

renderer UniqueValueRenderer

A relationship renderer instance.

options Object

optional

Options for creating the legend element.

Specification

node HTMLElement

optional

The container node in which to place the generated relationship element.

opacity Number

optional

Default Value: 1

The opacity of the legend element.

Returns

Type	Description
HTMLElement \| null \| undefined	Returns the relationship legend element to display in the DOM.

Example

const relationshipElement = symbolUtils.renderRelationshipRampPreviewHTML(layer.renderer);
body.appendChild(relationshipElement);