ArcGIS Maps SDK for JavaScript

CIM Symbol Builder

The CIM Symbol Builder allows you to visually design a point, line, or polygon CIM symbol and export the symbol to a JSON string for use in a web application built with the ArcGIS API for JavaScript.

Use the CIM Symbol Builder to create custom vector symbols.

CIMSymbols are multi-layer vector symbols for features and graphics used throughout the ArcGIS platform. They provide a lot of 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. The CIM Symbol Builder 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.

Select a symbol type

The ArcGIS API for JavaScript supports point, line, and polygon CIM symbols. Select the symbol type that you want to create from the dropdown to get started.


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, Lines, Fills, or Custom categories.

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

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

Edit symbol layer properties

Edit the properties of the symbol layers until you have your desired symbol. There are many supported symbol layers in the CIM Symbol Builder – each will have different properties that can be modified, depending on the symbol type selected.

Marker symbol layers

Stroke symbol layers

Fill symbol layers

Marker symbol layers


All of the symbol layers under the “Icons” and “Shapes” tabs 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.

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

Using the arrow next to the symbol layer name in the symbol editor, you can expand the layers to get access to embedded layers. 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.


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. You can add a CIMPictureMarker symbol from the “Custom” tab in the symbol library.


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.

Editing the text properties takes place on the CIMMarkerGraphic.

Marker symbols within a line or polygon

If a marker symbol is added when Line or Polygon is selected as the symbol type, then marker placement properties will appear that will allow you to configure how the marker is placed in the line or polygon symbol.

Stroke symbol layers

There are two types of stroke symbol layers that can be used with a line or polygon symbol: CIMSolidStroke and CIMPictureStroke. These symbol layers will not be visible when added to a point symbol. If added to a polygon symbol, they will display as the outline around the polygon.


The CIMSolidStroke symbol layer is pretty straightforward – it creates a stroke symbol of a solid color. You can update the color, opacity, width, cap style, and join style.



CIMPictureStroke is similar to the CIMPictureMarker symbol, except it will draw the picture provided continuously along the line.

Geometric Effects

Both of these symbol layers support geometric effects, which transform the style of your stroke symbol. To add an effect, scroll down to the bottom of the layer properties panel, select the effect you want from the dropdown, and click “Add effect”. Once the effect is added, click the down arrow next to the effect name to update the properties. Beneath the properties, you also have the option to delete the effect. You can add multiple effects if you want – just play around with it and see how it looks!

Fill symbol layers

There are three types of fill symbol layers that can be added to a polygon symbol: CIMSolidFill, CIMPictureFill, and CIMHatchFill. These symbol layers will not display for a point or line symbol.

CIMSolidFill & CIMPictureFill

CIMSolidFill will display a solid color inside the polygon graphic. CIMPictureFill will fill the polygon with a picture. These are similar to the other symbol layer types for stroke symbol layers that we just discussed.


CIMHatchFill is unique though – this allows you to define a line symbol that will fill the polygon graphic repeatedly at a defined rotation and separation. You can also update the line symbol by changing the color, width, adding effects, etc.

Similar to the stroke symbol layers, all fill symbol layer types also support effects.

View your symbol on the map

You can test your symbol on the map by clicking the Apply to feature layer button. Based on the symbol type you have selected, this will apply the symbol you created to the renderer of the corresponding point, line, or polygon feature layer.

Since "polygon" is the selected feature type, this symbol will be applied to the polygon feature layer in the map.

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 pointSymbolJSON (line 37), lineSymbolJSON (line 38), or polygonSymbolJSON (line 39) 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 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!


About the authors

Anne Fitz is a Senior Product Engineer at Esri, working on the ArcGIS Maps SDK for JavaScript and ArcGIS Arcade. Her expertise primarily focuses on dynamic vector symbology (CIM symbols), data visualization, animation, ArcGIS Arcade integration, and widgets. Anne’s primary goal is to help developers succeed in building geospatial applications, providing them with the tools and knowledge they need to bring their ideas to life. She has been with Esri for over five years.


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

Notify of
1 Comment
Inline Feedbacks
View all comments

Next Article

Generative AI in Urban Planning

Read this article