Migrate 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.

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.
• 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 the amount of repetitive code needed every time you implement an application with the JavaScript Maps SDK. For example, here is the JavaScript code for a simple map using the SDK's AMD modules.

1
2
3
4
5
6
7
8
9
10
11
12
require(["esri/Map", "esri/views/MapView"], (Map, MapView) => {
  const map = new Map({
    basemap: "streets-vector"
  });

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

Here is the equivalent code in HTML using map-components. This snippet demonstrates setting attributes directly on the component:

1
<arcgis-map zoom="14" center="8.5,47.37" basemap="streets-vector"></arcgis-map>

Implementing custom functionality

To implement functionality that runs after the arcgis-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 listens for when the view is ready, sets several properties and then writes the map's zoom level to the console. In this simple example, there is no need to implement a require() statement (AMD) or import modules (ESM).

1
2
<arcgis-map></arcgis-map>
<script type="module" src="/main.js"></script>

1
2
3
4
5
6
7
8
9
10
11
12
13
// Query for the HTML element
const map = document.querySelector("arcgis-map");

// Set map properties programmatically
map.zoom = 14;
map.center = [8.5, 47.37];
map.basemap = "streets-vector";

// Listen for the map's view to be ready
map.addEventListener("arcgisViewReadyChange", (event) => {
  // Get or set map properties
  console.log(`Zoom level is ${map.zoom}`);
});