Pop-ups: Arcade essentials

This blog article was originally published on October 18, 2022, and has been updated. The last previous update was December 9, 2022.

Layer pop-ups are an important part of crafting the complete map information experience. Pop-ups can transform an otherwise dull list of attributes into a far more meaningful display of intuitive and engaging information for your audience. Arcade can be thought of as a collection of useful tools that can be applied to craft the very best pop-ups, leveraging functions and logic to perform calculations and geometric operations, format text, access data from other layers, and much more.

What is Arcade?

Arcade is an expression language that is supported across ArcGIS. It can be used to perform calculations, manipulate text, and evaluate logical statements. Arcade exists within a profile, or context, that defines the parameters that are available to the script as global inputs and the output expected from the script. This blog article focuses only on the Popups profile and offers an overview of how it is used to craft layer pop-ups.

Arcade in pop-ups can be used in two ways; to create attribute expressions used in text elements that can be evaluated like fields, or as separate Arcade content elements that return a complete block of content. Using Arcade expressions and elements, you can take your pop-ups to the next level. Pop-ups: the essentials provides an overview of pop-ups and how they can be configured.

Why use Arcade?

Arcade enables you to work with data dynamically to perform calculations and manipulate data on-the-fly. If you have improperly formatted attributes, need to do a conversion, need to perform mathematical operations (e.g., sum values or calculate percentages), use logical expressions for branching, or perform geometric operations (e.g., calculate areas or intersections).

Arcade provides a straightforward, Excel-like way, to manipulate data without having to go back to the source. This is especially useful if you don’t own the source—Arcade can be applied to any feature layer in a map.

Quick links

Use these links to jump to a section of interest. Open the Arcade examples map to follow along.

• About the Arcade examples map
• Arcade attribute expressions
• Arcade content blocks
• Arcade editor
• Create attribute expressions
• Create Arcade content blocks
• Commonly used Arcade

More information

About the Arcade examples map

Open the Arcade examples map to follow along and see examples of Arcade use in pop-ups. The map has background layers plus two group layers: Final Pop-ups and Example Pop-ups.

Final pop-ups have fully configured pop-ups using Arcade. Click any feature to view the configured pop-up.

To learn more about how the pop-up was configured, select a layer and open the Pop-ups pane from the Settings (light) toolbar, then expand an element.

Arcade attribute expressions

To view the expressions for the Peaks layer in the Final Pop-ups group, select Peaks then on the Settings (light) toolbar, click Pop-ups, then Attribute expressions.

All layer attribute expressions will be listed in the Attribute expressions pane. Click to open any existing attribute expression to view it in the Arcade editor, or click Add expression to begin a new one.

In pop-ups, Arcade expressions are used in title or text elements. Open any text element in the Peaks layer to view the expressions and how they are used.

Expressions appear in curly braces – {expression/expr0} – and are numbered starting at zero. Expressions, like any text, can be selected and styled.

Tip: A great way to learn more about how to author and use Arcade expressions is to open any Living Atlas map or layer, then examine the pop-ups and expressions.

Arcade content blocks

Pop-up content blocks, or elements, are the building blocks of pop-up information. Pop-ups can be composed of field lists, text, charts, images, or Arcade.

Select the Peaks layer and click Pop-ups, then view the list of content blocks. Arcade elements are listed using the code symbol – </> – and titled Arcade.

To add a new Arcade content block, click Add content and choose Arcade.

Arcade Editor

The Arcade editor is used to create new attribute expressions and Arcade content blocks, or edit existing ones. It includes the following:

a – Name

b – Expression

c – Run (test) button

d – Action bar with options to display profile variables, functions, suggestions, and help

e – Action pane, with more information about the selected action.

Profile variables are special global variables that can be used in expressions. For example, $feature references the feature you click on your map to open the pop-up. This variable is used to retrieve specific attributes (fields) for the feature. For example, $feature.name returns the content of the field “name” for the feature.

Functions are used to calculate values in expressions. Functions are grouped and categorized into constants, data functions, feature functions, math functions, text functions, and so on. For example, Round is a math function that rounds the input numerical value to the specified number of places, and returns the new rounded number. Each function has built-in help so you can learn how to use them. You can also create your own custom functions for use in expressions.

Suggestions provide a list of existing expressions so that you can copy some or all of an expression into a new one.

Help links to the Arcade help documentation.

