arcgis-coding-components

name	arcgis-coding-components
description	Embed an Arcade expression editor in applications using the Coding Components package. Use for building Arcade authoring, testing, and debugging interfaces.

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.