arcgis-utility-network-picker | References | ArcGIS Maps SDK for JavaScript

ESM

import "@arcgis/map-components/components/arcgis-utility-network-picker";

Inheritance: ArcgisUtilityNetworkPicker→HTMLElement

Since: ArcGIS Maps SDK for JavaScript 5.2

The Utility Network Picker component selects a utility network from a web map. It is used by the arcgis-utility-network-trace-analysis component and can also be used independently.

Set view to a MapView whose web map contains utility networks. The component loads the map and the selected network. The component displays the network's title when the map contains one utility network, or a combobox for multiple utility networks.

When the map's networks are loaded, the first network is selected if the current selection is missing or does not belong to the map. Selecting a network does not execute a trace. Access the selected utility network with the selectedUtilityNetwork property.

Changing the selected utility network loads the new selected utility network if it is not already loaded. Before using the new selected UtilityNetwork, await its load() method, which resolves with the loaded instance, including when it is already loaded. componentOnReady() waits for component initialization, not for the selected network to load.

Customize what this component displays with heading, hideErrors, and hideLoader.

Example

Place a standalone picker in a pane next to a web map containing utility networks. Configure authentication for secured resources before loading the map.

<calcite-shell>
  <calcite-shell-panel slot="panel-start">
    <calcite-panel heading="Utility networks">
      <arcgis-utility-network-picker></arcgis-utility-network-picker>
    </calcite-panel>
  </calcite-shell-panel>
  <arcgis-map item-id="471eb0bf37074b1fbb972b1da70fb310"></arcgis-map>
</calcite-shell>

import "@arcgis/map-components/components/arcgis-map";
import "@arcgis/map-components/components/arcgis-utility-network-picker";

const mapElement = document.querySelector("arcgis-map");
await mapElement.viewOnReady();

const picker = document.querySelector("arcgis-utility-network-picker");
picker.view = mapElement.view;
picker.addEventListener("arcgisError", (event) => {
  console.error(event.type, picker.error);
});

picker.addEventListener("arcgisPropertyChange", async (event) => {
  if (event.detail.name !== "selectedUtilityNetwork") {
    return;
  }

  const network = picker.selectedUtilityNetwork;
  if (!network) {
    return;
  }

  try {
    const loadedNetwork = await network.load();
    if (picker.selectedUtilityNetwork === loadedNetwork) {
      console.log(loadedNetwork.dataElement);
    }
  } catch (error) {
    console.error(error);
  }
});

Properties

Property	Attribute	Type
error	error	string \| undefined
heading	heading	string \| undefined
hideErrors	hide-errors	boolean
hideLoader	hide-loader	boolean
messageOverrides		Record<string, unknown> \| undefined
selectedUtilityNetwork		UtilityNetwork \| undefined
state	state	"error" \| "loading" \| "ready"
view		MapView \| undefined

error

Property

Type: string | undefined

The current error message, or undefined when cleared. Errors can occur when the view has no map, the map cannot be loaded, the map has no utility networks, or the selected network cannot be loaded. The component displays this message unless hideErrors is true.

The error message is cleared when map setup starts or a selected network becomes ready. Selecting another network that loads successfully recovers from a network-load error. While a new network is loading, the previous error can remain; check state to distinguish loading from an active error.

Attribute: error

Example

Read the error message when the component emits arcgisError.

const picker = document.querySelector("arcgis-utility-network-picker");
picker.addEventListener("arcgisError", () => {
  console.error(picker.error);
});

heading

Property

Type: string | undefined

The heading above the utility network title or combobox. When not set or empty, the component uses the localized utility network label.

Attribute: heading

hideErrors

Property

Type: boolean

Whether to hide error notices. Errors still update error and state and emit @arcgisError.

Attribute: hide-errors
Default value: false

hideLoader

Property

Type: boolean

Whether to hide the loading indicator. This does not prevent the component from loading the map or the selected utility network.

Attribute: hide-loader
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.

selectedUtilityNetwork

Property

Type: UtilityNetwork | undefined

The selected UtilityNetwork. Set this property to a network from the view's web map to select it programmatically. The component loads the selected network if needed.

When the map's networks are loaded, the component selects the first network if this property is unset or refers to a network outside the map's collection. The same selection rule applies when the view or its map is replaced. The selection is cleared when the map has no utility networks.

Example

Select a network before adding the picker to the page. Here, mapView is a MapView backed by a WebMap containing utility networks. Replace "your-network-id" with the ID of a network in that map.

const map = mapView.map;
await map.load();
const network = map.utilityNetworks.find((network) => network.id === "your-network-id");
if (!network) {
  throw new Error("The requested utility network is not in this web map.");
}

const picker = document.createElement("arcgis-utility-network-picker");
picker.view = mapView;
picker.selectedUtilityNetwork = network;
document.body.append(picker);

state

Property

Type: "error" | "loading" | "ready"

The current component state.

error: The component could not set up the map, find a utility network, or load the selected network. See error for details.
loading: The component is setting up the map or loading the selected utility network.
ready: Setup is complete and no loading error occurred.

Selecting an unloaded network returns the component to loading until that network loads successfully (ready) or fails to load (error).

Attribute: state
Default value: "loading"

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-picker component will be associated with a map or scene component rather than using the view property.

Methods

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

componentOnReady

inherited Method

Signature: componentOnReady (): Promise<this>

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

Returns: Promise<this>

Example

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

Events

Name	Type
arcgisError	CustomEvent<void>
arcgisPropertyChange	CustomEvent<{ name: "selectedUtilityNetwork" \| "state"; }>

arcgisError

Event

arcgisError: CustomEvent<void>

Fires when an error occurs while setting up the map or loading a utility network. Read error for the message and state for the current state. This event has no detail payload and fires even when hideErrors is true.

Example

const picker = document.querySelector("arcgis-utility-network-picker");
picker.addEventListener("arcgisError", () => {
  console.error(picker.error);
});

arcgisPropertyChange

Event

arcgisPropertyChange: CustomEvent<{ name: "selectedUtilityNetwork" | "state"; }>

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