symbolUtils | References | ArcGIS Maps SDK for JavaScript

import { renderPieChartPreviewHTML, renderRelationshipRampPreviewHTML, renderColorRampPreviewHTML, renderPreviewHTML, getDisplayedSymbol } from "@arcgis/core/symbols/support/symbolUtils.js";

const { renderPieChartPreviewHTML, renderRelationshipRampPreviewHTML, renderColorRampPreviewHTML, renderPreviewHTML, getDisplayedSymbol } = await $arcgis.import("@arcgis/core/symbols/support/symbolUtils.js");

Since: ArcGIS Maps SDK for JavaScript 4.11

Utilities for generating small preview images of symbols.

Functions

Name	Return Type	Object
`renderPieChartPreviewHTML`	`HTMLElement \| null \| undefined`
`RenderPieChartPreviewHTMLOptions`
`renderRelationshipRampPreviewHTML`	`HTMLElement \| null \| undefined`
`RenderRelationshipRampPreviewHTMLOptions`
`renderColorRampPreviewHTML`	`HTMLElement`
`RenderColorRampPreviewHTMLOptions`
`renderPreviewHTML`	`Promise<HTMLElement \| null \| undefined>`
`getDisplayedSymbol`	`Promise<SymbolUnion \| null \| undefined>`
`getDisplayedColor`	`Promise<Color \| null \| undefined>`
`getLegendLabel`	`Promise<string \| null \| undefined>`
`RenderPreviewHTMLOptions`
`RenderPreviewHTMLSizeOptions`
`RenderPreviewSymbolConfigOptions`

renderPieChartPreviewHTML

Function

Since: ArcGIS Maps SDK for JavaScript 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.

Signature: renderPieChartPreviewHTML (colors: Color[], options?: RenderPieChartPreviewHTMLOptions): HTMLElement | null | undefined

Parameters

Parameter	Type	Description	Required
colors	`Color[]`	A list of colors used to render the pie chart.
options	`RenderPieChartPreviewHTMLOptions`	Options for creating the legend element.

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

renderRelationshipRampPreviewHTML

Function

Since: ArcGIS Maps SDK for JavaScript 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.

Signature: renderRelationshipRampPreviewHTML (renderer: UniqueValueRenderer, options?: RenderRelationshipRampPreviewHTMLOptions): HTMLElement | null | undefined

Parameters

Parameter	Type	Description	Required
renderer	`UniqueValueRenderer`	A relationship renderer instance.
options	`RenderRelationshipRampPreviewHTMLOptions`	Options for creating the legend element.

Returns: HTMLElement | null | undefined
Returns the relationship legend element to display in the DOM.

Example

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

renderColorRampPreviewHTML

Function

Since: ArcGIS Maps SDK for JavaScript 4.13

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

Signature: renderColorRampPreviewHTML (colors: Color[], options?: RenderColorRampPreviewHTMLOptions): HTMLElement

Parameters

Parameter	Type	Description	Required
colors	`Color[]`	An array of colors from which to construct the color ramp.
options	`RenderColorRampPreviewHTMLOptions`	Formatting options for the color ramp.

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

renderPreviewHTML

Function

Type parameters: <T extends RenderPreviewHTMLOptions>

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

Signature: renderPreviewHTML <T extends RenderPreviewHTMLOptions>(symbol: SymbolUnion, options?: T): Promise<HTMLElement | null | undefined>

Parameters

Parameter	Type	Description	Required
symbol	`SymbolUnion`	The symbol for which to generate a preview image.
options	`T`	Formatting options for the symbol preview image.

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

getDisplayedSymbol

Function

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

Signature: getDisplayedSymbol (graphic: Graphic, options?: GetDisplaySymbolOptions | null | undefined): Promise<SymbolUnion | null | undefined>

Parameters

Parameter	Type	Description	Required
graphic	`Graphic`	The graphic from which to retrieve the displayed symbol. This commonly comes from a MapView.hitTest() operation.
options	`GetDisplaySymbolOptions \| null \| undefined`	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.

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

getDisplayedColor

Function

Since: ArcGIS Maps SDK for JavaScript 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 MapView.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.

Signature: getDisplayedColor (graphic: Graphic, options?: GetDisplaySymbolOptions | null | undefined): Promise<Color | null | undefined>

Parameters

Parameter	Type	Description	Required
graphic	`Graphic`	The graphic from which to retrieve the displayed color. This commonly comes from a MapView.hitTest() or layer view query operation.
options	`GetDisplaySymbolOptions \| null \| undefined`	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.

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

getLegendLabel

Function

Since: ArcGIS Maps SDK for JavaScript 4.29

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

Signature: getLegendLabel (graphic: Graphic, view?: MapViewOrSceneView, options?: GetDisplaySymbolOptions | null | undefined): Promise<string | null | undefined>

Parameters

Parameter	Type	Description
graphic	`Graphic`	The graphic from which to retrieve its associated label as displayed in the legend. This commonly comes from a MapView.hitTest() operation.
view	`MapViewOrSceneView`	The graphic from which to retrieve the displayed symbol. This commonly comes from a MapView.hitTest() operation.
options	`GetDisplaySymbolOptions \| null \| undefined`	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.

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

Type definitions

RenderPieChartPreviewHTMLOptions

Type definition

radius

Property

Type: number | null | undefined

The radius of the pie chart in pixels.

Default value: 40

holePercentage

Property

Type: number | null | undefined

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.

Default value: 0

values

Property

Type: number[] | null | undefined

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

Property

Type: SimpleLineSymbol | null | undefined

The outline of the pie chart.

RenderRelationshipRampPreviewHTMLOptions

Type definition

node

Property

Type: HTMLElement | undefined

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

opacity

Property

Type: number | undefined

The opacity of the legend element.

Default value: 1

RenderColorRampPreviewHTMLOptions

Type definition

align

Property

Type: "horizontal" | "vertical" | null | undefined

Specifies the alignment of the color ramp.

Default value: vertical

width

Property

Type: number | null | undefined

The width of the ramp in pixels.

height

Property

Type: number | null | undefined

The height of the ramp in pixels.

gradient

Property

Type: boolean | null | undefined

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

Default value: true

cssEffectFilter

Property

Type: string | null | undefined

A CSS filter to apply to the ramp element.

ariaLabel

Property

Type: string | null | undefined

An accessible label for the ramp element.

RenderPreviewHTMLOptions

Type definition

node

Property

Type: HTMLElement | null | undefined

The parent node to append to the symbol.

size

Property

Type: number | RenderPreviewHTMLSizeOptions | null | undefined

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.

maxSize

Property

Type: number | null | undefined

The maximum size of the symbol preview in points.

opacity

Property

Type: number | null | undefined

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

scale

Property

Type: boolean | null | undefined

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.

Default value: true

disableUpsampling

Property

Type: boolean | null | undefined

Indicates whether to disable upsampling for raster images.

symbolConfig

Property

Type: "tall" | RenderPreviewSymbolConfigOptions | null | undefined

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.

rotation

Property

Type: number | null | undefined

The rotation of the symbol.

overrideText

Property

Type: string | null | undefined

Since: ArcGIS Maps SDK for JavaScript 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.

RenderPreviewHTMLSizeOptions

Type definition

width

Property

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

Property

Type: number

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

RenderPreviewSymbolConfigOptions

Type definition

isTall

Property

Type: boolean | undefined

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

Default value: false

isSquareFill

Property

Type: boolean | undefined

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

Default value: false