Create a web app using components | ArcGIS Maps SDK for JavaScript

Learn how to create a web application with Map Components and Calcite components using Vite developer build tools.

In this tutorial, you will:

Load and display a pre-configured web map stored in ArcGIS Online with an arcgis-layer-list component.
Create an application layout and user interface with Calcite components.
Add a map and a layer list leveraging Map Components.
Learn how to use the core API library to interact with the View, Map, and layers.

Prerequisites

The most recent LTS Node.js runtime environment.
A text editor to edit files.
A terminal to enter commands.

Steps

Create a new project using Vite

Download the initial Vite vanilla Javascript project to your local machine.
Unzip the downloaded file.
Open the unzipped folder’s files in your text editor.
Navigate to the unzipped folder in your terminal.

Install dependencies

To use map components, install the @arcgis/map-components package and its dependencies into your project:
npm install @arcgis/map-components
yarn add @arcgis/map-components @arcgis/core @esri/calcite-components
Start the Vite development server.
npm run dev
yarn run dev
Open a web browser and navigate to http://localhost:5173, this webpage will be empty, however, it will update as we proceed through the remaining steps.

Import the Layer List, Map and Zoom components from the @arcgis/map-components package in main.js.

main.js

import "./style.css";

import "@arcgis/map-components/components/arcgis-layer-list";
import "@arcgis/map-components/components/arcgis-map";
import "@arcgis/map-components/components/arcgis-zoom";

Import the Shell, Navigation and Navigation Logo components from the @esri/calcite-components package in main.js.

main.js

import "./style.css";

import "@arcgis/map-components/components/arcgis-layer-list";
import "@arcgis/map-components/components/arcgis-map";
import "@arcgis/map-components/components/arcgis-zoom";

import "@esri/calcite-components/components/calcite-navigation";
import "@esri/calcite-components/components/calcite-navigation-logo";
import "@esri/calcite-components/components/calcite-shell";

Add styles

Add CSS styles to make html and body fill the entire viewport with no margin.
style.css
html, body { height: 100%; margin: 0; }

Add components

To create an application layout and user interface for your app add calcite-shell, calcite-navigation, calcite-navigation-logo components to index.html.

index.html

9 collapsed lines
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" href="data:;base64,=" />
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
    <title>ArcGIS Maps SDK for JavaScript Tutorials: Create a web app using components</title>
  </head>

  <body>

    <calcite-shell>
      <calcite-navigation slot="header">
        <calcite-navigation-logo slot="logo"></calcite-navigation-logo>
      </calcite-navigation>

    </calcite-shell>

    <script type="module" src="/main.js"></script>
  </body>
2 collapsed lines

</html>

Next, add the Map, Zoom and Layer List components.

index.html

11 collapsed lines
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" href="data:;base64,=" />
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
    <title>ArcGIS Maps SDK for JavaScript Tutorials: Create a web app using components</title>
  </head>

  <body>

    <calcite-shell>
      <calcite-navigation slot="header">
        <calcite-navigation-logo slot="logo"></calcite-navigation-logo>
      </calcite-navigation>

      <arcgis-map item-id="e691172598f04ea8881cd2a4adaa45ba" zoom="4">
        <arcgis-zoom slot="top-left"></arcgis-zoom>
        <arcgis-layer-list slot="top-right"></arcgis-layer-list>
      </arcgis-map>

    </calcite-shell>
5 collapsed lines

    <script type="module" src="/main.js"></script>
  </body>

</html>

Add a Legend to the LayerList

In main.js use document.querySelector() to get a reference for the Layer List component.

main.js

10 collapsed lines
import "./style.css";

import "@arcgis/map-components/components/arcgis-layer-list";
import "@arcgis/map-components/components/arcgis-map";
import "@arcgis/map-components/components/arcgis-zoom";

import "@esri/calcite-components/components/calcite-navigation";
import "@esri/calcite-components/components/calcite-navigation-logo";
import "@esri/calcite-components/components/calcite-shell";

