Migrate to components | ArcGIS Maps SDK for JavaScript

If you’re migrating an existing widget-based application, widgets are deprecated as of version 5.0 and will be removed in a future release. For timeline details, see the Transition plan: widgets to components.

Web components were added to the ArcGIS Maps SDK for JavaScript at version 4.30. These components are built as custom HTML elements which means that they are standard in modern browsers and framework-agnostic. In the SDK, components simplify common coding patterns by encapsulating much of the API’s boilerplate code.

Applications can now be defined declaratively using components (custom HTML elements), such as the Map and Scene components. This reduces the need for configuring views, containers, and module imports.

<head>
  <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
  <script type="module" src="https://js.arcgis.com/5.0/"></script>
</head>
<body>
  <arcgis-map basemap="topo-vector" zoom="4" center="15, 65"></arcgis-map>
</body>

Getting started

If you are new to web components or just need to brush up on the topic, there are a variety of resources to help:

Explore the components tutorials or code samples on GitHub if you want to immediately start coding.
Read the Programming patterns guide topic for insights on working with attributes and properties, watching for changes and more.
Visit the References page to check out properties, methods and events.
Learn about additional component packages such as AI components (beta), Charts components, Coding components, Common components, and Embeddable components.
Check out the blog Build GIS Web Apps with the JavaScript Maps SDK components.
Visit the MDN Web Components resource page.

Basic implementation

Using components reduces repetitive boilerplate code when implementing applications with the JavaScript Maps SDK. For example, here is the legacy pattern for creating a simple map with the Map and MapView classes from the core API.

const [Map, MapView] = await $arcgis.import([
  "@arcgis/core/Map.js",
  "@arcgis/core/views/MapView.js",
]);
const map = new Map({
  basemap: "streets-vector",
});

const view = new MapView({
  container: "viewDiv",
  map: map,
  zoom: 14,
  center: [15, 65],
});

Here is the equivalent code in HTML using Map components. This removes the need to manually create a view, manage a container element, or import core view modules for common use cases. This snippet demonstrates setting attributes directly on the component:

<arcgis-map zoom="14" center="15, 65" basemap="streets-vector"></arcgis-map>

Position UI elements declaratively with slots

Component-based patterns replace view.ui.add with slots, allowing UI elements—such as other components or custom HTML—to be positioned declaratively in markup and managed as part of the DOM. Layout and styling follow standard HTML and CSS behavior, enabling more flexible design without requiring SDK-specific constructs and imports.

<arcgis-map zoom="14" center="15, 65" basemap="streets-vector">
  <arcgis-zoom slot="top-left"></arcgis-zoom>
  <arcgis-basemap-toggle slot="bottom-right" next-basemap="topo"></arcgis-basemap-toggle>
  <div id="my-custom-ui-content" slot="bottom-right"></div>
</arcgis-map>

This approach keeps UI placement close to the markup and avoids view lifecycle timing concerns common with imperative UI code.

Associate components with a map or scene using reference-element

In addition to slots, you can position components anywhere in the DOM and connect them to a map or scene by using the reference-element attribute. Pass the id of the <arcgis-map> or <arcgis-scene> element to keep the component wired up while allowing more flexible layout.

<arcgis-map id="my-map" zoom="14" center="15, 65" basemap="streets-vector"></arcgis-map>
<arcgis-legend reference-element="my-map"></arcgis-legend>

When to continue using the core API

Components simplify application setup and UI composition, but they are not a replacement for the JavaScript Maps SDK core API. Advanced workflows, such as custom layer logic, renderers, querying, or complex view interactions, can continue to use core modules alongside components.

Implementing custom functionality with JavaScript

To implement functionality that runs after the Map component has loaded, you can query for the HTML element and then use the element’s object to set event listeners, get or set properties, or implement methods directly on the component.

Here’s a snippet that sets several properties, waits for when the view is ready, and then logs the map’s itemId to the console. If you need additional functionality, you can still import core API modules dynamically (example below).

index.html

<arcgis-map item-id="05e015c5f0314db9a487a9b46cb37eca"></arcgis-map>
<script type="module" src="/main.js"></script>

main.js

// Query for the HTML element
const viewElement = document.querySelector("arcgis-map");

// Set map properties programmatically
viewElement.zoom = 14;
viewElement.center = [15, 65];
viewElement.basemap = "streets-vector";

// Wait for the view to be ready
await viewElement.viewOnReady();

// Log the map's item id
console.log(viewElement.itemId)

// Optional: use core API modules for custom behavior
const FeatureLayer = await $arcgis.import("@arcgis/core/layers/FeatureLayer.js");
const weatherStationsLayer = new FeatureLayer({
  url: "https://services.arcgis.com/V6ZHFr6zdgNZuVG0/arcgis/rest/services/weather_stations_010417/FeatureServer/0",
});
viewElement.map.add(weatherStationsLayer);

Components can be configured programmatically through properties or directly in the custom element using attributes. Properties can be updated, events can be observed, and lifecycle methods such as viewOnReady() are exposed for controlling application logic flow.

While components streamline application setup, most projects can continue to use the core API to support custom behavior as shown above. Modules can be imported dynamically using $arcgis.import() to configure views or integrate additional functionality as needed.