4.4 Dynamic Labeling with Arcade Expressions

Introduction to Arcade in ArcGIS Pro

ArcGIS Arcade is a lightweight, secure, and portable expression language designed by Esri. Unlike Python or VBScript, Arcade is designed to execute securely in any ArcGIS environment—ArcGIS Pro, ArcGIS Online, ArcGIS Enterprise, and runtime apps—ensuring that your labeling logic works seamlessly when maps are published to the web. In the context of layer symbology and display, Arcade is predominantly used for crafting advanced label expressions and custom symbology rules.

The Arcade Syntax and Global Variables

Arcade syntax is similar to JavaScript. It is case-insensitive for function names but case-sensitive for variable and field names. Arcade relies heavily on Profile Variables (globals) that provide context to the expression.

For labeling, the most critical global variable is $feature. This represents the current feature being processed by the label engine. To access a specific attribute, you append the field name to the variable using dot notation.

// Accessing the 'CITY_NAME' field
$feature.CITY_NAME

If a field name contains spaces or special characters, you must use bracket notation:

// Accessing a field with a space
$feature['Total Population']

Other important global variables (often used in popup configurations or attribute rules rather than basic labeling) include:

• $datastore: Represents the entire database or service the feature belongs to.
• $map: Represents the current web map or map frame.

Formatting Strings and Numbers

Arcade excels at manipulating text and numbers for display.

Concatenation You can combine multiple fields and static text using the + operator or the Concatenate() function. To add a new line, use the TextFormatting.NewLine constant.

// Using the + operator
$feature.CITY_NAME + ", " + $feature.STATE_ABBR

// Using Concatenate for multiline labels
Concatenate([$feature.NAME, $feature.POPULATION], TextFormatting.NewLine)

Text Formatting Functions Arcade provides functions to alter string casing and format numbers:

• Upper($feature.NAME): Converts text to ALL CAPS.
• Lower($feature.NAME): Converts text to all lowercase.
• Proper($feature.NAME): Capitalizes the first letter of each word (Title Case).
• Text($feature.SALES, '$#,###.00'): Formats a numerical value as a currency string.

Conditional Logic

One of the most powerful aspects of Arcade is conditional logic, allowing labels to respond dynamically to the data.

The IIf Function IIf (Immediate If) evaluates a boolean condition. If true, it returns the second argument; if false, the third.

// If population is over 1M, return the name in caps. Otherwise, normal case.
IIf($feature.POPULATION > 1000000, Upper($feature.CITY_NAME), $feature.CITY_NAME)

The When Function When evaluates a series of conditions sequentially, returning the result of the first true condition. It is ideal for complex if/else scenarios.

When(
  $feature.TEMP > 90, "Hot",
  $feature.TEMP > 60, "Warm",
  $feature.TEMP > 32, "Cool",
  "Freezing" // Default fallback
)

The Decode Function Decode is used for matching specific discrete values, similar to a switch statement. It compares a field against a list of possible values and returns a corresponding result.

Decode($feature.ZONING_CODE,
  "R1", "Single-Family Residential",
  "C1", "Commercial",
  "I1", "Industrial",
  "Unknown Zoning" // Default fallback
)

Handling Null Values

Null values (empty attributes) can break label expressions or result in ugly text like "None" or blank spaces. Arcade provides the IsEmpty() function to gracefully handle nulls.

// If the alias field is empty, use the formal name. Otherwise, use the alias.
IIf(IsEmpty($feature.ALIAS), $feature.FORMAL_NAME, $feature.ALIAS)

Rich Text Formatting Tags

Arcade can inject ArcGIS Pro text formatting tags into the output string to apply styling (bold, italics, color, fonts) dynamically. These tags are enclosed in angle brackets.

// Makes the city name bold and red, places a new line, then prints the state.
"<FNT name='Arial' size='12'><CLR red='255'><BOL>" + $feature.CITY_NAME + "</BOL></CLR></FNT>" + TextFormatting.NewLine + $feature.STATE_NAME

Advanced Spatial Functions

While less common for basic labeling due to performance overhead, Arcade supports spatial functions directly in the expression. You can access the geometry of the feature using Geometry($feature). Functions like Area(), Length(), Buffer(), or Intersects() allow you to generate labels based on spatial relationships or calculated geometries on-the-fly. For example, you could dynamically label a polygon with its calculated area in acres, regardless of whether an 'Acres' field exists in the attribute table.

Arcade's portability, combined with its robust logical and formatting capabilities, makes it the standard for advanced labeling and symbology in the modern ArcGIS ecosystem.