// Get a reference to the arcgis-layer-list element
const arcgisLayerList = document.querySelector("arcgis-layer-list");

Add a listItemCreatedFunction to the Layer List. This function will add a Legend in the ListItemPanel for all layers except group layers.

main.js

10 collapsed lines
import "./style.css";

import "@arcgis/map-components/components/arcgis-layer-list";
import "@arcgis/map-components/components/arcgis-map";
import "@arcgis/map-components/components/arcgis-zoom";

import "@esri/calcite-components/components/calcite-navigation";
import "@esri/calcite-components/components/calcite-navigation-logo";
import "@esri/calcite-components/components/calcite-shell";

// Get a reference to the arcgis-layer-list element
const arcgisLayerList = document.querySelector("arcgis-layer-list");

// Set the listItemCreatedFunction to add a legend to each list item
arcgisLayerList.listItemCreatedFunction = (event) => {
  const { item } = event;
  if (item.layer.type !== "group") {
    item.panel = {
      content: "legend",
    };
  }
};

Interacting with the View, Map, and layers

Use document.querySelector() to get a reference for the Map component. Since we are going to use property values from the map component, we’ll use the arcgisViewReadyChange event to determine when the map is ready.

main.js

23 collapsed lines
import "./style.css";

import "@arcgis/map-components/components/arcgis-layer-list";
import "@arcgis/map-components/components/arcgis-map";
import "@arcgis/map-components/components/arcgis-zoom";

import "@esri/calcite-components/components/calcite-navigation";
import "@esri/calcite-components/components/calcite-navigation-logo";
import "@esri/calcite-components/components/calcite-shell";

// Get a reference to the arcgis-layer-list element
const arcgisLayerList = document.querySelector("arcgis-layer-list");

// Set the listItemCreatedFunction to add a legend to each list item
arcgisLayerList.listItemCreatedFunction = (event) => {
  const { item } = event;
  if (item.layer.type !== "group") {
    item.panel = {
      content: "legend",
    };
  }
};

// Get a reference to the arcgis-map element
const viewElement = document.querySelector("arcgis-map");

// Wait for the map component to be ready before accessing its properties.
viewElement.addEventListener("arcgisViewReadyChange", () => {

});

Create a variable for the map’s PortalItem instance.

main.js

26 collapsed lines
import "./style.css";

import "@arcgis/map-components/components/arcgis-layer-list";
import "@arcgis/map-components/components/arcgis-map";
import "@arcgis/map-components/components/arcgis-zoom";

import "@esri/calcite-components/components/calcite-navigation";
import "@esri/calcite-components/components/calcite-navigation-logo";
import "@esri/calcite-components/components/calcite-shell";

// Get a reference to the arcgis-layer-list element
const arcgisLayerList = document.querySelector("arcgis-layer-list");

// Set the listItemCreatedFunction to add a legend to each list item
arcgisLayerList.listItemCreatedFunction = (event) => {
  const { item } = event;
  if (item.layer.type !== "group") {
    item.panel = {
      content: "legend",
    };
  }
};

// Get a reference to the arcgis-map element
const viewElement = document.querySelector("arcgis-map");

// Wait for the map component to be ready before accessing its properties.
viewElement.addEventListener("arcgisViewReadyChange", () => {

  const { portalItem } = viewElement.map;

});

Next, add a heading, description, and thumbnail to your app’s UI using the PortalItem. To do so, set Navigation Logo’s heading, description, and thumbnail properties to the PortalItem’s title, snippet and thumbnailUrl properties.

main.js

26 collapsed lines
import "./style.css";

import "@arcgis/map-components/components/arcgis-layer-list";
import "@arcgis/map-components/components/arcgis-map";
import "@arcgis/map-components/components/arcgis-zoom";

import "@esri/calcite-components/components/calcite-navigation";
import "@esri/calcite-components/components/calcite-navigation-logo";
import "@esri/calcite-components/components/calcite-shell";

