ArcGIS Runtime SDK for macOS

Symbolize data

In ArcGIS Runtime, for many types of geographic data, you can control how your data are displayed. Feature layers, raster layers, graphic overlays, and even vector basemaps provide the ability to alter display characteristics like size, color, rotation and so on. The rendering of geographic data is generally controlled by one or more of the following types of classes:

  • Symbol—Defines a set of display properties, such as color and size, for features and graphics (collectively referred to as geoelements).
  • Renderer—A collection of one or more symbols and logic to determine which symbol to apply to each geoelement, usually based on one or several attribute values.
  • Raster renderer—Used exclusively for raster data, these renderers determine which color to apply for each raster cell value.
  • Style—A predefined definition, available for some layer formats, of how a layer should be displayed. If more than one style is available, it can be changed dynamically.

The Symbols, renderers, and styles topic provides an overview of these classes. This topic describes how to customize the display of various types of data you might include in your app, and shows examples.

The following table describes options for symbolizing different types of data.

Data typeSymbology options



  • Apply a renderer to the feature layer or feature collection
  • Assign 3D properties (such as an extrusion expression) to the renderer for display in a scene view


Vector basemap

WMS layer

Work with symbols

ArcGIS Runtime SDK provides a variety of symbols for displaying geoelements in a map or scene. These symbols fall into one of two broad categories: simple or multilayer. You can create these symbols new, read them from a file, and make edits to their properties. See Symbol types described for an overview and a discussion of the available types of symbols.

Create simple symbols

Simple symbols follow the web map specification and you can create and work with them through the simple symbol classes in the API (AGSSimpleMarkerSymbol, AGSSimpleLineSymbol, and AGSSimpleFillSymbol). These are also the symbols you get from web maps or from feature services when advanced symbology is turned off. Each of the simple symbol types provides an enumeration of pre-defined styles that can be applied to the symbol.

//create a picture marker symbol
UIImage *image = [UIImage imageWithContentsOfFile: @"RedShinyPin.png"];
AGSPictureMarkerSymbol *pictureMarkerSymbol  = [AGSPictureMarkerSymbol pictureMarkerSymbolWithImage:image];

//create graphic
AGSGraphic *graphic = [AGSGraphic graphicWithGeometry:location symbol:pictureMarkerSymbol];
//add the graphic to the graphics overlay
[ addObject:graphic];

Text symbol with angle defined

There are various ways to create picture marker symbols. For example:

You can create a picture marker symbol from a URL:

//Create a picture marker symbol from a URL resource
//When using a URL, you need to call load to fetch the remote resource
AGSPictureMarkerSymbol *campsiteSymbol = [AGSPictureMarkerSymbol pictureMarkerSymbolWithURL:[NSURL URLWithString:@""]];

