ArcGIS Coding Components

Use this skill when embedding an Arcade expression editor into a web application. The @arcgis/coding-components package provides the arcgis-arcade-editor web component - a full-featured code editor for writing, testing, and debugging Arcade expressions. This is a new component package in 5.0 with no 4.x equivalent.

Import Patterns

CDN (No Build Tools)

<!-- Load ArcGIS Maps SDK -->
<script src="https://js.arcgis.com/5.0/"></script>
<!-- Load Coding Components -->
<script type="module" src="https://js.arcgis.com/5.0/coding-components/"></script>

Direct ESM Imports (Build Tools)

import "@arcgis/coding-components/components/arcgis-arcade-editor";

arcgis-arcade-editor Component

A rich code editor for Arcade expressions with syntax highlighting, diagnostics, code suggestions, and a documentation side panel.

Properties

Property	Attribute	Type	Default	Description
script	script	string	""	The Arcade script content (read/write)
profile	-	IEditorProfileDefinition	-	Profile metadata defining the editing context (set via JS)
testData	-	IEditorTestContext	-	Test data context for expression validation (set via JS)
snippets	-	ApiSnippet[]	-	Collection of code snippets to show in the snippets panel (set via JS)
suggestions	-	IEditorCodeSuggestion[]	-	Code suggestions shown to the user (set via JS)
editorOptions	-	IEditorOptions & IGlobalEditorOptions	-	Monaco-style editor options (set via JS)
hideSideBar	hide-side-bar	boolean	false	Hide the side action bar for a minimal UI
hideDocumentationActions	-	boolean	false	Hide the documentation action in the side panel
openedSidePanel	opened-side-panel	string	"none"	Name of the currently opened side panel
sideActionBarExpanded	side-action-bar-expanded	boolean	false	Whether the side action bar is expanded

Methods

Method	Returns	Description
setFocus()	void	Set focus on the editor
componentOnReady()	Promise<void>	Resolves when the component is fully loaded

Events

Event	Detail	Description
arcgisScriptChange	string	Fired when the script content changes (debounced)
arcgisDiagnosticsChange	Diagnostic[]	Fired when diagnostics (errors/warnings) change

Basic Usage

Minimal Editor

<arcgis-arcade-editor
  script="return $feature.Population * 2;"
  style="width: 600px; height: 400px;">
</arcgis-arcade-editor>

Listening for Script Changes

<arcgis-arcade-editor id="editor" style="width: 600px; height: 400px;">
</arcgis-arcade-editor>

<script type="module">
  const editor = document.querySelector("#editor");
  editor.script = "return $feature.Name;";

  editor.addEventListener("arcgisScriptChange", (event) => {
    const newScript = event.detail;
    console.log("Script updated:", newScript);
  });

  editor.addEventListener("arcgisDiagnosticsChange", (event) => {
    const diagnostics = event.detail;
    const errors = diagnostics.filter(d => d.severity === "error");
    if (errors.length > 0) {
      console.warn("Script has errors:", errors);
    }
  });
</script>

Editor with Profile Context

const editor = document.querySelector("arcgis-arcade-editor");

// Define the editing profile - tells the editor what variables are available
editor.profile = {
  id: "popup",
  title: "Popup Expression",
  description: "Expression for popup content",
  variables: [
    {
      name: "$feature",
      type: "Feature",
      description: "The current feature"
    },
    {
      name: "$layer",
      type: "FeatureSet",
      description: "The feature's parent layer"
    }
  ]
};

Editor with Test Data

const editor = document.querySelector("arcgis-arcade-editor");

// Provide test data for expression validation
editor.testData = {
  spatialReference: { wkid: 4326 },
  features: [
    {
      attributes: {
        Name: "Test Feature",
        Population: 50000,
        Area: 125.5
      },
      geometry: {
        type: "point",
        x: -118.24,
        y: 34.05
      }
    }
  ],
  fields: [
    { name: "Name", type: "esriFieldTypeString", alias: "Name" },
    { name: "Population", type: "esriFieldTypeInteger", alias: "Population" },
    { name: "Area", type: "esriFieldTypeDouble", alias: "Area" }
  ]
};

Editor with Custom Snippets

const editor = document.querySelector("arcgis-arcade-editor");