// Get a reference to the arcgis-layer-list element
const arcgisLayerList = document.querySelector("arcgis-layer-list");

// Set the listItemCreatedFunction to add a legend to each list item
arcgisLayerList.listItemCreatedFunction = (event) => {
  const { item } = event;
  if (item.layer.type !== "group") {
    item.panel = {
      content: "legend",
    };
  }
};

// Get a reference to the arcgis-map element
const viewElement = document.querySelector("arcgis-map");

// Wait for the map component to be ready before accessing its properties.
viewElement.addEventListener("arcgisViewReadyChange", () => {

  const { portalItem } = viewElement.map;

  const navigationLogo = document.querySelector("calcite-navigation-logo");
  navigationLogo.heading = portalItem.title;
  navigationLogo.description = portalItem.snippet;
  navigationLogo.thumbnail = portalItem.thumbnailUrl;

});

Find the accidental deaths layer in the view.map.layers collection.

main.js

36 collapsed lines
import "./style.css";

import "@arcgis/map-components/components/arcgis-layer-list";
import "@arcgis/map-components/components/arcgis-map";
import "@arcgis/map-components/components/arcgis-zoom";

import "@esri/calcite-components/components/calcite-navigation";
import "@esri/calcite-components/components/calcite-navigation-logo";
import "@esri/calcite-components/components/calcite-shell";

// Get a reference to the arcgis-layer-list element
const arcgisLayerList = document.querySelector("arcgis-layer-list");

// Set the listItemCreatedFunction to add a legend to each list item
arcgisLayerList.listItemCreatedFunction = (event) => {
  const { item } = event;
  if (item.layer.type !== "group") {
    item.panel = {
      content: "legend",
    };
  }
};

// Get a reference to the arcgis-map element
const viewElement = document.querySelector("arcgis-map");

// Wait for the map component to be ready before accessing its properties.
viewElement.addEventListener("arcgisViewReadyChange", () => {

  const { portalItem } = viewElement.map;

  const navigationLogo = document.querySelector("calcite-navigation-logo");
  navigationLogo.heading = portalItem.title;
  navigationLogo.description = portalItem.snippet;
  navigationLogo.thumbnail = portalItem.thumbnailUrl;

  const layer = viewElement.map.layers.find((layer) => layer.id === "Accidental_Deaths_8938");

1 collapsed line
});

Modify the layer’s PopupTemplate title.

main.js

36 collapsed lines
import "./style.css";

import "@arcgis/map-components/components/arcgis-layer-list";
import "@arcgis/map-components/components/arcgis-map";
import "@arcgis/map-components/components/arcgis-zoom";

import "@esri/calcite-components/components/calcite-navigation";
import "@esri/calcite-components/components/calcite-navigation-logo";
import "@esri/calcite-components/components/calcite-shell";

// Get a reference to the arcgis-layer-list element
const arcgisLayerList = document.querySelector("arcgis-layer-list");

// Set the listItemCreatedFunction to add a legend to each list item
arcgisLayerList.listItemCreatedFunction = (event) => {
  const { item } = event;
  if (item.layer.type !== "group") {
    item.panel = {
      content: "legend",
    };
  }
};

// Get a reference to the arcgis-map element
const viewElement = document.querySelector("arcgis-map");

// Wait for the map component to be ready before accessing its properties.
viewElement.addEventListener("arcgisViewReadyChange", () => {

  const { portalItem } = viewElement.map;

  const navigationLogo = document.querySelector("calcite-navigation-logo");
  navigationLogo.heading = portalItem.title;
  navigationLogo.description = portalItem.snippet;
  navigationLogo.thumbnail = portalItem.thumbnailUrl;

  const layer = viewElement.map.layers.find((layer) => layer.id === "Accidental_Deaths_8938");

  layer.popupTemplate.title = "Accidental Deaths";
2 collapsed lines

});

Run the application

Start the application from your project directory by running npm run dev in a terminal window. It should launch and be visible in your browser at http://localhost:5173.