Arcade

When to use: Activate this skill whenever the user writes an Arcade expression for popups, labels, or renderers, or computes values from attributes/geometry.

Overview

Arcade is Esri's expression language; the SDK compiles a script into an executor scoped to a profile.

• Problem it solves: dynamic, data-driven text and values without round-trips.
• Who it serves: developers customizing popups, labels, and symbology.
• Pattern it teaches: pick the profile for the context; compile once with createArcadeExecutor.
• What it does NOT cover: renderers themselves (see arcgis-visualization) or popups (arcgis-popup-templates).

Quick Start

import { createArcadeExecutor } from "@arcgis/core/arcade.js";
const executor = await createArcadeExecutor("$feature.POP * 2", {
  variables: [{ name: "$feature", type: "feature" }],
});
const value = executor.execute({ $feature: graphic }); // the graphic must carry POP

Decision Tree

1. Where does the expression run?
   • Popup → use a popup profile (often via PopupTemplate expressionInfos).
   • Label → label profile.
   • Renderer / visual variable → renderer profile (valueExpression).
2. Compiling manually?
   • Yes → createArcadeExecutor(script, createArcadeProfile("popup")). The profile names are "popup", "labeling", "visualization" (renderers), "field-calculation", "form-calculation", "form-constraint", "aggregate-field", among others; the helper declares every variable the context has ($feature, $layer, $map, $view, …).

Default: declare the expression on the consuming object (popup/label/renderer) and let the SDK compile it.

Import Patterns

Direct ESM (recommended for npm/Vite/Webpack)

import { createArcadeExecutor } from "@arcgis/core/arcade.js";

Dynamic Imports (CDN)

const arcade = await $arcgis.import("@arcgis/core/arcade.js");

Map Components (recommended for new projects)

// Expressions live in popupTemplate/labelingInfo/renderer on layers in the component map.
import "@arcgis/map-components/components/arcgis-map";

Key Concepts

Concept 1: Profiles

A profile declares the variables available to the script (e.g. $feature, $layer, $map). Use the profile that matches the context so the right globals exist.

Concept 2: createArcadeExecutor

createArcadeExecutor(script, profile, options?) returns an ArcadeExecutor you call with the runtime context (the feature). Compile once, execute many times.

What the executor tells you, and what goes wrong if you ignore it (measured with SDK 5.1.27):

• isAsync: true when the script uses a FeatureSet function. Then only executeAsync() works; execute() throws "Cannot execute the script in synchronous mode". For many features, executeAsyncBatch().
• fieldsUsed: request these fields (layer.outFields = executor.fieldsUsed, or the query's outFields). A field that was not requested arrives as null, and null / 1000 gives 0: a plausible wrong number, no error.
• geometryUsed: request geometry (returnGeometry: true). Without it, Area($feature) returns 0, no error.
• options.cache (5.0) replaces the deprecated lruCache; options.timeZone should be the view's time zone when dates are shown.

Field names are case-insensitive: $feature.pop reads a field named POP.

Concept 2b: Area and length are planar unless you say otherwise

Area() and Length() measure in the geometry's own projection. In Web Mercator that is wrong away from the equator: a 0.01° cell at 50° S measures 1.928 km² with Area and 0.798 km² with AreaGeodetic (factor 2.42). Use AreaGeodetic() / LengthGeodetic() for real-world sizes.

Concept 3: Where expressions live

Most of the time you don't call the executor yourself — you set expressionInfos on a popup, valueExpression on a renderer, or an Arcade label expression, and the SDK runs it.

Common Pitfalls (Top 3)

Pitfall 1: Wrong profile for the context

// ❌ Anti-pattern
createArcadeExecutor(script, { variables: [] }); // $feature not declared

// ✅ Correct
createArcadeExecutor(script, { variables: [{ name: "$feature", type: "feature" }] });

Impact: the script errors because $feature is undefined.

Pitfall 2: Compiling on every render

// ❌ Anti-pattern
features.forEach(async (f) => { const e = await createArcadeExecutor(script, profile); });

// ✅ Correct
const executor = await createArcadeExecutor(script, profile); // once, reuse per feature

Impact: recompiling per feature is slow.

Pitfall 3: A field or the geometry was never requested

// ❌ Anti-pattern
const e = await createArcadeExecutor("$feature.pop2000 / 1000", profile);
const { features } = await layer.queryFeatures({ where: "1=1", outFields: ["objectid"] });
e.execute({ $feature: features[0] }); // 0, silently

// ✅ Correct
const { features } = await layer.queryFeatures({
  where: "1=1",
  outFields: e.fieldsUsed,
  returnGeometry: e.geometryUsed,
});
e.execute({ $feature: features[0] }); // 1211.537

Impact: measured on the USA sample service: the missing field arrives as null and the expression returns 0, a believable wrong value with no error. Area() without geometry also returns 0.

When to Read references/

Related Skills

• arcgis-popup-templates — expressionInfos in popups
• arcgis-visualization — valueExpression in renderers
• arcgis-layers — the data the expressions read

Reference Samples

• Arcade in popups
• Arcade renderer

Changelog

• 0.2.0 (2026-10-27): SDK 5.1. Removed the false "field name case" pitfall (Arcade field names are case-insensitive, measured); missing fields or geometry return 0 silently; isAsync / executeAsync; createArcadeProfile; cache replaces lruCache (5.0); planar vs geodetic area. Every claim run in tests/runtime/casos/arcgis-arcade.ts.
• 0.1.0 (2026-05-31): Initial release.