reactiveUtils

Since

ArcGIS Maps SDK for JavaScript 4.23

• Overview
• Using reactiveUtils
• Truthy checks versus explicit value checks
• Async versus sync callbacks
• Working with collections
• Working with objects
• ResourceHandles and Promises
• Working with TypeScript

Overview

reactiveUtils provides a declarative way to watch SDK state and respond to changes.

To use it, provide:

• A reactive expression that returns the state you want to track.
• A callback that runs whenever that state changes.

The reactive expression is a function that automatically re-evaluates whenever any state it accesses changes. For example, if the expression reads the map component's stationary property, the callback runs whenever stationary changes between true and false.

Reactive expressions can track primitive values, arrays, collections, and objects. Depending on the function you use, reactiveUtils supports both continuous observation and one-time conditions.

Using reactiveUtils

reactiveUtils provides five functions for observing state: on(), once(), watch(), when() and whenOnce(). Each of these has different characteristics and use cases, as summarized in the table below:

The snippet below uses watch() to react when the Map component's stationary property changes. This pattern is useful when work should run after navigation settles, such as querying features for the current extent, refreshing summary statistics, or enabling UI actions.

The first argument in the watch() function is the reactive expression, in the form of a getValue function, that evaluates the stationary property. When a change is observed in the expression the new value is automatically passed to the callback:

// Watching for changes on the map component's stationary property
const viewElement = document.querySelector("arcgis-map");
const handle = reactiveUtils.watch(
  // getValue expression
  () => viewElement.stationary,
  // callback
  (stationary) => {
    console.log(stationary)
  });

// Remove the handle when it's no longer needed to stop watching for changes
handle.remove();

Other examples of getValue expressions include:

() => viewElement.ready                           // Wait until the view finishes updating
() => [viewElement.stationary, viewElement.zoom]  // Track changes to multiple properties at once
() => viewElement.popupElement?.open              // Detect when a popup is opened
() => layer.visible                               // Track changes in layer visibility

Basic usage rules:

• Shape expressions so callbacks receive defined values.
• Avoid truthy checks when falsy values like 0, "", or false are valid.
• Use explicit comparisons for specific values (e.g., === 0 or === false).
• Use optional chaining (?.) to safely access nested properties.
• Return derived values for collections to react to structural changes.

Truthy checks versus explicit value checks

The when() and whenOnce() functions execute when the getValue expression evaluates as truthy, instead of reacting to every value change.

Use truthy checks when you only care whether a value is present or available. Use explicit value checks when you need to verify a specific state or distinguish between different values.

The snippets below use the Popup component's open property in the getValue expression. The first snippet uses a truthy check to determine when the popup is open, which is useful when you want to run the callback whenever the popup becomes visible. The property is false by default, so the callback will run when the popup opens, but not on subsequent changes that keep it open. Once the popup is closed, the callback will run again when it opens.

const viewElement = document.querySelector("arcgis-map");

const handle = reactiveUtils.when(() => viewElement.popupElement.open, () => {
  console.log("Truthy check for popup open");
});

// Remove the handle when it's no longer needed to stop watching for changes
handle.remove();

Other truthy examples include:

() => viewElement.ready
() => layer.loaded
() => layer.visible

Use explicit value checks when your logic depends on a specific value, rather than simply whether a value is truthy.

This is useful when valid values may be falsy, such as 0, "", or false, and a truthy check would produce unintended results.

For example, to react only when the map is at a specific scale:

const handle = reactiveUtils.when(() => viewElement.scale === 5000, () => {
  console.log("The map is at scale 1:5000");
});

// Remove the handle when it's no longer needed to stop watching for changes
handle.remove();

Other examples include:

() => viewElement.updating === false
() => layer.visible === false

See the MDN documentation to learn more about truthy and falsy values.

Async versus sync callbacks

Understanding the difference between asynchronous and synchronous callbacks is essential when working with reactiveUtils. The timing of when your callback executes, either immediately or on the next microtask, can impact both application behavior and performance.

By default, watch(), when() and on() functions are asynchronous, meaning that the callback will run on the next microtask after the expression value changes. This allows for batching of multiple changes and can help with performance. However, if you need the callback to run synchronously with the change, you can set the sync option to true in the options parameter.

once() and whenOnce() resolve via a Promise, so they are always asynchronous and cannot be made synchronous. If the condition is already satisfied when once() or whenOnce() is called, the promise will resolve on the next microtask with the current value.

One nuance, if you provide initial: true in the ReactiveWatchOptions for watch() and when(), the callback will run immediately after initialization if the condition is met, and then continue to watch for changes. In this case, the callback runs synchronously with the initial check, but subsequent calls are asynchronous. This is useful when you don’t want to duplicate initialization logic or manually “seed” state.

const handle = reactiveUtils.when(
  () => layer.visible === true,
  () => showLayerUI(),
  { initial: true }
);

// Remove the handle when it's no longer needed to stop watching for changes
handle.remove();

Without initial: true, you might miss the fact that layer.visible was already true at startup and only respond to future changes.

Working with collections

reactiveUtils can observe changes with a Collection, such as the Map component’s allLayerViews. Methods like Collection.map() and Collection.filter(), can be used in the getValue expression to derive values. This ensures the callback reacts to additions, removals, or updates in the collection.