editor.snippets = [
  {
    name: "Format Currency",
    description: "Format a number as US currency",
    code: 'Text($feature.Value, "$#,###.00")'
  },
  {
    name: "Concatenate Fields",
    description: "Join two text fields with a separator",
    code: 'Concatenate([$feature.FirstName, $feature.LastName], " ")'
  }
];

Minimal Editor (No Side Bar)

<arcgis-arcade-editor
  hide-side-bar
  script="return Round($feature.Value, 2);"
  style="width: 400px; height: 200px;">
</arcgis-arcade-editor>

Full Example with Map Integration

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>Arcade Editor</title>
  <script src="https://js.arcgis.com/5.0/"></script>
  <script type="module" src="https://js.arcgis.com/5.0/coding-components/"></script>
  <script type="module" src="https://js.arcgis.com/5.0/map-components/"></script>
  <style>
    html, body { height: 100%; margin: 0; display: flex; flex-direction: column; }
    arcgis-map { flex: 1; }
    #editor-panel { height: 300px; border-top: 1px solid #ccc; }
  </style>
</head>
<body>
  <arcgis-map id="map" item-id="YOUR_WEBMAP_ID">
    <arcgis-zoom slot="top-left"></arcgis-zoom>
  </arcgis-map>
  <div id="editor-panel">
    <arcgis-arcade-editor id="editor"></arcgis-arcade-editor>
  </div>

  <script type="module">
    const mapElement = document.querySelector("#map");
    const editor = document.querySelector("#editor");

    await mapElement.viewOnReady();
    const view = mapElement.view;
    const layer = view.map.layers.getItemAt(0);
    await layer.load();

    // Set initial script
    editor.script = 'return $feature.Name + " (" + $feature.Type + ")"';

    // Configure profile from layer fields
    editor.profile = {
      id: "popup",
      title: "Popup Expression",
      variables: [
        { name: "$feature", type: "Feature", description: "Current feature" }
      ]
    };

    // Listen for changes and apply to popup
    editor.addEventListener("arcgisScriptChange", (event) => {
      console.log("Expression:", event.detail);
    });
  </script>
</body>
</html>

Common Pitfalls

1. Missing coding-components script: The arcgis-arcade-editor element must be loaded separately from the core SDK.

   <!-- Anti-pattern: only loading core SDK -->
   <script src="https://js.arcgis.com/5.0/"></script>
   <arcgis-arcade-editor></arcgis-arcade-editor>
   

   <!-- Correct: load coding-components too -->
   <script src="https://js.arcgis.com/5.0/"></script>
   <script type="module" src="https://js.arcgis.com/5.0/coding-components/"></script>
   <arcgis-arcade-editor></arcgis-arcade-editor>
   

   Impact: The element is unrecognized and renders as empty.

2. No size on the editor: The editor needs explicit width and height to render.

   <!-- Anti-pattern: no size -->
   <arcgis-arcade-editor></arcgis-arcade-editor>
   

   <!-- Correct: explicit size -->
   <arcgis-arcade-editor style="width: 600px; height: 400px;"></arcgis-arcade-editor>
   

   Impact: The editor renders with zero height and is invisible.

3. Setting profile or testData as HTML attributes: These properties accept complex objects and must be set via JavaScript.

   Impact: Values are silently ignored; the editor lacks context for autocompletion and validation.

4. Not debouncing arcgisScriptChange: The event fires on every keystroke (debounced internally but can still be frequent). Avoid expensive operations in the handler.

   // Anti-pattern: expensive operation on every change
   editor.addEventListener("arcgisScriptChange", async (event) => {
     await compileAndExecuteArcade(event.detail); // too frequent
   });
   

   // Correct: add your own debounce for expensive operations
   let timeout;
   editor.addEventListener("arcgisScriptChange", (event) => {
     clearTimeout(timeout);
     timeout = setTimeout(() => {
       compileAndExecuteArcade(event.detail);
     }, 500);
   });
   

   Impact: UI freezes or excessive server requests during typing.

Reference Samples

• Search for Arcade-related samples that demonstrate expression editing workflows.

Related Skills

• See arcgis-arcade for Arcade expression language syntax and usage patterns.
• See arcgis-widgets-ui for layout components to host the editor panel.
• See arcgis-popup-templates for using Arcade expressions in popup content.
• See arcgis-visualization for Arcade-driven visual variables and renderers.