Skip To Content ArcGIS for Developers Sign In Dashboard

Add labels

Features and graphics in your ArcGIS Runtime SDK app can be labeled using a combination of attribute values, text strings, and values calculated with an expression. You can determine how labels are positioned and prioritized, and how conflicts between overlapping labels are automatically and dynamically resolved. Define any number of label classes for a layer to set unique labels for distinct groups of features.


Label classes on Feature Layers in ArcGIS Pro are used to generate dynamic labels (which resize and move with changes in the map view). Should the position and size of text need to be fixed, you can convert labels to static annotation features in an Annotation layer using ArcGIS Pro.

Define labels for features or graphics

Feature layers and graphics overlays provide the ability to show or hide labels in the map and to control a variety of labeling behavior. A label definition is used to specify:

  • what labels look like (font, size, color, angle, and so on)
  • at which scales they should be visible
  • the text to display (which attributes, for example)
  • which features should be labeled
  • how to handle overlaps and prioritize labels
If you want to label all features in your layer the same way, you can define labeling with a single label definition. If you want to display different labels for different types of features, you can add as many label definitions as you need to define distinct sets of features for labeling. For graphics overlays and feature layers, labels are rendered by the client app.


At this release, labeling of feature layers and graphics overlays is only supported in 2D (maps). In 3D (scenes), only map image sublayer labeling is supported.

A label definition is constructed as a JSON string using the syntax defined in the Web map specification for label definition. In order to provide a more accurate representation of labels created in ArcGIS Pro (for a mobile map package, for example), ArcGIS Runtime defines additional JSON properties that are not included in the Web map specification. Refer to the JSON label class properties topic for a description of the available properties, their expected values, and the defaults used for each.

Most properties in the label definition are optional and will use a default value if not assigned explicitly. At a minimum, you must provide a labelExpressionInfo (or labelExpression), a labelPlacement option, and a symbol (with at least color, font size, and type) to display labels for a layer. The JSON below provides the most basic label definition for a layer.

    "expression": "return $feature.address;"
  "labelPlacement": "esriServerPolygonPlacementAlwaysHorizontal",
    "color": [255,0,255,123],
    "font": { "size": 16 },
    "type": "esriTS"

The preceding example uses an Arcade expression for the labelExpressionInfo to label each feature with the value of its address attribute. See the Arcade documentation for information about working with Arcade expressions across the ArcGIS platform. The use of Arcade expressions is recommended when labeling feature layers or graphics overlays.


Label definitions for a map image layer must use the ArcGIS Server REST API for label expressions. Arcade expressions are not supported for labels rendered by ArcGIS Server.

In your ArcGIS Runtime SDK code, the JSON label definitions are managed by the LabelDefinition class. Two static methods on the class, fromJSON and toJSON, allow you to serialize and deserialize JSON label definitions. Feature layers, map image sublayers, and graphics overlays all maintain a collection of label definitions in a labelDefinitions property. Labels for a layer or graphics overlay can be shown or hidden using the labelsEnabled property.


ArcGIS Runtime will render labels for web map layers that have label definitions stored with them. You can use the LabelDefinition.toJSON method to deserialize label definitions stored with a web map to a JSON string.

Common aspects of label behavior that you can control for a label class are described in the following section (JSON property names in parentheses). For a comprehensive list that includes expected values, defaults, and some examples see the JSON label class properties topic.

  • Label text (labelExpressionInfo.expression)—A label expression can be used to determine the text to display for each feature in the label definition. The label text can come from a combination of available attributes, text strings, and expressions. A label showing length in meters from values in feet from an attribute named length_ft, for example, may look like this: ($feature.length_ft * 0.3048) + ' meters'. A feature with a length_ft value of 343 would result in a label of 104.546 meters.
  • Text symbol (symbol)—The font, size, color, angle, and so on, used to display labels in the definition. You can also provide a border or background for the label symbol.
  • Maximum scale (maxScale)—The largest scale at which labels in the definition are shown. This value represents the scale denominator for the zoomed-in scale; a value of 0 means a maximum scale is not applied.
  • Minimum scale (minScale)—The smallest scale at which labels in the definition are shown. This value represents the scale denominator for the zoomed-out scale; a value of 0 means a minimum scale is not applied.
  • Placement (labelPlacement)—Labels can be placed at a specified position relative to the features they describe. There are different options for placement depending on the geometry of the feature being labeled. Line features, for example, may have labels placed above the center of the line, below the center of the line, above the end point, and so on.
  • Position (deconflictionStrategy)—Logic for positioning labels can be controlled using a variety of options, such as whether they should be allowed to overlap with features in the layer.
  • Priority (priority)—A label definition can be given a priority relative to other definitions in the layer. If labels from different definitions conflict in their placement, the label from the highest-priority definition will be displayed.
  • Label overlap with other labels (allowOverlapOfLabel)—Whether other labels are allowed to overlap this label. One of the following values is expected: allow means that labels are allowed to overlap this label, avoid means that labels that would overlap will move as much possible to minimize the overlap, and exclude (the default) means that labels that would overlap are not placed.
  • Label overlap with features—Whether other labels are allowed to overlap a polygon edge (allowOverlapOfFeatureBoundary) or feature (allowOverlapOfFeatureInterior). One of the following values is expected: allow means that labels are allowed to overlap, avoid means that labels that would overlap will move as much possible to minimize the overlap, and exclude means that labels that would overlap a feature are not placed. The default value is allow for lines and polygons and exclude for points.
  • Which features to label (where)—The features labeled with the label definition are determined by evaluating an attribute expression. If this expression is not defined, all features are included in the definition. When using multiple label definitions, it's important that expressions uniquely assign features for each definition.

Creating multiple label definitions for a single layer is useful when you want to distinguish labels for certain types of features. When labeling a cities layer, for example, you may want to display capital cities with a larger font or different color.

Use text formatting tags with labels

Text used for labels can contain some of the same formatting tags used by ArcGIS Pro. These tags are similar to html tags and are used to modify the appearance of the text. For the current release, ArcGIS Runtime supports the following tags:

  • <FNT>—Font name, size, and scaling.
  • <CLR>—Color (defined with RGB or CMYK values).
  • <BOL>, <_BOL>—Bold / un-bold.
  • <ITA>, <_ITA>—Italic / un-italic.
  • <UND>, <_UND>—Underline / un-underline.

See the Text formatting tags topic in the ArcGIS Pro documentation for more information about these formatting tags and how they can be used with your labels.

Define labels for a map image layer

Labels for map image sublayers (ArcGISMapImageLayer) can be defined in much the same way as labels for feature layers and graphics overlays. The main difference is that labels for map image layers are rendered by the server and not in your client app. You must therefore use ArcGIS Server REST API syntax to define your label expressions, rather than the Arcade syntax you can use with feature layers and graphics overlays. Labels for a map image sublayer are supported for layers displayed in 2D (maps) and in 3D (scenes).

The JSON below creates a label definition that uses labelExpression with ArcGIS Server REST syntax. This differs from the preceding example for graphics and features that used labelExpressionInfo.expression and Arcade syntax.

  "labelExpression": "[areaname]",
  "labelPlacement": "esriServerPointLabelPlacementAboveCenter",
  "symbol": {
    "color": [255,0,255,123],
    "font": {"size": 16},
    "type": "esriTS"