arcgis-utility-network-trace-inputs | References | ArcGIS Maps SDK for JavaScript

ESM

import "@arcgis/map-components/components/arcgis-utility-network-trace-inputs";

Inheritance: ArcgisUtilityNetworkTraceInputs→HTMLElement

Since: ArcGIS Maps SDK for JavaScript 5.2

The Utility Network Trace Inputs component collects the inputs needed to run a utility network trace. These include a utility network and one of its named trace configurations, starting points, stopping points (available for path trace configurations), and barriers.

For a subnetwork trace configured with a subnetwork name, users select a subnetwork instead of adding starting points.

Required setup

A MapView with a WebMap that contains a utility network and the utility network's layers. Set view to that MapView.
Users must choose a utility network (if the web map contains more than one) and a named trace configuration. The utility network can also be supplied through selectedUtilityNetwork.

Optional inputs

When users click the map to select a trace location, the component presents candidate features at that point using the Features component. Users can inspect the features and add one as a trace location. Customize the actions presented with those features using actions, hideActionBar, and includeDefaultActionsDisabled. Use beforeMapInteraction to run an asynchronous callback before trace location selection begins, such as closing a popup or canceling another tool.

This component does not execute traces or display trace results. Use selectedUtilityNetwork, selectedNamedTraceConfiguration, traceConfiguration, and traceLocations to execute a trace with UtilityNetwork.trace().

See also

Example

Display a web map and trace inputs side by side using Calcite Shell and Shell Panel components. Import the map, trace inputs, and Calcite components before running this example. The web map must contain a utility network and its layers, and may require authentication.

<calcite-shell>
  <calcite-shell-panel slot="panel-start">
    <calcite-panel heading="Trace inputs">
      <arcgis-utility-network-trace-inputs id="trace-inputs">
      </arcgis-utility-network-trace-inputs>
    </calcite-panel>
  </calcite-shell-panel>
  <arcgis-map id="trace-map" item-id="471eb0bf37074b1fbb972b1da70fb310"></arcgis-map>
</calcite-shell>

Assign the map's view after it is ready. Close its popup before selecting trace locations, and hide the feature action bar during selection. Call runTrace() from the app's trace button handler. The handler reads the component's current values.

const mapElement = document.getElementById("trace-map");
const inputs = document.getElementById("trace-inputs");
await mapElement.viewOnReady();

inputs.view = mapElement.view;
inputs.hideActionBar = true;
inputs.beforeMapInteraction = async () => {
  mapElement.view.closePopup();
};

async function runTrace() {
  try {
    const {
      selectedUtilityNetwork: utilityNetwork,
      selectedNamedTraceConfiguration: namedTraceConfiguration,
      traceConfiguration,
      traceLocations,
    } = inputs;

    if (!utilityNetwork || !namedTraceConfiguration?.traceType || !traceConfiguration) {
      throw new Error("Select a utility network and trace configuration first.");
    }

    const result = await utilityNetwork.trace({
      traceType: namedTraceConfiguration.traceType,
      resultTypes: namedTraceConfiguration.resultTypes,
      traceConfiguration,
      traceLocations,
    });

    console.log(result);
  } catch (error) {
    console.error("Trace failed:", error);
  }
}

Properties

Property	Attribute	Type
actions		ArcgisFeaturesNext["actions"] \| undefined
autoDestroyDisabled	auto-destroy-disabled	boolean
beforeMapInteraction		(() => Promise<void>) \| undefined
hideActionBar	hide-action-bar	boolean
includeDefaultActionsDisabled	include-default-actions-disabled	boolean
messageOverrides		Record<string, unknown> \| undefined
mode reflected	mode	UtilityNetworkTraceAnalysisDisplayMode
referenceElement	reference-element	ArcgisReferenceElement \| string \| undefined
selectedNamedTraceConfiguration		NamedTraceConfiguration \| undefined
selectedUtilityNetwork		UtilityNetwork \| undefined
traceConfiguration readonly		UNTraceConfiguration \| undefined
traceLocations readonly		TraceLocation[]
view		MapView \| undefined

