CIMSymbol

AMD: require(["esri/symbols/CIMSymbol"], (CIMSymbol) => { /* code goes here */ });
ESM: import CIMSymbol from "@arcgis/core/symbols/CIMSymbol";
Class: esri/symbols/CIMSymbol
Inheritance: CIMSymbol Symbol Accessor
Since: ArcGIS API for JavaScript 4.12

CIMSymbols are used to display multi-layer vector symbols for features and graphics. They allow the user to add more customizations to their symbols, using one or more symbol layers to create the desired effect on the symbol. CIMSymbols can be created from CIMSymbolReference JSON that complies with the CIM specification by passing the JSON to the data property. CIMSymbols can also be created from WebStyleSymbols, using WebStyleSymbol.fetchCIMSymbol().

To get or set the values for color, rotation, and size on the CIMSymbol, use the utility functions found in cimSymbolUtils.

Examples:

CIMPointSymbol

The code snippet below shows an example of creating a CIMPointSymbol with one CIMVectorMarker layer which contains a triangle marker graphic as shown below.

CIMSymbol

const symbol = new CIMSymbol({
  data:  {
    type: "CIMSymbolReference",
    symbol: {
       type: "CIMPointSymbol",
       symbolLayers: [{
           type: "CIMVectorMarker",
           enable: true,
           size: 32,
           frame: {
             xmin: 0,
             ymin: 0,
             xmax: 16,
             ymax: 16
           },
           markerGraphics: [{
             type: "CIMMarkerGraphic",
             geometry: {
               rings: [[[8, 16],[0, 0],[16, 0],[8, 16]]]
             },
             symbol: {
               type: "CIMPolygonSymbol",
               symbolLayers: [{
                 type: "CIMSolidStroke",
                 width: 5,
                 color: [240, 94, 35, 255]
               }]
             }
           }]
       }]
    }
  }
});

Click read more below to see examples for CIMLineSymbol and CIMPolygonSymbol.

CIMLineSymbol

Since 4.16

The code snippet below shows an example of a CIMLineSymbol with one CIMSolidStroke layer with a dash effect on top of another CIMSolidStroke layer as shown below.

CIMLineSymbol

const lineSymbol = new CIMSymbol({
  data: {
    type: "CIMSymbolReference",
    symbol: {
       type: "CIMLineSymbol",
       symbolLayers: [{
         type: "CIMSolidStroke",
         effects: [{
           type: "CIMGeometricEffectDashes",
           dashTemplate: [5, 5],
           lineDashEnding: "FullGap",
           controlPointEnding: "NoConstraint"
         }],
         enable: "true",
         capStyle: "Butt",
         joinStyle: "Round",
         width: 2.6,
         color: [255, 255, 255, 255]
       },
       {
         type: "CIMSolidStroke",
         enable: true,
         capStyle: "Butt",
         joinStyle: "Round",
         width: 3.4,
         color: [0, 0, 0, 255]
       }]
    }
  }
});

CIMPolygonSymbol

Since 4.16

The code snippet below shows an example of a CIMPolygonSymbol with a CIMSolidStroke layer and a CIMSolidFill layer.

CIMPolygonSymbol

const polygonSymbol = new CIMSymbol({
  data: {
     type: "CIMSymbolReference",
     symbol: {
       type: "CIMPolygonSymbol",
       symbolLayers: [{
         type: "CIMSolidStroke", // outlines the polygon
         enable: "true",
         width: 0.4,
         color: [0, 92, 100, 255]
       },
       {
         type: "CIMSolidFill", // fills the polygon
         enable: true,
         color: [151, 219, 100, 150]
       }]
     }
  }
});

CIMPolygonSymbol with markerPlacement

Since 4.16

The code snippet below shows an example of a CIMPolygonSymbol with CIMVectorMarker symbols placed inside the polygon.

CIMPolygonWithMarkers

const markerPolygonSymbol = new CIMSymbol({
   data: {
     type: "CIMSymbolReference",
     symbol: {
       type: "CIMPolygonSymbol",
       symbolLayers: [{
         type: "CIMVectorMarker",
         enable: true,
         size: 10,
         markerPlacement: {
           type: "CIMMarkerPlacementInsidePolygon",
           gridType: "Fixed",
           seed: 13,
           stepX: 16,
           stepY: 16,
           clipping: "ClipAtBoundary",
         },
         markerGraphics: [{
           type: "CIMMarkerGraphic",
           geometry: {
             rings: [
               [
                 [0,5],
                 [1.12,1.55],
                 [4.76,1.55],
                 [1.82,-0.59],
                 [2.94,-4.05],
                 [0,-1.91],
                 [-2.94,-4.05],
                 [-1.82,-0.59],
                 [-4.76,1.55],
                 [-1.12,1.55],
                 [0,5]
               ]
             ]
           },
           symbol: {
             type: "CIMPolygonSymbol",
             symbolLayers: [{
               type: "CIMSolidFill",
               enable: true,
               color: [190,210,255,255]
             }]
           }
         }],
         scaleSymbolsProportionally: true,
         respectFrame: true
       },
       {
         type: "CIMSolidFill",
         enable: true,
         color: [0,112,255,255]
       }]
     }
   }
});

