Agent Guide: arcgis-interaction

Quick-reference decisions, checklists, and tables for user interaction patterns.

Hit Test vs Query vs Popup Decision Matrix

When to use each:

• Popup -- Simplest. Just configure popupTemplate on the layer. No code for the interaction itself.
• Hit test -- Returns the graphic at a screen point. Use when you need the actual feature object for custom behavior (not just a popup).
• Server query -- Returns features matching SQL/spatial criteria from the service. Use for bulk operations or features not visible on screen.
• Client query -- layerView.queryFeatures() queries only loaded features. Faster but limited to what is in the view.

Click Event Selection Guide

Recommendation: Use immediate-click for hit testing and feature selection. It fires instantly without waiting for a potential double-click.

Click-to-Select Implementation Checklist

• Get a reference to the target FeatureLayer
• Get the LayerView: const layerView = await view.whenLayerView(featureLayer)
• Store a highlight handle variable: let highlightHandle = null
• Add click handler: view.on("immediate-click", async (event) => { ... })
• Inside handler, run hit test: const response = await view.hitTest(event, { include: [featureLayer] })
• Remove previous highlight: highlightHandle?.remove()
• If results found, highlight: highlightHandle = layerView.highlight(graphic)
• Optionally open popup or update side panel with feature attributes

Cleanup Pattern

Always clean up handles and event listeners to prevent memory leaks.

Handle-based cleanup (highlight, watch)

const handle = layerView.highlight(graphic);
// Later:
handle.remove();

Event listener cleanup

const handle = view.on("click", handler);
// Later:
handle.remove();

reactiveUtils cleanup

import * as reactiveUtils from "@arcgis/core/core/reactiveUtils.js";

const handle = reactiveUtils.watch(() => view.zoom, callback);
// Later:
handle.remove();

Destroy pattern (widgets)

widget.destroy();  // Removes from DOM and cleans up

Checklist for cleanup

• Store all view.on() return handles
• Store all reactiveUtils.watch() / when() / once() return handles
• Store all layerView.highlight() return handles
• Call .remove() on handles when the interaction is no longer needed
• Call .destroy() on widgets when removing them
• In frameworks (React/Angular): clean up in unmount/destroy lifecycle hooks

Event Types Quick Reference

Preventing Default Behavior

view.on("double-click", (event) => {
  event.stopPropagation();  // Prevents default zoom-in
});

Coordinate Conversion Quick Reference

Highlight Options

Set on view.highlightOptions at the MapView / SceneView level.

Sketch Component vs Widget vs Draw