actions

Property

Type: ArcgisFeaturesNext["actions"] | undefined

A collection of action button or action toggle objects. Each action may be executed by clicking the icon or image symbolizing them. There is a default Zoom To action styled with a magnifying glass icon to zoom in four LODs and center the map on the selected feature. This default action can be removed by setting includeDefaultActionsDisabled to true, or by setting the overwriteActions property to true in a PopupTemplate.

The order of each action is the order in which they appear in the actions Collection. The @arcgisTriggerAction event fires each time an action is clicked.

See also

autoDestroyDisabled

Property

Type: boolean

If true, the component will not be destroyed automatically when it is disconnected from the document. This is useful when you want to move the component to a different place on the page, or temporarily hide it. If this is set, make sure to call the destroy() method when you are done to prevent memory leaks.

Attribute: auto-destroy-disabled
Default value: false

Example

<arcgis-utility-network-trace-inputs auto-destroy-disabled></arcgis-utility-network-trace-inputs>

utilityNetworkTraceInputsElement.autoDestroyDisabled = true;

beforeMapInteraction

Property

Type: (() => Promise<void>) | undefined

An asynchronous callback invoked before the user selects a trace location. Selection begins after this callback completes. Use this callback to finish or cancel active map tools or interactions that might interfere with selecting a trace location, such as sketching, measurement, or map selection tools, or to close a popup.

To prevent selection from starting, call preventDefault() on @arcgisTraceLocationSelectStart.

Example

Prevent selecting trace locations while another tool is active.

import SketchViewModel from "@arcgis/core/widgets/Sketch/SketchViewModel.js";

const inputs = document.querySelector("arcgis-utility-network-trace-inputs");
const sketch = new SketchViewModel({ view: inputs.view });
inputs.addEventListener("arcgisTraceLocationSelectStart", (event) => {
  if (sketch.state === "active") {
    event.preventDefault();
  }
});

hideActionBar

Property

Type: boolean

Whether the action bar that holds the feature's arcgis-features-next.actions is hidden when selecting trace locations.

See also

Attribute: hide-action-bar
Default value: false

includeDefaultActionsDisabled

Property

Type: boolean

Whether default actions are disabled (hidden) when selecting trace locations. This property must be set to true to disable default actions.

See also

arcgis-features-next.includeDefaultActionsDisabled

Attribute: include-default-actions-disabled
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.

mode

reflected Property

Type: UtilityNetworkTraceAnalysisDisplayMode

The current display mode. The component updates this property during trace location selection.

default: Displays the network, configuration, and trace location inputs.
add-spatial-instructions: Displays instructions for selecting a location on the map.
add-spatial-feature: Displays candidate features so the user can choose a trace location.

Attribute: mode
Default value: "default"

referenceElement

Property

Type: ArcgisReferenceElement | string | undefined

By assigning the id attribute of the Map or Scene component to this property, you can position a child component anywhere in the DOM while still maintaining a connection to the Map or Scene.

See also

Associate components with a Map or Scene component

Attribute: reference-element

selectedNamedTraceConfiguration

Property

Type: NamedTraceConfiguration | undefined

The named trace configuration to use. It determines the trace type and its settings. Users choose one in the component's trace configuration picker. Set this property to one of the selected utility network's shared named trace configurations to select it programmatically, including before the component or utility network finishes loading. The selection is preserved when it is included in the available configurations.

selectedUtilityNetwork

Property

Type: UtilityNetwork | undefined

The utility network to use for the trace. The component loads it if needed and shows the named trace configurations from that utility network's sharedNamedTraceConfigurations. Changing the utility network clears any trace locations previously added, such as starting points and barriers, and updates the available named trace configurations.

traceConfiguration

readonly Property

Type: UNTraceConfiguration | undefined

A clone of the UNTraceConfiguration associated with selectedNamedTraceConfiguration. The component updates this clone to reflect changes such as the selected subnetwork name, without modifying the original named trace configuration.