Known Limitations

See also:

Constructors

new CIMSymbol(properties)
Parameter:
properties Object
optional

See the properties for a list of all the properties that may be passed into the constructor.

Property Overview

Any properties can be set, retrieved or listened to. See the Working with Properties topic.
Show inherited properties Hide inherited properties
Name Type Summary Class
CIMSymbolReferencemore details

The JSON payload of the CIMSymbolReference.

more detailsCIMSymbol
Stringmore details

The name of the class.

more detailsAccessor
Stringmore details

The symbol type.

more detailsCIMSymbol

Property Details

The JSON payload of the CIMSymbolReference. The CIMSymbolReference is comprised of the symbol, primitive overrides, and scale.

Symbol: The symbol property can be of type CIMPointSymbol, CIMLineSymbol, CIMPolygonSymbol, or CIMTextSymbol. Each symbol is made up of one or more symbolLayers. CIMTextSymbol is an exception - it has native properties, but no symbol layers. Symbol layers are the building blocks of CIM symbols, they combine to make rich graphical depictions. You can configure the shape, color, texture, size, position, etc of each symbol layer, and combine multiple symbol layers to create your desired symbol. The CIM Symbol Builder provides a simple user interface to experiment with symbol layers and their properties.

Primitive overrides: Primitive overrides allow you to use Arcade expressions to dynamically change many symbol layer properties from data values. Primitive overrides are defined on the primitiveOverrides property - this property takes in an array of objects, each object representing a primitive override on a specific symbol layer.

Minimum and maximum scale: (Since version 4.20) The minScale and maxScale values will determine the scale values at which your symbol will be visible in the view. To show your symbol at all scales, these properties can either be ignored or set to 0.

Example:
const cimSymbol = new CIMSymbol({
  data: {
    type: "CIMSymbolReference",
    minScale: 750000, // only allow the symbol to be shown at certain scales
    maxScale: 80000,
    symbol: {
      type: "CIMLineSymbol",
      symbolLayers: [{ ... }]
    },
    primitiveOverrides: [{
      type: "CIMPrimitiveOverride",
      primitiveName: "symbol-layer-1", // the name of the symbol layer we want to override
      propertyName: "Size", // the name of the property on the symbol layer we want to override
      valueExpressionInfo: {
        type: "CIMExpressionInfo",
        title: "Size override",
        expression: "..." // the expression to change the size of the symbol
      }
    }]
  }
});
declaredClass Stringreadonly inherited

The name of the class. The declared class name is formatted as esri.folder.className.

type Stringreadonly

The symbol type.

For CIMSymbol the type is always "cim".

Method Overview

Show inherited methods Hide inherited methods
Name Return Type Summary Class
CIMSymbolmore details

Creates a deep clone of the symbol.

more detailsCIMSymbol
*more details

Creates a new instance of this class and initializes it with values from a JSON object generated from an ArcGIS product.

more detailsSymbol
Objectmore details

Converts an instance of this class to its ArcGIS portal JSON representation.

more detailsSymbol

Method Details

clone(){CIMSymbol}

Creates a deep clone of the symbol.

Returns:
Type Description
CIMSymbol A deep clone of the object that invoked this method.
Example:
// Creates a deep clone of the graphic's symbol
let symLyr = graphic.symbol.clone();
fromJSON(json){*}static

Creates a new instance of this class and initializes it with values from a JSON object generated from an ArcGIS product. The object passed into the input json parameter often comes from a response to a query operation in the REST API or a toJSON() method from another ArcGIS product. See the Using fromJSON() topic in the Guide for details and examples of when and how to use this function.

Parameter:
json Object

A JSON representation of the instance in the ArcGIS format. See the ArcGIS REST API documentation for examples of the structure of various input JSON objects.

Returns:
Type Description
* Returns a new instance of this class.
toJSON(){Object}inherited

Converts an instance of this class to its ArcGIS portal JSON representation. See the Using fromJSON() guide topic for more information.

Returns:
Type Description
Object The ArcGIS portal JSON representation of an instance of this class.

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