//Optionally set the size (if not set, the size in pixels of the image will be used)
campsiteSymbol.height = 18;
campsiteSymbol.width = 18;
[campsiteSymbol loadWithCompletion:^void(NSError * error) {
    //create graphic and add to graphic overlay

Traffic signals displayed with a picture marker symbol.

Create multilayer (advanced) symbols

Multilayer symbols are based on a subset of the ArcGIS Pro symbology model. These symbols are composed of one or more symbol layers and can contain different symbol types within each layer with definable behaviors to get advanced cartographic effects. You can modify properties of individual symbol layers, or use properties of the symbol itself to apply a value (color or size, for example) to all the symbol layers it contains.

There are multilayer symbol classes for displaying points (MultilayerPointSymbol), polylines (MultilayerPolylineSymbol), and polygons (MultilayerPolygonSymbol). A multilayer symbol can contain one or several symbol layers of the same or different type. A symbol used to render polygons, for example, might contain a fill symbol layer to render the polygon interior, a stroke symbol layer for rendering the polygon outline, and a marker symbol layer to render polygon vertices. For a description of the types of symbol layers available for a multilayer symbol, see the symbol layers section of the symbol types described topic.

Some symbol layers can contain additional symbol layers. A hatch fill symbol layer, for example, is composed of multilayer polyline symbols that define the hatch lines.


The order in which symbol layers are added dictates their drawing order in the symbol. The last layer in the collection will be the last layer to draw.

Multilayer hatch fill symbol.

Read symbols from a style file

For complex multilayer symbols, especially those you use frequently, it's easier to read them from a mobile style file (.stylex) than to create them from scratch. ArcGIS Pro provides an intuitive authoring environment for creating multilayer symbols. These symbols can be saved in a mobile style file (.stylex) and then consumed in your ArcGIS Runtime app.


Standard ArcGIS Pro style files and mobile styles both have a .stylex extension, but only mobile styles are supported in ArcGIS Runtime. Symbols from a standard style can be copied to a mobile style file, but may be generalized if they contain unsupported features, such as true curves or color gradients.

A mobile style can be opened in your app. Each symbol in the mobile style has a unique key, name, tags, and category. You can reference a symbol using its key or search the style to return a set of results.

You can use a symbol's key to return it from the style. You can also get several symbols from a style as a single combined symbol. The GetSymbolAsync method of a AGSSymbolStyle instance takes a list of identifiers (one or more keys) and returns a symbol that is a combination of all symbols that were found.

A combined symbol from individual style items.

Convert simple symbols to multilayer

The trade-off between simple and multilayer symbology is convenience versus control. Simple symbols are easy to create but offer a finite set of style options. Multilayer symbols often require a lot of code to create from scratch but give you fine-grained control and allow you to create more complex symbols. You might have simple symbols in your app that you'd like to convert to multilayer symbols, perhaps as a starting point for creating more complex types of symbols.

Simple marker, line, and fill symbols provide a ToMultilayerSymbol helper to convert to an equivalent multilayer symbol.

  • Simple marker symbol is converted to a multilayer point symbol. A vector marker symbol element layer is added to the symbol layer collection to represent the original marker symbol (circle, square, triangle and so on). The vector marker symbol element layer geometry is a polygon.
  • Simple line symbol is converted to a multilayer polyline symbol. A stroke symbol layer is added to the symbol layer collection to represent the original line symbol. If necessary, an effect is applied to the stroke layer to represent dash styles.
  • Simple fill symbol is converted to a multilayer polygon symbol. A hatch or solid fill symbol layer is added to the symbol layer collection depending on the fill pattern (solid, horizontal, vertical and so on).

Once a simple symbol is represented as multilayer, you can add additional layers (perhaps from other simple symbols that you converted).

Red multilayer point symbols with white hatch lines

Create 3D symbols

While you can use the same 2D symbols available for symbolizing graphics in a map view, ArcGIS Runtime provides some specialized symbols for displaying graphics in a scene view. You can display points and lines as 3D shapes or use models to realistically represent real-world objects (such as vehicles). See 3D-specific symbols for more information.

Add shape-based symbols

3D shapes, such as a cone, floating on the earth's surface.

The following code snippet shows how to create a sphere symbol and render it using a point geometry in a graphic.

// sphere symbol
AGSSimpleMarkerSceneSymbol *sphereSymbol = [[AGSSimpleMarkerSceneSymbol alloc] 
 initWithStyle:AGSSimpleMarkerSceneSymbolStyleSphere color:UIColor.redColor height:3000 width:3000 depth:3000 

// sphere point
AGSPoint *spherePoint = AGSPointMake3D(-4.04, 53.16, 1000, 0, self.sceneView.spatialReference);

// add graphic to graphics overlay    
AGSGraphic *sphereGraphic = [[AGSGraphic alloc] initWithGeometry:spherePoint symbol:sphereSymbol];
[ addObject:sphereGraphic];

Add model symbols

Model symbol representing a helicopter

Create these model symbols using the ModelSceneSymbol class.

// create the model symbol from file
NSURL *URL = [[NSURL alloc] initFileURLWithPath:@".../A310_FedEx.dae"];
AGSModelSceneSymbol *modelSymbol = [[AGSModelSceneSymbol alloc] initWithURL: URL scale:3000];        
modelSymbol.roll = -30;
[modelSymbol loadWithCompletion:^(NSError * _Nullable error) {
 if (error != nil) {
  NSLog(@"%@", error.localizedDescription);
 } else {
  AGSPoint *modelPoint = AGSPointMake3D(-4.04, 53.16, 5000, 0, self.sceneView.spatialReference);
  AGSGraphic *modelGraphic = = [[AGSGraphic alloc] initWithGeometry:modelPoint symbol:modelSceneSymbol attributes:nil];
  [ addObject:modelGraphic];

When you add a model symbol file of type .dae into your project you must ensure that the file is of type Data. For each file in your project go to the File Inspector. Find the Type property and change it from Default = Digital Asset Exchange to Data. This will ensure that Xcode does not compress the file and it will be read correctly.

Distance composite symbols

While model symbols closely resemble the real-world object they represent when viewed close up, when you zoom away from them, the symbols gets smaller until they're no longer visible. If you want to see the location of your graphics at any distance from the camera, use distance composite symbols. These symbols allow you to use different symbols depending on the distance the graphic is from the camera.

The code snippet below the following images shows how to set up a distance composite symbol similar to the one shown in the images.

When the camera is far away from the point, a red simple marker symbol displays.

A simple point is displayed when the camera is far away

As you zoom closer to the point, the symbol renders as a cone pointing in the aircraft's direction of travel.

A cone symbol shows heading at intermediate camera distance

When viewed even closer, the point displays as a model symbol, which is appropriate at this distance from the camera.

A model symbol displays at the nearest camera distance

Apply a renderer

A renderer is an object that determines how geoelements (features or graphics) are displayed. A renderer includes one or more symbols as well as logic to determine which symbol to apply for data in the layer (or graphics overlay). There are a variety of renderer types, each designed to use a different rendering logic. Renderers use attribute values to determine which symbol should be applied.

The Symbols, renderers, and styles topic provides an overview of symbols and renderers and how they work together to symbolize data.


If you apply a symbol to a graphic that is in a graphics overlay with a renderer, the symbol on the graphic will take precedence over the renderer.

ArcGIS Runtime SDK provides simple, unique value, class breaks, and dictionary renderers for displaying geoelements.

The following steps describe the process for defining a renderer for a feature layer or graphics overlay. Dictionary renderers are described in the Display military symbols with a dictionary renderer topic. See the Raster renderers section for examples of changing raster display.

  1. Create a new renderer of the desired type: simple, unique value, or class breaks.
  2. Create the symbol(s) required by the renderer and appropriate for the geometry type. The Symbol types described topic provides an overview of the available ArcGIS Runtime symbols.
  3. Define the logic that the renderer needs in order to apply the correct symbol for each geoelement. Depending on the type of renderer, this could be one or several attribute names or ranges of values for a given numeric attribute. A simple renderer always applies a single symbol to all geoelements.
  4. For unique value or class breaks renderers, associate the desired symbol for each range or unique value defined in the renderer.
  5. Apply the renderer by assigning it to the to the feature layer or graphics overlay.

Simple renderer

A simple renderer uses one symbol for all features in a layer (or all graphics in an overlay) regardless of attribute values.

//create a simple symbol for use in a simple renderer
UIColor *color = [UIColor colorWithRed:1.0 green:0.0 blue:0.0 alpha:1.0];
AGSSimpleMarkerSymbol *symbol = [AGSSimpleMarkerSymbol simpleMarkerSymbolWithStyle:AGSSimpleMarkerSymbolStyleCross color:color size:12.0];
AGSSimpleRenderer *renderer = [[AGSSimpleRenderer alloc] initWithSymbol:symbol];

//apply the renderer to the graphics overlay (so all graphics will use the same symbol from the renderer)
graphicsOverlay.renderer = renderer;

Unique value renderer

A unique value renderer symbolizes features in a layer (or graphics in an overlay) differently based one or more of their attribute values. It's useful for symbolizing features based on an attribute whose values represent names or categories, usually referred to as nominal data. Unlike graphics, features do not have a symbol property and therefore cannot be assigned an individual symbol. However, you can use a unique value renderer to set symbology on a layer based on each feature's attribute values. (You can do this for graphics, too).


ArcGIS map services allow up to three fields to be used for unique value renderers. An ArcGIS feature service allows only one. As a developer, you can specify as many fields as you like, ensuring that the order of the fields you specify corresponds to the order of the values you specify.

// Create service feature table
AGSServiceFeatureTable *serviceFeatureTable = [AGSServiceFeatureTable serviceFeatureTableWithURL:[NSURL URLWithString:sampleServiceString]];
// Create the feature layer using the service feature table
AGSFeatureLayer *featureLayer = [[AGSFeatureLayer alloc] initWithFeatureTable:serviceFeatureTable];
// Override the renderer of the feature layer with a new unique value renderer
AGSUniqueValueRenderer *uniqueValueRenderer = [AGSUniqueValueRenderer uniqueValueRenderer];
// Set the field to use for the unique values
uniqueValueRenderer.fieldNames = @[@"STATE_ABBR"];
//You can add multiple fields to be used for the renderer in the form of a list, in this case we are only adding a single field
// Create the symbols to be used in the renderer
AGSSimpleFillSymbol *defaultFillSymbol = [AGSSimpleFillSymbol simpleFillSymbolWithStyle:AGSSimpleFillSymbolStyleNull
 color:[UIColor colorWithRed:0.0 green:0.0 blue:0.0 alpha:0.0]
 outline:[AGSSimpleLineSymbol simpleLineSymbolWithStyle:AGSSimpleLineSymbolStyleSolid
  color:[UIColor colorWithRed:0.8 green:0.8 blue:0.8 alpha:1.0]
AGSSimpleFillSymbol *californiaFillSymbol = [AGSSimpleFillSymbol simpleFillSymbolWithStyle:AGSSimpleFillSymbolStyleNull
 color:[UIColor colorWithRed:1.0 green:0.0 blue:0.0 alpha:1.0]
 outline:[AGSSimpleLineSymbol simpleLineSymbolWithStyle:AGSSimpleLineSymbolStyleSolid                                                                                                                                    
  color:[UIColor colorWithRed:1.0 green:0.0 blue:0.0 alpha:1.0]                                           
AGSSimpleFillSymbol *arizonaFillSymbol = [AGSSimpleFillSymbol simpleFillSymbolWithStyle:AGSSimpleFillSymbolStyleNull
 color:[UIColor colorWithRed:0.0 green:1.0 blue:0.0 alpha:1.0]
 outline:[AGSSimpleLineSymbol simpleLineSymbolWithStyle:AGSSimpleLineSymbolStyleSolid
  color:[UIColor colorWithRed:0.0 green:1.0 blue:0.0 alpha:1.0]                                            
AGSSimpleFillSymbol *nevadaFillSymbol = [AGSSimpleFillSymbol simpleFillSymbolWithStyle:AGSSimpleFillSymbolStyleNull
 color:[UIColor colorWithRed:0.0 green:0.0 blue:1.0 alpha:1.0]
 outline:[AGSSimpleLineSymbol simpleLineSymbolWithStyle:AGSSimpleLineSymbolStyleSolid                                            
  color:[UIColor colorWithRed:0.0 green:0.0 blue:1.0 alpha:1.0]                                                                                                                                
// Set default symbol
uniqueValueRenderer.defaultSymbol = defaultFillSymbol;
uniqueValueRenderer.defaultLabel = @"Other";
// create unique value for california
AGSUniqueValue *californiaValue = [AGSUniqueValue uniqueValueWithDescription:@"State of California" label:@"California"symbol:californiaFillSymbol values:@[@"CA"]];
// create unique value for arizona
AGSUniqueValue *arizonaValue = [AGSUniqueValue uniqueValueWithDescription:@"State of Arizona" label:@"Arizona" symbol:arizonaFillSymbol values:@[@"AZ"]];
// create unique value for nevada
AGSUniqueValue *nevadaValue = [AGSUniqueValue uniqueValueWithDescription:@"State of Nevada" label:@"Nevada" symbol:nevadaFillSymbol values:@[@"NV"]];
// set the unique values on the renderer
uniqueValueRenderer.uniqueValues = @[californiaValue, arizonaValue, nevadaValue];
// Set the renderer on the feature layer
featureLayer.renderer = uniqueValueRenderer;

Unique value renderer applied to some US states

Features whose attribute value falls outside the classes defined for the renderer are symbolized with the default symbol. If a default symbol is not defined, those features won't display.

Class breaks renderer

Use a class breaks renderer to symbolize quantitative information about feature data. Class breaks symbology divides the range of feature values into a relatively small number of classes. For example, you can use a class breaks renderer to symbolize geoelements by population value, dividing the features into three classes of low, medium, and high population value.

One symbol is associated with each class, and is used to render geoelements whose attribute value falls within the range defining the class. For example, with polygons, you could use a yellow fill symbol to represent low population, an orange fill for medium population, and red fill for high population. If a geoelement has an attribute value that falls outside all class ranges, a default symbol can be applied (or no symbol).

Symbol color is an effective way to represent differences in magnitude of a phenomenon because it is easy to distinguish variations in color if there are relatively few classes. A range of seven colors is the approximate upper limit of colors that can be easily distinguished on a map. Avoid using too many classes, especially if you are using light colors.

A class breaks renderer can be used for any geometry type and the symbols do not have to only vary by color. For example, a line feature class representing roads with associated numeric values for traffic density can be rendered using different line widths for high, medium, and low traffic. City points can be classified with a range of circular marker symbols with different sizes or colors (or both) based on population.

The following image shows a class breaks renderer with three class breaks. The US States layer is classified by three ranges of population for the year 2007.

A class breaks renderer applied to a US States layer to show classes of population.

3D renderer properties

When using renderers in 3D, you can set properties to define extrusion expressions for both features and graphics. For graphics you can also define a rotation expression to control heading, pitch, and roll.

Extrusion is the process of stretching a flat 2D shape vertically to create a 3D object. This provides a simple method to create three-dimensional symbology from two-dimensional features. For example, you can extrude building polygons by a height value to create realistic building shapes. You can also use extrusion to illustrate relative values in your data. The three basic geometry types-points, lines, and polygons-all support extrusion.


Extrusion may not work with some types of multilayer symbols, such as hatch fills.

To apply extrusion to a feature layer:

  1. Set the feature layer to rendering in DYNAMIC mode
  2. Define a renderer which will be used to render the feature layer
  3. Set the renderer's scene property extrusion mode
  4. Set the renderer's scene property extrusion expression
  5. Set the renderer to the feature layer
  6. Add the feature layer to the scene

Extrusion can also be applied to graphics overlays:

  1. Define a renderer which will be used to render the graphics overlay
  2. Set the renderer's scene property extrusion mode
  3. Set the renderer's scene property extrusion expression
  4. Set the renderer to the graphics overlay

// define fill and outline for symbol       
AGSSimpleLineSymbol *line = [[AGSSimpleLineSymbol alloc] initWithStyle:AGSSimpleLineSymbolStyleSolid color:UIColor.blackColor width:1];    
AGSSimpleFillSymbol *fill = [[AGSSimpleFillSymbol alloc] initWithStyle:AGSSimpleFillSymbolStyleSolid color:UIColor.greenColor outline:line];

// create a simple renderer
AGSSimpleRenderer *renderer = [[AGSSimpleRenderer alloc] initWithSymbol:fill];
// define the extrusion mode and expression
renderer.sceneProperties.extrusionMode = AGSExtrusionModeAbsoluteHeight;
renderer.sceneProperties.extrusionExpression = @"pop2000";
graphicsOverlay.renderer = renderer;

The following image shows a graphic overlay of US counties extruded based on a population attribute.

County polygons extruded on population

Only graphics overlays can have rotation expressions--used to change the heading, pitch and roll of the graphics in the graphics overlay. To set rotation expressions:

  1. Define a renderer which will be used to render the graphics overlay
  2. Set the rotation type
  3. Set the renderer's scene property heading expression
  4. Set the renderer's scene property pitch expression
  5. Set the renderer's scene property roll expression
  6. Set the renderer to the graphics overlay

// create a simple renderer and set rotation expressions
AGSSimpleRenderer *renderer = [[AGSSimpleRenderer alloc] initWithSymbol:coneSymbol];
renderer.sceneProperties.headingExpression = @"heading";
renderer.sceneProperties.pitchExpression = @"pitch";
renderer.sceneProperties.rollExpression = @"roll";

Raster renderers

When initially created, a default renderer is used to display a raster layer. To customize the display, you can create a raster renderer to define display properties and apply it to the layer.

AGSRasterRenderer is the base class inherited by all renderers available to display a raster layer and allows you to control how raster data are presented (visualized). Each of the following renderers are types of AGSRasterRenderer and can be used to display your raster layer in different ways.

  • AGSHillshadeRenderer—Creates a grayscale 3D representation of an elevation surface, with the sun's (hypothetical) position taken into account for shading the image. It can be applied to a raster layer created with single-band raster data.
  • AGSBlendRenderer—Blends a hillshade image (derived from the raster) with the original raster. This provides a look similar to the original raster but with some terrain shading, for a rich, textured look.
  • AGSColormapRenderer—Provides a discrete mapping of raster pixel values to colors. All pixels matching the specified value are rendered using the mapped color. This can be useful for tasks such as land classification.
  • AGSStretchRenderer—Displays continuous raster cell values across a gradual ramp of colors. Use the stretch renderer to draw a single band of continuous data. The stretch renderer works well when you have a large range of values to display, such as in imagery, aerial photographs, or elevation models.
  • AGSRGBRenderer—Uses the same methods as the stretch renderer but allows you to combine bands as red, green, and blue composites.

Blend renderer showing elevation with hillshade

Raster functions can also be used to apply on-the-fly processing to rasters to apply hillshade, colormaps, color ramps, and so on. See the Add raster data topic for more information.

Raster rendering rules

A rendering rule defines how a requested raster image should be rendered or processed. AGSImageServiceRaster allows you to apply service-defined or client-defined rendering rules on an image service by setting its rendering rule property. You can create a AGSRenderingRule from a AGSRenderingRuleInfo object or a JSON string that specifies a service-defined or client-defined rendering rule and then set it on the image service raster. For the syntax of rendering rules, see raster function (JSON) objects in the ArcGIS REST API help.

Alternatively you can create a AGSRenderingRule using a JSON string that specifies a service-defined or client-defined rendering rule.

Symbolize graphics

Graphics provide a basic way to display geometry on top of the map. Graphics are unique in that they can be symbolized using a renderer for the overlay that contains them or by applying a symbol directly to the graphic. For a description of how to work with graphics, see Add graphics and text to graphics overlays. To apply symbols to features (as opposed to graphics), create a renderer.

The following example shows how to create a point graphic, apply a symbol, then display it on the map.

//create a simple marker symbol
UIColor *color = [UIColor colorWithRed:1.0 green:0.0 blue:0.0 alpha:1.0];
AGSSimpleMarkerSymbol *symbol = [AGSSimpleMarkerSymbol simpleMarkerSymbolWithStyle:AGSSimpleMarkerSymbolStyleCircle color:color size:12.0];

//add a new graphic with a new point geometry
AGSPoint *graphicPoint = [[AGSPoint alloc] initWithX:-226773 y:6550477 spatialReference:[AGSSpatialReference webMercator]];
AGSGraphic *graphic = [AGSGraphic graphicWithGeometry:graphicPoint symbol:symbol];
[ addObject:graphic];


A symbol applied directly to a graphic overrides the symbol applied through the graphics overlay's renderer.

Apply styles to layers

Some layers that don’t support symbols and renderers, such ArcGIS vector tiled layers and WMS, offer styles as a way to control the display of the features they contain. These layers use a default style and also provide the option to apply other available styles.


The styles described here are not the styles you can create using ArcGIS Pro (.stylex). For information about reading symbols from such a style file, see Read symbols from a map or style file.

ArcGIS vector tiled layer styles

With ArcGIS Runtime SDK you can display vector basemaps with your own custom style. The ArcGIS Vector Tile Style Editor allows you to interactively create a style for one of the Esri vector basemaps and save it in ArcGIS Online as a portal item. You can then open it from the portal item to display it in your map with the custom style.

The ArcGIS Vector Tile Style editor

WMS styles

WMS servers provide clients with a list of supported styles for each layer. At run time, you can choose which style the WMS server uses to render map images. In general, styles are predefined and cannot be changed or added to.

The styles property of the AGSWMSLayerInfo class can be inspected to determine if there are styles available. The current style property of a WMS sublayer can be set to select a specific style.