symbolUtils

AMD: require(["esri/symbols/support/symbolUtils"], (symbolUtils) => { /* code goes here */ });
ESM: import * as symbolUtils from "@arcgis/core/symbols/support/symbolUtils";
Object: esri/symbols/support/symbolUtils
Since: ArcGIS API for JavaScript 4.11

Generates small preview images of symbols. This utility can be useful when creating custom widgets that require displaying small previews of symbols used to represent features in a layer.

Method Overview

Name Return Type Summary Object
Promise<Color>

Returns a color representing the input graphic's symbol.

more details
symbolUtils
Promise<Symbol>

Returns a symbol representing the input Graphic.

more details
symbolUtils
HTMLElement

Generates a preview image of a color ramp to display in a custom widget or other DOM element.

more details
symbolUtils
Promise<HTMLElement>

Generates a preview image of a given symbol that can be displayed in a custom widget or other DOM element.

more details
symbolUtils

Method Details

getDisplayedColor(graphic, options){Promise<Color>}
Since: ArcGIS API 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 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
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 Renderer
optional

The renderer of the layer associated with the graphic.

resolution Number
optional

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

Returns
Type Description
Promise<Color> 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(graphic, options){Promise<Symbol>}

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 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 symbol. This commonly comes from a hitTest() operation.

options Object
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 Renderer
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<Symbol> 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
  });
});
renderColorRampPreviewHTML(colors, options){HTMLElement}
Since: ArcGIS API for JavaScript 4.13

Generates a preview image of a color ramp to display in a custom widget or other 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);
renderPreviewHTML(symbol, options){Promise<HTMLElement>}

Generates a preview image of a given symbol that can be displayed in a custom widget or other DOM element.

Parameters
Specification
symbol Symbol

The symbol for which to generate a preview image.

options Object
optional

Formatting options for the symbol preview image.

Specification
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
optional

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
optional

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

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