ArcGIS Maps SDK for JavaScript

Build GIS Web Apps with JavaScript Maps SDK components

What is the ArcGIS Maps SDK for JavaScript?

The ArcGIS Maps SDK for JavaScript is a powerful mapping and spatial analysis technology that enables developers to build compelling web GIS experiences. At Esri, we use this foundational SDK to develop geospatial applications. These applications enable users to create, analyze, collaborate on, and share their maps.

What are web components?

Introduced by the W3C, web components are a set of technologies native to the browser that allow the construction of custom reusable and framework-agnostic HTML elements. They provide strong encapsulation, custom functionality, and full compatibility with HTML and the DOM API. There are three main technologies provided by web components that we use in the SDK:

In summary, web components are great for simplifying complex HTML, along with its associated CSS and JavaScript. Next, we’ll go over the JavaScript Maps SDK and how web components are available as a new feature of the SDK.

ArcGIS Maps SDK for JavaScript components

The October 2023 release of ArcGIS Maps SDK for JavaScript (v4.28) introduced a beta version of our standards-based web components. JavaScript Maps SDK components are a component library extending parts of the JavaScript Maps SDK to provide reusable custom HTML elements that can be easily brought into your own GIS web applications. As of v4.30 of the JavaScript Maps SDK, three component packages are offered:

With Map components, you can showcase a web map with one line of HTML:

<arcgis-map item-id="05e015c5f0314db9a487a9b46cb37eca></arcgis-map>

Why our developers use web components from the SDK

Web components have a rich history at Esri. By adopting web components as fundamental building blocks in our development process, we have been able to create a wide range of reusable HTML elements that are not tied to any specific application framework (e.g., React, Angular, Vue) or module bundler (e.g., Vite, Webpack). We also heavily utilize components from Calcite Design System. This adoption of web components unifies our developers and ensures consistent user experiences across different ArcGIS products.

In terms of programming paradigms, JavaScript Maps SDK components offer a declarative-first approach, while the JavaScript Maps SDK has traditionally followed a mostly imperative/procedural approach. With the components, developers can rely on prebuilt ArcGIS experiences that reduce the need for boilerplate code and instead focus on using HTML markup to accomplish most—if not all—of the required tasks. This simplifies the process of integrating ArcGIS capabilities into your app. On the other hand, the JavaScript Maps SDK provides extensive control over the application’s state and flow of execution by allowing developers to write detailed instructions.

A new way to build JS Maps SDK apps: Use components

To gain a better understanding of how you might create a basic web map using the imperative approach, check out the example below. JavaScript is used to manipulate the <div id="viewDiv"></div> container element which is responsible for displaying the map and its widgets.

Web map built with the JavaScript Maps SDK

To illustrate the difference between the two paradigms, let’s consider the previous example and demonstrate how it may be rewritten using the @arcgis/map-components package.

Web map built with JavaScript Maps SDK components

As you have seen with map components, JavaScript is not necessary to achieve the same solution, which eliminates the need for the viewDiv container element. It also simplifies needing to separately initialize the WebMap and MapView. It is important to note that while the example was written purely with web components, the underlying API is still available, creating a balance between the imperative and declarative programming paradigms. This flexibility allows you to reap the benefits of both approaches.

  <arcgis-map item-id="05e015c5f0314db9a487a9b46cb37eca">
    <arcgis-search position="top-right" />
    <arcgis-legend position="bottom-left" />
    // Access the underlying API to get the thumbnail url of the map
    const mapElm = document.querySelector("arcgis-map");
    mapElm.addEventListener("arcgisViewReadyChange", (event) => {
      const { map } =;

Integrate your apps with the Calcite Design System

You can integrate the Calcite Design System with JavaScript Maps SDK apps to build comprehensive and engaging GIS experiences. Observe that again with the imperative approach, there is boilerplate code and <div/> HTML elements needed to be created and manipulated with JavaScript.

Web map built with the JavaScript Maps SDK and Calcite

Web map built with JavaScript Maps SDK components and Calcite

Easily associate components with a Map or Scene

The Map and Scene components are parent containers for building interactive 2D and 3D visualization experiences. Other components from the @arcgis/map-components package can be associated with a Map or Scene component to provide additional functionality, such as adding a legend, layer list, search, and more. The legend component can access a map by setting its reference-element (see the Properties tab for more) to the id of the <arcgis-map/>. This is useful when components live outside of the <arcgis-map/> component.

Legend associated with a map

Get started today!

Explore component tutorials, where you can discover components to build web mapping applications with minimal code. Also, stay tuned – additional components will be available in upcoming releases.

For more information, refer to the component documentation. If you encounter an issue, visit the troubleshooting guide and to collaborate with others, ask questions, or report issues visit Esri Community.

About the author

Omar is a biotechnologist, geographer and computer scientist who works at Esri as a Product Engineer on the ArcGIS Maps SDK for JavaScript components and Arcade expression language. Omar's main focus is to help develop and integrate modern web components like the Arcade editor which you can now find across ArcGIS Online!

Notify of
Inline Feedbacks
View all comments

Next Article

Explore BlueBikes ride data with ArcGIS Pro Charts

Read this article