arcgis-arcade-editor | References | ArcGIS Maps SDK for JavaScript

ESM

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

Inheritance: ArcgisArcadeEditor→HTMLElement

Arcade is a portable, and lightweight expression language used to create custom content throughout the ArcGIS system. Like other expression languages, it can perform mathematical calculations, format text, and evaluate logical statements. It also supports multi-statement expressions, variables, and flow control statements. Arcade is unique when compared to other expression and scripting languages due to its inclusion of feature and geometry data types.

Map Viewer (MV) was the first ArcGIS Online product to incorporate the new Arcade editor after the editor's introduction in the November 2022 ArcGIS Online release. This was possible thanks to the Arcade editor component, which enabled MV to implement its own Arcade expression builder. You can now also find the editor in ArcGIS Dashboards, ArcGIS Field Maps, and ArcGIS Velocity.

You can easily get your own dedicated Arcade expression builder with the Arcade editor component, which includes:

An easy to use layout
An optional minimal layout if you, for example, decide to manually exclude things such as test data, padding, line numbers, and the sidebar
A way to execute Arcade expressions in a configurable code editor
Suggestions and code completion
WCAG 2.0 compliant code colorization / syntax highlighting
Built-in keyboard shortcuts
In-editor help for finding information about profile variables relevant to your profile, documentation for constants and functions, a link to the official Arcade documentation, and, in some case, suggestions
Support for many languages and directionality
A debugger with support for breakpoints, stepping, and an interactive console
An AI Assistant that uses natural language processing to generate Arcade expressions from scratch or find and fix errors in your code

The Arcade editor and some of the underlying core Arcade language functions depend on esriConfig properties. To ensure the best experience for your users, make sure to set the following:

esriConfig.applicationName
- Used by the GetEnvironment() Arcade function
- Associates feedback to the Arcade assistant with a specific application
esriConfig.portalUrl
- Required for the Arcade assistant to function, as the assistant relies on ArcGIS Online services

Demo

Properties

Property	Attribute	Type
disableAssistant	disable-assistant	boolean
editorOptions		(Editor.IEditorOptions & Editor.IGlobalEditorOptions) \| undefined
enableDebugger	enable-debugger	boolean
hideDocumentationActions	hide-documentation-actions	boolean
hideSideBar	hide-side-bar	boolean
messageOverrides		Record<string, unknown> \| undefined
openedSidePanel reflected	opened-side-panel	string
profile		EditorProfileDefinition \| IEditorProfileDefinition \| IPredefinedProfile \| PredefinedProfile \| undefined
script	script	string
sideActionBarExpanded reflected	side-action-bar-expanded	boolean
snippets		ApiSnippet[] \| undefined
suggestions		EditorCodeSuggestion[] \| EditorCodeSuggestionGroup[] \| IEditorCodeSuggestion[] \| IEditorCodeSuggestionGroup[] \| undefined
testData		EditorTestContext \| IEditorTestContext \| undefined

disableAssistant

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.1

When set to true, hides the Arcade assistant (beta) panel and disables all related features. The Arcade assistant (beta) panel includes a question/answer UX that allows users to ask the assistant to generate Arcade expressions from natural language prompts, or to find and fix errors in their code.

The Arcade assistant (beta) will only be available if the following conditions are met:

The disableAssistant property is false
The esriConfig.portalUrl is set to an ArcGIS Online portal (either the default or a custom one)
The user is signed in to the portal. The application exposing the editor must handle user authentication.
The signed in user has permissions to use AI features in ArcGIS Online, including the following conditions:
- The user's organization allows use of AI assistants,
- The user's role has the "Use AI assistants" privilege enabled, and
- Beta features are enabled for the user's organization

The assistant also provides the ability for users to submit feedback on generated responses, which may be used to improve the assistant's performance over time. When feedback is logged, it is associated with the application exposing the Arcade editor. It is best practice to set esriConfig.applicationName so the feedback can be associated with a specific application.

More information about the Arcade assistant, including best practices, the context provided to the underlying model, limitations, and transparency cards can be found in the links below.

See also

Attribute: disable-assistant
Default value: false

editorOptions

Property

Type: (Editor.IEditorOptions & Editor.IGlobalEditorOptions) | undefined

Options to update on the editor. For example:

{
  "fontSize": 18
}

To get the full list of available options, see the Monaco Editor options documentation for more details.

enableDebugger

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.1

If true, the editor will enable a debug drawer at the bottom of the editor. This drawer includes debugging features such as the ability to set breakpoints, step through code, and view variable values during execution.

Attribute: enable-debugger
Default value: false

hideDocumentationActions

Property

Type: boolean

If true, it will hide the documentation action in the side panel

Attribute: hide-documentation-actions
Default value: false

hideSideBar

Property

Type: boolean

If true, it will hide the side actions bar. The editor will be in a minimalistic UX.

Attribute: hide-side-bar
Default value: false

messageOverrides

Property

Type: Record<string, unknown> | undefined

Replace localized message strings with your own strings.

Note: Individual message keys may change between releases.

openedSidePanel

reflected Property

Type: string

The name of the opened side panel. 'none' means 'no panel opened'.

Attribute: opened-side-panel
Default value: "none"

profile

Property

Type: EditorProfileDefinition | IEditorProfileDefinition | IPredefinedProfile | PredefinedProfile | undefined

The profile contains metadata used by the editor for editing context and help. Example:

 {
   bundles: ["core", "dataAccess", "geometry", "portal-access"],
   variables: [
     {
       name: "$feature",
       description: "The feature passed to the script during execution.",
       definition: aFeatureLayerInstance
     }
   ]
 }

script

Property

Type: string

The arcade script. Use this property to define or update the script.

Attribute: script
Default value: ""

sideActionBarExpanded

reflected Property

Type: boolean

If true, the side action bar will be expanded

Attribute: side-action-bar-expanded
Default value: false

snippets

Property

Type: ApiSnippet[] | undefined

Collection of snippets

suggestions

Property

Type: EditorCodeSuggestion[] | EditorCodeSuggestionGroup[] | IEditorCodeSuggestion[] | IEditorCodeSuggestionGroup[] | undefined

Collection of suggestions

testData

Property

Type: EditorTestContext | IEditorTestContext | undefined

Test data used to execute the script in the editor. If undefined the execute script UX will be hidden.

Methods

Method	Signature
componentOnReady inherited	componentOnReady(): Promise<this>
setFocus	setFocus(): Promise<void>

componentOnReady

inherited Method

Signature: componentOnReady (): Promise<this>

Inherited from: this

Creates a promise that resolves once the component is fully loaded.

Returns: Promise<this>

Example

const arcgisArcadeEditor = document.createElement("arcgis-arcade-editor");
document.body.append(arcgisArcadeEditor);
await arcgisArcadeEditor.componentOnReady();
console.log("arcgis-arcade-editor is ready to go!");

setFocus

Method

Signature: setFocus (): Promise<void>

Set the focus on the element.

Returns: Promise<void>

Events

Name	Type
arcgisDiagnosticsChange	CustomEvent<Diagnostic[]>
arcgisScriptChange	CustomEvent<string>

arcgisDiagnosticsChange

Event

arcgisDiagnosticsChange: CustomEvent<Diagnostic[]>

Emitted when the diagnostics collection has changed.

arcgisScriptChange

Event

arcgisScriptChange: CustomEvent<string>

Emitted when the script string has changed.