Create a web app using components

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 a LayerList widget.
• 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 ArcGIS Maps SDK for JavaScript to interact with the View, Map, and layers.

Prerequisites

Steps

Create a new project using Vite

1. Download the inital Vite vanilla Javascript project to your local machine.
2. Unzip the downloaded file.
3. Open the unzipped folder's files in your text editor.
4. Navigate to the unzipped folder in your terminal.

Install dependencies

1. Install Map Components in the terminal as a dependency.

   Use dark colors for code blocksCopy

   1
   npm install @arcgis/map-components

2. Later in this tutorial we will need to know which version of @esri/calcite-components was installed as a dependency of @arcgis/map-components, run this command in the terminal window to find the correct version.

   Use dark colors for code blocksCopy

   1
   npm list @esri/calcite-components

3. Start the Vite development server.

   Use dark colors for code blocksCopy

   1
   npm run dev

4. Open a web browser and navigate to http://localhost:5173, this webpage will be empty however it will update as we proceed thrugh the remaining steps.

5. Import functions to define the custom HTML elements from the Map Components and Calcite Components libraries in main.js. You will need to use an alias, because the imported function from each library has the same name, defineCustomElements.

   main.js

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   
   import "./style.css";
   
   
   import { defineCustomElements as defineMapElements } from "@arcgis/map-components/dist/loader";
   import { defineCustomElements as defineCalciteElements } from "@esri/calcite-components/dist/loader";
   
   
   
   

6. Define the custom elements on the window using the Calcite Components distribution build. You will use CDN-hosted assets. When using the CDN-hosted assets, you need to keep the version number in the path the same as the version of @esri/calcite-components found in step two.

   main.js

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   
   import "./style.css";
   
   
   import { defineCustomElements as defineMapElements } from "@arcgis/map-components/dist/loader";
   import { defineCustomElements as defineCalciteElements } from "@esri/calcite-components/dist/loader";
   
   defineCalciteElements(window, {
     resourcesUrl: "https://js.arcgis.com/calcite-components/2.5.1/assets"
   });
   
   
   
   

7. Next, use the Map Components distribution build to define and lazy load the custom map elements.

   main.js

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   
   import "./style.css";
   
   
   import { defineCustomElements as defineMapElements } from "@arcgis/map-components/dist/loader";
   import { defineCustomElements as defineCalciteElements } from "@esri/calcite-components/dist/loader";
   
   defineCalciteElements(window, {
     resourcesUrl: "https://js.arcgis.com/calcite-components/2.5.1/assets"
   });
   
   defineMapElements(window, {
     resourcesUrl: "https://js.arcgis.com/map-components/4.29/assets"
   });
   
   
   
   

Add styles

1. In style.css, import the @arcgis/core light theme.

   style.css

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   @import "https://js.arcgis.com/4.29/@arcgis/core/assets/esri/themes/light/main.css";
   

2. Add CSS styles to make the html, body and arcgis-map elements the full width and height of their parent containers.

   style.css

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   @import "https://js.arcgis.com/4.29/@arcgis/core/assets/esri/themes/light/main.css";
   
   html,
   body,
   arcgis-map {
     height: 100%;
     width: 100%;
     margin: 0;
     padding: 0;
   }

Add components

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

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   <!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.0" />
       <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>
       </calcite-shell>
   
       <script type="module" src="/main.js"></script>
     </body>
   </html>

2. Next, add the arcgis-map and arcgis-layer-list components.

   index.html

   Expand

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
       <calcite-shell>
         <calcite-navigation slot="header">
           <calcite-navigation-logo slot="logo" />
         </calcite-navigation>
         <arcgis-map item-id="e691172598f04ea8881cd2a4adaa45ba" zoom="4">
           <arcgis-layer-list position="top-right" />
         </arcgis-map>
       </calcite-shell>
   

   Expand

Add a Legend to the LayerList

1. In main.js use document.querySelector() to reference the arcgis-layer-list component and then add an event listener for the component's arcgisLayerListReady event.

   main.js

   Expand

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   document.querySelector("arcgis-layer-list").addEventListener("arcgisLayerListReady", (event) => {
   });
   

   Expand

2. Get a reference to the LayerList component from the event.target object.

   main.js

   Expand

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   document.querySelector("arcgis-layer-list").addEventListener("arcgisLayerListReady", (event) => {
     const arcgisLayerList = event.target;
   });
   

   Expand

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

   main.js

   Expand

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   document.querySelector("arcgis-layer-list").addEventListener("arcgisLayerListReady", (event) => {
     const arcgisLayerList = event.target;
     arcgisLayerList.listItemCreatedFunction = (event) => {
       const { item } = event;
       if (item.layer.type !== "group") {
         item.panel = {
           content: "legend"
         };
       }
     };
   });
   

   Expand

Interacting with the the View, Map, and layers

1. Use document.querySelector() to reference the arcgis-map component and then add an event listener for the arcgis-map component's arcgisViewReadyChange event.

   main.js

   Expand

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   document.querySelector("arcgis-map").addEventListener("arcgisViewReadyChange", (event) => {
   });

2. Create a constant for the map's PortalItem instance.

   main.js

   Expand

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   document.querySelector("arcgis-map").addEventListener("arcgisViewReadyChange", (event) => {
     const { portalItem } = event.target.map;
   });

3. Next, in the calcite-navigation you will dynamically add a heading, description, and thumbnail to your app's UI using the PortalItem. To do so, set calcite-navigation-logo's heading, description, and thumbnail properties to the PortalItem's title, snippet and thumbnailUrl properties.

   main.js

   Expand

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   document.querySelector("arcgis-map").addEventListener("arcgisViewReadyChange", (event) => {
     const { portalItem } = event.target.map;
     const navigationLogo = document.querySelector("calcite-navigation-logo");
     navigationLogo.heading = portalItem.title;
     navigationLogo.description = portalItem.snippet;
     navigationLogo.thumbnail = portalItem.thumbnailUrl;
   });

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

   main.js

   Expand

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   document.querySelector("arcgis-map").addEventListener("arcgisViewReadyChange", (event) => {
     const { portalItem } = event.target.map;
     const navigationLogo = document.querySelector("calcite-navigation-logo");
     navigationLogo.heading = portalItem.title;
     navigationLogo.description = portalItem.snippet;
     navigationLogo.thumbnail = portalItem.thumbnailUrl;
   
     const layer = event.target.map.layers.find((layer) => layer.id === "Accidental_Deaths_8938");
   });

5. Modify the layer's PopupTemplate title.

   main.js

   Expand

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   document.querySelector("arcgis-map").addEventListener("arcgisViewReadyChange", (event) => {
     const { portalItem } = event.target.map;
     const navigationLogo = document.querySelector("calcite-navigation-logo");
     navigationLogo.heading = portalItem.title;
     navigationLogo.description = portalItem.snippet;
     navigationLogo.thumbnail = portalItem.thumbnailUrl;
   
     const layer = event.target.map.layers.find((layer) => layer.id === "Accidental_Deaths_8938");
     layer.popupTemplate.title = "Accidental Deaths";
   });

Run the application

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