ArcGIS Map

An interactive map surface that loads an ArcGIS WebMap by item id from ArcGIS Online or an Enterprise portal. It provides zoom, pan, popups, and a set of placeable on-map controls — and it is the source of cross-widget actions that drive the data widgets on a view.

At a glance

Type key	arcgis-map
Default size	8 × 14 (min 4 × 6)
Data source	A WebMap Portal item
Emits	map:extent-change, map:layer-click
Receives	map-command (from AI Chat), zoom / pan (from a List item click)
Source	src/widgets/widgets/arcgis-map/

Configuration

The widget's config schema (schema.ts):

Field	Type	Default	Purpose
webMapId	string	""	Portal item id of the WebMap. Empty shows the placeholder.
portalUrl	string?	—	Enterprise portal URL; defaults to ArcGIS Online.
auth	object?	—	OAuth for secured portals (appId, popup).
hideAttribution	boolean	true	Hide the attribution banner.
mouseWheelZoom	boolean	true	Enable mouse-wheel zoom.
popupEnabled	boolean	true	Show the feature popup on click.
controls	object	zoom top-left	Placement of zoom, home, layerList, bookmarks, popup (corner + inExpand) or null to hide. The popup placement docks the feature popup in that corner.
expands	corner[] (max 4)	[]	Corners that host expand containers.
basemapSwitcher	object	hidden	placement, defaultLabel, and up to 4 options (itemId, label).
layerToggle	object	hidden	placement and up to 8 options (layerId, label).
quickFilter	object	hidden	placement and up to 8 filters (layerId, label, clauses). Each filter is a multi-clause SQL expression (field, operator, value/field operand) joined by AND/OR, applied to its layer.
editor	object	hidden	placement plus capability toggles (allowCreate, allowUpdateGeometry, allowUpdateAttributes, allowDelete, allowAttachments, snapping, popupEditAction) and up to 20 per-layer overrides (layerId, enabled, addEnabled, updateEnabled, deleteEnabled, fields).
theme	"light" | "dark"	"dark"	Theme for the ArcGIS controls.

A freshly added map starts with an empty webMapId, so it prompts you to pick a WebMap before rendering.

Config panel

• Data — WebMap item picker, portal URL, and OAuth setup (app id + popup toggle) for secured portals. Once a WebMap is selected, a preview card shows its thumbnail, title, and summary with a link to open the item in a new tab (see Picking an ArcGIS data source).
• Appearance — drag nine controls (Zoom, Home, Layers, Bookmarks, Popup, Basemaps, Toggle, Filter, Editor) into map corners or expand containers, edit basemap/layer/filter options and editing capabilities, choose the theme, and toggle attribution, mouse-wheel zoom, and popups.

UI controls

Nine placeable controls can be dragged onto a map corner—or grouped inside a corner's expand—from Appearance → UI controls. Each has its own page with configuration, config-panel steps, and behavior:

Control	Config key	Summary
Zoom	controls.zoom	Native zoom in / out buttons (placed by default).
Home	controls.home	Return to the WebMap's initial extent.
Layer List	controls.layerList	Full layer panel with visibility and legends.
Bookmarks	controls.bookmarks	Navigate to the WebMap's saved bookmarks.
Popup	controls.popup	Dock the feature popup in a chosen corner.
Basemap Switcher	basemapSwitcher	Swap between curated basemaps (max 4 + default).
Layer Toggle	layerToggle	Pill control to reveal one curated layer at a time.
Quick Filter	quickFilter	Apply curated attribute filters (max 8, one at a time).
Editor	editor	Native create / update / delete editing experience.

Every control is placed with a ControlPlacement ({ corner, inExpand }) or hidden with null. The custom controls (Basemap Switcher, Layer Toggle, Quick Filter, Editor) track their placement under their own config object's placement field.

Cross-widget actions

The Map is the only widget that emits actions:

• map:extent-change — fired when the view settles after pan/zoom, carrying a MapExtentPayload (extent + center as JSON). Wire it to a Table, List, Indicator, or Details as a filter.
• map:layer-click — fired when a feature is clicked, carrying a LayerClickPayload (layer id, title, attributes). Wire it to a Details widget as show-feature.

It also receives the map-command effect from an AI Chat widget: when an assistant turn carries commands (e.g. zoom to a location or extent), they are applied to this view with view.goTo. Each command is applied once; navigating the view re-fires map:extent-change, so extent-wired filters update automatically. The 3D Scene receives the same effect.

The Map also receives zoom and pan effects from a List's list:item-click or a Table's table:row-select: clicking a list item or selecting a table row navigates this view to the feature (zoom frames it; pan recenters at the current scale). The same live-navigation re-fires map:extent-change for extent-wired filters.

It also registers its live MapView so a sibling Legend or Details widget can bind to its layers.

Notable behavior

• Live indicator. When the WebMap contains a stream layer, a subtly pulsing sensor icon (the same glyph the layer list uses to mark stream layers) appears next to the map card's title to flag that the map is showing live data. It watches the map's layers, so it appears or disappears as stream layers are added or removed (including when a different WebMap is loaded).
• Expand containers. Up to four corners can host an expand container (expands). Controls placed with inExpand: true render inside their corner's expand, grouping them behind a single toggle button; an expand with no controls is not rendered.
• Extent debouncing. Fast wheel/pinch zoom settles repeatedly; emits are coalesced with a 300 ms trailing debounce to avoid a burst of downstream filter queries.
• Connection-safe. The portal and auth are injected at render time from the active ArcGIS connection — any portal info carried in saved config is ignored, so a map never requests items from a portal you're no longer signed in to.
• Initial extent. The WebMap's own initial extent is used the first time the view settles.

For per-control behavior (layer toggle visibility, quick filter expressions, editor gating and field visibility, bookmarks, and more), see the individual UI control pages.