This property is read-only, but the returned configuration object is mutable. Pass this object to UtilityNetwork.trace() to use the current input settings. It is undefined when no configuration is available.

Example

After selecting a network and configuration and completing the required trace inputs:

const inputs = document.querySelector("arcgis-utility-network-trace-inputs");

try {
  const { selectedUtilityNetwork, selectedNamedTraceConfiguration, traceConfiguration } = inputs;
  if (!selectedUtilityNetwork || !selectedNamedTraceConfiguration?.traceType || !traceConfiguration) {
    throw new Error("Select a utility network and trace configuration first.");
  }

  const result = await selectedUtilityNetwork.trace({
    traceType: selectedNamedTraceConfiguration.traceType,
    resultTypes: selectedNamedTraceConfiguration.resultTypes,
    traceConfiguration,
    traceLocations: inputs.traceLocations,
  });
  console.log(result);
} catch (error) {
  console.error("Trace failed:", error);
}

traceLocations

readonly Property

Type: TraceLocation[]

The trace locations currently added for the trace. Returns a new array of TraceLocation objects that can include starting points, stopping points, and barriers. If a trace location has multiple terminals selected, the returned array contains one entry for each selected terminal.

The returned location types depend on selectedNamedTraceConfiguration. Starting points are excluded for a subnetwork trace when the selected named trace configuration specifies a subnetworkName. Stopping points are included only for path traces. Barriers are always included.

The returned array can be empty or contain locations with missing terminal selections, depending on the user's inputs in the component.

view

Property

Type: MapView | undefined

The view associated with the component.

Note: The recommended approach is to fully migrate applications to use map and scene components and avoid using MapView and SceneView directly. However, if you are migrating a large application from widgets to components, you might prefer a more gradual transition. To support this use case, the SDK includes this view property which connects a component to a MapView or SceneView. Ultimately, once migration is complete, the arcgis-utility-network-trace-inputs component will be associated with a map or scene component rather than using the view property.

Methods

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

componentOnReady

inherited Method

Signature: componentOnReady (): Promise<this>

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

Returns: Promise<this>

Example

const arcgisUtilityNetworkTraceInputs = document.createElement("arcgis-utility-network-trace-inputs");
document.body.append(arcgisUtilityNetworkTraceInputs);
await arcgisUtilityNetworkTraceInputs.componentOnReady();
console.log("arcgis-utility-network-trace-inputs is ready to go!");

destroy

Method

Signature: destroy (): Promise<void>

Permanently destroy the component.

Returns: Promise<void>

Events

Name	Type
arcgisPropertyChange	CustomEvent<{ name: "mode" \| "selectedNamedTraceConfiguration" \| "selectedUtilityNetwork" \| "traceLocations"; }>
arcgisTraceLocationSelectEnd	CustomEvent<void>
arcgisTraceLocationSelectStart	CustomEvent<SelectStartPayload>
arcgisTriggerAction	CustomEvent<ActionEvent>

arcgisPropertyChange

Event

 arcgisPropertyChange: CustomEvent<{ name: "mode" | "selectedNamedTraceConfiguration" | "selectedUtilityNetwork" | "traceLocations"; }>

Emitted when the value of a property is changed. Use this to listen to changes to properties.

arcgisTraceLocationSelectEnd

Event

arcgisTraceLocationSelectEnd: CustomEvent<void>

Fires when trace location selection ends, including when selection is canceled. This event does not guarantee that a trace location was added.

arcgisTraceLocationSelectStart

Event

arcgisTraceLocationSelectStart: CustomEvent<SelectStartPayload>

Fires before map interaction begins to select a trace location, after beforeMapInteraction resolves, if provided. Call event.preventDefault() to prevent selection from starting. The event's detail.cancelSelect function can be called to cancel the selection after it starts.

arcgisTriggerAction

Event

arcgisTriggerAction: CustomEvent<ActionEvent>

Emitted when an action is triggered on the component.