Set custom expressions for symbology

With the Arcade scripting language, you can write expressions using one or more fields in the data to modify or specify the appearance of feature symbology.

An expression can be a single line of code or multiple lines of code. Expressions can be created or imported and modified in the Expression Builder dialog box. If a feature's attributes change, refresh the symbology values by choosing Refresh values from the More drop-down menu in the Symbology pane.

Note:

Single symbol and chart symbology do not support the use of Arcade expressions.

Apply an expression to the symbology field of a feature layer

To apply an expression to the symbology field of a feature layer, do the following:

1. Choose a feature layer in the Contents pane, if necessary.
2. On the Feature Layer tab, in the Drawing group, click Symbology to open the Symbology pane, if it is not already open.
3. Select a primary symbology.
4. Next to the Field drop-down menu, click the Set an expression button .
5. In the Expression Builder dialog box, do the following:
   1. Optionally, add Title text for the custom expression.
   2. Under Fields, double-click the name of a field to add it to the expression. If the number of fields in the data is large, click the Advanced button to filter the list and find the field you need.
   3. Under Functions, view the library of mathematical, text, and date-based functions. Click the Helper Type button to filter the list of functions, and double-click a function to add it to the expression.
   4. If a field is selected, click the Insert Values drop-down menu to browse to and add specific values to the expression.
   5. Under Expression, write a custom expression using Arcade language syntax.

      Caution:

      If symbolizing a field in which the name contains special characters or starts with a number, Arcade uses the same format as joined field syntax, for example, $feature['33field'], $feature['acres²'], and $feature['st_area(SHAPE)'].

   6. Click Verify to validate the expression.

      Validation error messages provide guidance if the expression is invalid. You can also click Import to import or click Export to export expressions outside ArcGIS Pro.

6. Click OK to set the expression for the field.

   The symbology updates to reflect the changes.

If a custom expression is used for the symbology, the title of the expression is displayed in the Contents pane and in the Field drop-down menu. Expressions are saved as long as the layer's primary symbology remains the same.

Symbology expression basics

Defining symbology with an expression assumes that you are familiar with Arcade. Arcade provides consistent functionality across ArcGIS software. This includes ArcGIS Pro, ArcGIS API for JavaScript, and other related applications.

Symbology Arcade expressions use the Visualization profile. Each profile has a defined set of global (profile) variables. This contextualizes the expression's variables and returned values. Extrusion expressions also use the visualization profile. For more information, see Visualization.

Simple expressions contain a definition of the field value and a mathematical operation. For example, you can use the $feature global variable to reference a field in the feature layer's attribute table, such as the population for a region in 2020, and subtract the 2010 population total from it to determine the difference. The resulting value of the expression is returned and used in determining the feature's symbol.

$feature.2020POP - $feature.2010POP

More complex expressions may use variables and span multiple lines of code. For example, you can set a variable to represent the difference between the current time and a date represented in a field.

var days_from_today = DateDiff(Now(), date_field, “days”);

Visualization profile variables

The Expression Builder dialog box accessed from the Symbology pane exclusively uses Arcade to provide consistency between maps, projects, and other applications. Additional information is available in the Arcade documentation.

• The Arcade global variable $view.scale makes a reference to the current scale of the view (map, scene, or layout). If you set a variable to $view.scale as part of a symbology expression, the symbology can change depending on the current scale of the view. An introductory example is below.

  var mapscale = $view.scale;
  var weight = $feature.STROKEWGHT;
  var size;
  var normal = 1000000;
  
  size = normal/mapscale*weight
  return size

  In this expression, the mapscale variable is created to store the scale value. The expression multiplies the scale by the stroke weight, which is derived by a value in the STROKEWGHT field, and divides this product by a custom value normal. The result changes the stroke weight of the symbols as you zoom in and out of the view. This is useful as an alternative to symbol class scaling.

• The $view.timeProperties global variable allows time slider settings to be accessible when a time slider is enabled on the map. Expressions using the variable should accommodate for situations in which the time slider is not enabled. The sample output below, which starts with a HasKey statement, checks for the presence of the time slider in the $view. If it returns true, the else statement is read.

  if (HasKey($view, 'timeProperties') == false || $view.timeProperties.currentEnd == null)
    return -1
  else
    return (
      DateDiff($view.timeProperties.currentEnd, $view.timeProperties.currentStart, 'days') 
      -
      DateDiff($view.timeProperties.currentEnd, $feature.Date_time, 'days') 
    )

• The $feature global variable refers to a feature layer's field for the symbology.

  Tip:

  If the field name contains a character that cannot be accessed with dot notation, place the name inside brackets, for example, $feature.["joinKey.fieldName"].

Visualization profile examples

The profile examples below include how to achieve certain types of symbology using the available variables.

Create symbology classes

In most cases, you can manually set the layer to use graduated symbols or graduated colors symbology. However, if you are referencing information from another source that changes frequently (for example, the national average price of a commodity), you must refresh or reset the symbology settings each time. To avoid this, you can set an expression to make calculations and use the results with an existing classification method.

	var stationID = $feature.stationID; //ID number for gas station
var stationPrice = $feature.stationPrice; //Price at gas station
var avgPrice = '4.164' //National average price of gas

var priceDiffUL = Round(avgPrice - stationPrice, 2); //Calculate the difference

return priceDiffUL;

This example determines the result value from two fields, stationID and stationPrice.

Classify unique values

You can write a custom expression to build unique values symbology, especially if the values are well defined and the symbology is used across multiple projects. Most expressions written for unique values symbology assign variables to classes and apply if-else or when logical functions to define the symbol class labels. In the example below, the unique value returned depends on whether it is a member of the example array.

var example_array = [1, 2, 3, 4];
if (IndexOf(example_array, $feature.VALUE) > -1) {
return “Value is 1, 2, 3 or 4”;
} else {
return “Other value”;
}

In another example, values are grouped based on the Enhanced Fujita tornado scale. This example is similar to the scale-based symbology example above, but this expression does not use the $view.scale variable.

var WindSpeed = $feature.WINDSPEED
when (
WindSpeed > 261, “F5”,
WindSpeed > 207, “F4”,
WindSpeed > 158, “F3”,
WindSpeed > 113, “F2”,
WindSpeed > 73, “F1”, 
“F0”
)

Scale-based symbology

In the first example, the variable vs stores the current scale value. The wind variable stores the feature's wind speed value, which is used to determine the exact size of the symbol. This value is stored as windSize, which is then resized depending on the map scale.

var vs = $view.scale
var wind = $feature.WINDSPEED

var windSize = When(
    wind > 136, 24, //Category 5
    wind > 112, 23, //Category 4
    wind > 95, 22, //Category 3
    wind > 82, 21, //Category 2
    wind > 63, 20, //Category 1
    wind > 33, 18, //Tropical Storm
    16) //Tropical Depression

when(
    vs >=37000000, windSize,
    vs >=18500000, 1 + windSize,
    vs >=9300000, 2 + windSize,
    vs >=4700000, 4 + windSize,
    vs >=2000000, 6 + windSize, 8 + windSize)

The second example symbolizes the feature from the EXAMPLE field only when the current scale is greater than 1:30000.

Var scale = $view.scale
var feature = $feature.EXAMPLE
if(scale > 30000 && feature == 10){
return 'Feature equals 10'
}
return 'Feature is not equal to 10'

Custom expressions provide a flexible way to measure and dynamically adjust symbology scaling, especially if the symbols are not based on a template. For more information, see Scale-based symbol sizing.