const handle = reactiveUtils.watch(
  () => viewElement.allLayerViews.map((layerView) => layerView.visible),
  (layerViews) => {
    console.log(`Visible layerViews: ${layerViews}`);
  });

// Remove the handle when it's no longer needed to stop watching for changes
handle.remove();

Working with objects

reactiveUtils allows you to track object properties using dot notation (e.g. viewElement.updating) or bracket notation (e.g. viewElement["updating"]).

Optional chaining (?.) can be used to safely access nested properties without manually checking each level.

const handle = reactiveUtils.watch(
  () => viewElement?.extent?.xmin,
  (xmin) => {
    console.log(`Extent change xmin = ${xmin}`);
  }
);

// Remove the handle when it's no longer needed to stop watching for changes
handle.remove();

ResourceHandles and Promises

The watch(), on() and when() functions return a ResourceHandle. Handles retain references to observed objects and callbacks until they are removed. The once() and whenOnce() functions return a Promise instead of a ResourceHandle and have the option to be cancelled via an AbortSignal. When cancelled, the Promise settles and is eligible for disposal.

watch() and when() have an optional once property in their options parameter. When once: true is set, the returned ResourceHandle will automatically remove itself after the first time the callback is executed, which can be useful for one-time conditions while still allowing for manual removal if needed.

To avoid memory leaks:

• Remove handles when the reference is no longer needed, such as during component teardown or before creating a replacement handle.
• Use Handles to manage groups of handles.
• Abort unresolved async operations, this allows them to be disposed.

Removing a handle stops the observation and releases references to observed objects and callbacks, allowing them to be garbage collected. Handle removal is idempotent and can be safely called multiple times.

// Remove a ResourceHandle to stop watching for changes
const handle = reactiveUtils.watch(
  () => viewElement?.extent?.xmin,
  (xmin) => {
    console.log(`Extent change xmin = ${xmin}`)
  });

// Remove the handle when it's no longer needed to stop watching for changes
handle.remove()

Use Handles to group multiple ResourceHandles and remove them together, such as when a component is torn down. This also makes it easier to manage handles by name.

const handles = new Handles();
handles.add(
  reactiveUtils.watch(...),
  "view-watcher" // groupKey is optional but can be helpful for managing handles
);

// In another function or during component teardown
handles.remove("view-watcher");

The once() and whenOnce() functions return a Promise. In some advanced use cases where an action may take additional time, these functions also offer the option to cancel the async callback via an AbortSignal.

let abortController = new AbortController();
const { signal } = abortController;

// Cancel the async callback by sending an AbortSignal
const abort = () => {
  abortController?.abort();
}

// Set the signal property to watch for abort signals
// and reject the promise if the signal is aborted before the promise resolves
reactiveUtils.whenOnce(
  () => !viewElement.updating,
  { signal }
)
.then((updating) => {
  console.log("Map is not updating", updating);
})
.catch((error) => {
  if (error.name === "AbortError") {
    console.log("The async callback was aborted");
  } else {
    console.error("An unexpected error occurred:", error);
  }
})
.finally(() => {
  console.log("Async callback has completed or was aborted");
  abortController = null;
});

See the SDK guide topic on Async cancellation with AbortController for more details and examples.

Working with TypeScript

reactiveUtils also works with TypeScript. TypeScript infers the expression result type from the getValue expression and passes it to the callback. For array expressions, use explicit tuple typing when positional meaning matters. Using as const preserves tuple types so callback parameters are strongly typed by position. You can also use objects to group values and maintain strong typing without relying on position.

The first snippet shows how to use as const for tuple typing when tracking multiple properties in an array.

import { watch } from "@arcgis/core/core/reactiveUtils.js";
import type { ArcgisMap } from "@arcgis/map-components/components/arcgis-map";

// Get a reference to the map component
const arcgisMap = document.querySelector<ArcgisMap>("arcgis-map");

const handle = reactiveUtils.watch(
  () => [view.stationary, view.zoom] as const,
  ([stationary, zoom], oldValue) => {
    if (stationary) {
      const previousZoom = oldValue?.[1];
      console.log("Zoom:", zoom, "Previous:", previousZoom);
    }
  }
);

// Remove the handle when it's no longer needed to stop watching for changes
handle.remove();

The second snippet shows how to use an object to group values and maintain strong typing without relying on position. One advantage of this approach is the callback properties are named. The order of properties in the getValue expression doesn't matter. This improves maintainability and readability, especially when tracking multiple properties or when the expression is complex because the properties are matched by the name and not position.

const handle = reactiveUtils.watch(
  () => ({
    scale: viewElement.scale,
    stationary: viewElement.stationary,
    extent: viewElement.extent
  }),
  ({ stationary, extent, scale }) => {
    if (stationary) {
      console.log("View stopped moving");
      console.log("Scale:", scale);
      console.log("Extent:", extent);
    }
  }
);

If the getValue expression may return null or undefined, shape the expression so the callback only runs when a defined value is available.

This avoids unnecessary callback executions and ensures TypeScript receives a narrowed type.

const handle = reactiveUtils.when(
  () => viewElement.popupElement?.selectedFeature?.geometry,
  (geometry) => {
    console.log(geometry.type);
  }
);

// Remove the handle when it's no longer needed to stop watching for changes
handle.remove();

See also

• Watch for changes guide topic

• Sample - Watch for changes in components using reactiveUtils

• Sample - Property changes with reactiveUtils

• Samples with reactiveUtils