ArcGIS API for JavaScript

CIM Symbol Builder

The 4.18 release of the ArcGIS API for JavaScript introduced an app called the CIM Symbol Builder. This app allows you to visually design a CIM symbol and export the symbol to a JSON string for use in a web application built with the ArcGIS API for JavaScript.

CIM symbol builder
Use the CIM Symbol Builder to create custom symbols - like this trailhead symbol.

CIMSymbols are multi-layer vector symbols for features and graphics used throughout the ArcGIS platform. They provide unlimited flexibility so that you can create very elaborate and intricate symbols. Previously, such symbols could only be achieved using pre-generated images rendered as PictureMarkerSymbols.

CIM symbols are rendered based on the definition stored in the data property. This property is a well-defined JSON string that complies with the CIM specification, which can be difficult to author from scratch. This app can be a handy tool for developers, allowing them to get immediate visual feedback when altering the CIM JSON. It also allows users to create CIM symbols by combining pre-existing symbols and modifying their attributes.

Add a symbol layer

Start by adding symbol layer(s) from the symbol gallery. Click the ADD SYMBOL LAYER button and choose a symbol layer from the pre-defined symbols in the Icons, Shapes, or Custom categories.

Symbol Gallery
Choose a predefined symbol from the Symbol Gallery to start building your CIM Symbol.

Or you can import your own symbol by adding symbol JSON in the custom tab of the symbol gallery.

Import symbol from CIM JSON

You can also import a web style from the “+” tab.

Import webstyle

Edit symbol layer properties

Edit the properties of the symbol layers until you have your desired symbol. There are three supported symbol layers in the CIM Symbol Builder – each will have different properties that can be modified.


Most of the symbol layers in the pre-defined symbol gallery are CIMVectorMarker symbol layers. Click on the symbol layer name to access the properties to edit. You will be able to change properties like size, rotation, anchor point, and offset.

edit symbol layer properties
Click the symbol layer to edit its associated properties. In this image, we rotate the original symbol clockwise by 90 degrees.

You can expand the layers in the symbol editor to get to the embedded layers within the specified layer. From there, you will be able to access additional properties that you can customize, such as the color and opacity of the embedded CIMSolidFill or CIMSolidStroke.

Edit color of the symbol fill


CIMPictureMarker allows you to add a picture as a symbol layer in your symbol. We recommend using an image data URI for the URL property of a CIMPictureMarker to avoid any potential cross domain (CORS) issues. Keep in mind that the color of the image will not change if any color visual variables are applied to the symbol. You can add a CIMPictureMarker symbol from the “Custom” tab in the symbol library.

add CIMPictureMarker


A text layer can be considered as a special type of CIMVectorMarker layer – it is an embedded text symbol in a CIMMarkerGraphic of a CIMVectorMarker. To edit the properties of the text symbol, you must click the CIMMarkerGraphic to access its properties. You can add a text layer from the “Custom” tab in the symbol gallery.

edit text properties
Editing the text properties takes place on the CIMMarkerGraphic

View your symbol on the map

You can test your symbol on the map by clicking the APPLY TO FEATURE LAYER button. This will apply the symbol you created to the renderer of the feature layer.

apply symbol to feature layer

Get the symbol JSON

Once you are satisfied with the way your symbol looks, you can copy out the symbol JSON to add it to your own app! Use the GET SYMBOL JSON button to see the symbol’s JSON. Then, click the COPY JSON button to quickly copy the JSON to your clipboard to use it in your app. The symbol JSON should be applied to the property, like this:

// Modules required: 
// esri/symbols/CIMSymbol

var symbol = new CIMSymbol({
    data: {
        type: "CIMSymbolReference",
        symbol: {} // ENTER SYMBOL JSON HERE

You can test the symbol JSON you created in this Codepen. Simply replace the value of cimSymbolJSON on line 43 with your symbol JSON.

Final notes

In most cases SimpleMarkerSymbol, PictureMarkerSymbol, or other familiar and easy-to-use symbols will satisfy your requirements. However, some of your apps may require elaborate symbols that cannot be rendered with these traditional symbols. That’s where CIM symbols come in. This article introduces a visual editor for CIM marker symbols that saves you the effort of learning the CIM spec and editing raw JSON. We can’t wait to see the awesome symbols that you create using the CIM Symbol Builder!

This app currently only supports CIMPointSymbols. Line and polygon symbols are not currently supported.


About the authors

Fang is a product engineer on the ArcGIS API for JavaScript team.


Anne is a Product Engineer on the ArcGIS API for JavaScript team in Redlands, CA.


Leave a Reply

Please Login to comment

Next Article

What's new in ArcGIS Maps for Adobe Creative Cloud (July 2021)

Read this article