The Arcade editor also includes Intellisense, helping to reduce errors and helping to complete the expression as you write it. Warnings also appear in the editor, helping you understand when there’s something in your expression that could be a problem or could be improved.

Create attribute expressions

In this section you will create two very simple expressions: one that converts all upper case text to proper case text and another that converts feet to meters. You can follow along by viewing the sample map and opening the Example Pop-ups layer group, then selecting and viewing the Peaks (Text element) layer.

Open the text element in the layer pop-up.  The element uses the {PEAKNAME} and {ELEV} fields to create the pop-up.

Follow these steps to create the first expression that converts the upper case name to proper case.

Step 1 — In the Arcade editor, begin by doing the following.

a – Change the default name to something more meaningful and easier to recognize.

b – Add a comment (using the double forward slashes //) to describe what the expression does.

c – Click Profile variables to open the Profile variables pane.

d – Click the arrow to the right of the $feature variable to show all available fields.

Step 2 — Scroll down the list of fields to find PEAKNAME, then click the field to begin the expression. Since we already know the field to use, we could simply have begun the expression by typing $feature.PEAKNAME.

Step 3 — Move on to the next line. Click the Functions tab to view the available functions. Scroll down to the Text functions category to search for applicable functions, or enter the function name to identify possibilities. Click to add the function to the expression.

Tip: Click the arrow (circled in green in the image above) to learn more about the function. Click More information to go to the complete function help documentation.

Step 4 — The function takes a text value as the input and returns proper case text. Edit the expression so that $feature.PEAKNAME is the function value input.

The optional parameter ‘everyword’ isn’t needed, since that is the default. But it makes the Arcade more understandable. The other parameter would be firstword to only capitalize the first word in the string.

Step 5 — Click Run to ensure the expression returns the desired result. Click OK when finished to save the expression.

Step 6 — Use the expression in the text element just like any other field. Enter the curly brace { in the text element to display a list of fields and expressions. The expressions are found at the top of the list.

The text elements now returns the proper case peak name.

Step 7 — Use similar steps described above to create another expression that converts the elevation in feet to meters.

This expression can be used in the text element as shown below.

Add formatting to the expression

To add text formatting to the expression, return the height in meters as a string using the Text function and add the desired formatting using the hash notation to the returned text.

Format expressions like fields

Since expressions are treated exactly like fields, we can format numeric expressions by selecting them in the Fields pane (expressions are found at the bottom of the fields list) and adjusting the formatting like any other field. FeetToMeters returns a string, but if it returned a numeric value we could format it as shown below.

Additional text typography, such as text size, bold or italic text, and color can be applied to expressions, text, and fields to achieve the desired results.

Create Arcade content blocks

You can follow along by viewing the sample map and opening the Example Pop-ups layer group, then selecting and viewing the Peaks (Arcade element) layer. In this example the Arcade content element is similar to the pop-up created with attribute expressions above, with some additional HTML styling. Compare Peaks (Expressions) and Peaks (Content Element) to understand the two approaches.

One of the biggest differences between Arcade attribute expressions and Arcade content elements is that attribute expressions are used in text elements, and Arcade content elements are intended to return a complete part of your pop-up, either independently or combined with other elements. While the Arcade behind both expressions and elements is very similar, Arcade content elements are self-contained, so anything you need must be done within the element.

When you open the Arcade editor, there are several templates that help you get started. By default, the Rich text template is opened.

a – Change the default name to something more meaningful and easier to recognize.

b – Edit and add comments to describe what the expression does and also use comments to document the steps along the way. The better you document your Arcade, the more understandable and maintainable it will be.

c – Use the Profile variables and Functions tabs to construct the Arcade expressions. This is the same as is done when creating attribute expressions.

d – Use Arcade functions to assign variables that will be used in the returned text. The goal of all functions, profile variables, and variables in the context of explicitly returned text is to create the building blocks to be used to construct the final returned text.

e – The explicit Return is the block of rich text that the Arcade content element displays in the pop-up. In the case of rich text, this provides full HTML styling to craft the returned content.

The final result is the pop-up shown below.

This is a simple example using Arcade content, with lots more potential to go beyond the basics. See the Peaks layer in the Final Pop-ups group for more examples of using Arcade.

Commonly used Arcade

The following are examples of common uses of Arcade in pop-ups. Many of these are used to configure pop-ups in the Arcade samples map used in this blog article. Other examples can be found in ArcGIS Living Atlas maps and layers or the Arcade Function Reference.

Proper case text

This expression will return proper case text. The Proper function has two options – capitalize all words or capitalize the first word only. If COUNTY contains the string “SAN DIEGO COUNTY” the expression returns “San Diego County.”

var txtProper = Proper($feature.COUNTY, 'everyword')
return txtProper

There are many other text functions for working with text. For more information, see Text Functions.

Convert codes or abbreviations to a readable string

Converts an abbreviation or code number to an understandable string. For example, if the field value is “CAC” the expression will return “Cades Cove.”

var distNam = $feature.PARKDIST

When (
    distNam == "CAC", "Cades Cove",
    distNam == "CAT", "Cataloochie",
    distNam == "COS", "Cosby",
    distNam == "DCR", "Deep Creek",
    distNam == "LRI", "Little River",
    distNam == "OCO", "Oconaluftee",
    "Unknown")

Units conversion

This expression will convert feet to meters using a simple conversion factor. The units in feet are in the field ELEV.

Text($feature.ELEV * 0.3048, "#,###")

Remove blanks or empty values

This expression checks the contents of AFIELD and will return “Unknown” if it is null, the field has spaces, or the feature is empty. Otherwise, it returns the field contents.

var valField = $feature.AFIELD
var boolEmpty = IsEmpty($feature.AFIELD)

When(
    valField == NULL, "Unknown",
    valField == " ", "Unknown",
    boolEmpty == true, "Unknown", 
valField)

Another approach is to use DefaultValue to compare against null.

DefaultValue($feature.AFIELD, 'Unknown')

To also catch spaces, add Trim.

DefaultValue(Trim($feature.AFIELD), 'Unknown')

Create a link by combining an attribute value and a root URL string

You can combine feature attribute values with a string to create a URL link to open another web site or to retrieve more information. For example, a parcel map may have a unique parcel ID which can be linked to the assessor records by creating the unique URL that points to the information,

// Return link to unique property record
var txtLink = "https://app1.pinal.gov/Search/Parcel-Details.aspx?Parcel_ID="+$feature.ParcelID
return txtLink

Get attributes from another layer in the current map

Using expressions, you can combine attribute information from other layers in the same map into a single pop-up. Use FeatureSetByName to find the layer using its name.

// Get layer named "Counties" in the map
var fsetCounties = FeatureSetByName($map,"Counties")

Other functions can be applied to the feature set to retrieve the desired information, such as Count or geometry functions such as Intersect.

var numCounties = Count(fsetCounties)
var feaCounty = (First(Intersects(fsetCounty, $feature)))

Get attributes from a layer not in your map

In this case a feature set is returned from another layer that is not in the current map, referenced by its ID. This can be used to retrieve attributes from Living Atlas layers such as current weather, demographic information, air quality, and more.

var fsetStates = FeatureSetByPortalItem(Portal('https://www.arcgis.com/'), 
"774019f31f8549c39b5c72f149bbe74e", 0)

Apply color to text

In text blocks you can add color to expressions in the same way as coloring text or attribute values (select the expression, then use the color picker). In this example two expressions were constructed to evaluate the {STATUS} field which contains one of two attribute values; Active or Inactive. While the logic here may initially seem confusing, we are creating two expressions which return the string value Active or Inactive. If the expression does not evaluate to True, Null is returned and it will not appear in the text block.

The first expression, titled IsActive, evaluates whether the field for the feature contains the word Active.

The second expression, titled IsInactive, evaluates whether the field for the feature contains the word Inactive.

Color is applied to the expression, which is treated like a field, in the text editor. The results are shown below.

Arcade content blocks

For more information, see the following:

• Pop-ups: the essentials (Blog)
• Arcade Getting Started (Documentation)
• Arcade Function Index (Documentation)
• Introducing the new Arcade editor in ArcGIS Online (Blog)
• Try ArcGIS Arcade (Learn ArcGIS)
• Your Arcade questions answered (Blog)
• What is Arcade and why use it? (Story)
• ArcGIS Online: Web mapping with expressions (Video)
• Enhance your pop-ups using Arcade + Living Atlas (Blog)
• Part 1: Introducing Arcade pop-up content elements (Blog)
• Part 2: Introducing Arcade pop-up content elements (Blog)
• Use Arcade geometry functions to provide spatial context (Blog)