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

  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.

    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.

    1
    npm list @esri/calcite-components
  3. Start the Vite development server.

    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 through the remaining steps.

  5. Import the the arcgis-layer-list and arcgis-map components from the @arcgis/map-components package in main.js.

    main.js
    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
    40
    41
    42
    43
    44
    45
    46
    47
    48
    
    import "./style.css";
    
    import "@arcgis/map-components/dist/components/arcgis-layer-list";
    import "@arcgis/map-components/dist/components/arcgis-map";
    
    
  6. Import the calcite-navigation, calcite-navigation-logo, and calcite-shell components from the @esri/calcite-components package in main.js.

    main.js
    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
    40
    41
    42
    43
    44
    45
    46
    47
    48
    
    import "./style.css";
    
    import "@arcgis/map-components/dist/components/arcgis-layer-list";
    import "@arcgis/map-components/dist/components/arcgis-map";
    
    import "@esri/calcite-components/dist/components/calcite-navigation";
    import "@esri/calcite-components/dist/components/calcite-navigation-logo";
    import "@esri/calcite-components/dist/components/calcite-shell";
    
    
  7. Set the asset path for the Calcite Components in main.js. 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 when using setAssetPath().

    main.js
    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
    40
    41
    42
    43
    44
    45
    46
    47
    48
    
    import "./style.css";
    
    import "@arcgis/map-components/dist/components/arcgis-layer-list";
    import "@arcgis/map-components/dist/components/arcgis-map";
    
    import "@esri/calcite-components/dist/components/calcite-navigation";
    import "@esri/calcite-components/dist/components/calcite-navigation-logo";
    import "@esri/calcite-components/dist/components/calcite-shell";
    
    // Import the setAssetPath function from calcite-components
    // This function allows you to set the path to the calcite components assets
    import { setAssetPath } from "@esri/calcite-components/dist/components";
    // CDN hosted calcite components assets
    setAssetPath("https://js.arcgis.com/calcite-components/2.13.2/assets");
    

Add styles

  1. In style.css, import the @arcgis/core light theme and @esri/calcite-components CSS stylesheets.

    style.css
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    
    @import "https://js.arcgis.com/4.31/@arcgis/core/assets/esri/themes/light/main.css";
    @import "https://js.arcgis.com/calcite-components/2.13.2/calcite.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
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    
    @import "https://js.arcgis.com/4.31/@arcgis/core/assets/esri/themes/light/main.css";
    @import "https://js.arcgis.com/calcite-components/2.13.2/calcite.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
    Expand
    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
      <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>
    
    Expand
  2. Next, add the arcgis-map and arcgis-layer-list components.

    index.html
    Expand
    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
        <calcite-shell>
          <calcite-navigation slot="header">
            <calcite-navigation-logo slot="logo"></calcite-navigation-logo>
          </calcite-navigation>
    
          <arcgis-map item-id="e691172598f04ea8881cd2a4adaa45ba" zoom="4">
            <arcgis-layer-list position="top-right"></arcgis-layer-list>
          </arcgis-map>
    
        </calcite-shell>
    
    Expand

Add a Legend to the LayerList

  1. In main.js use document.querySelector() to get a reference for the arcgis-layer-list component.

    main.js
    Expand
    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
    40
    41
    42
    43
    44
    45
    46
    47
    48
    // Get a reference to the arcgis-layer-list element
    const arcgisLayerList = document.querySelector("arcgis-layer-list");
    
    
    Expand
  2. Add a listItemCreatedFunction to the LayerList. This function will add a Legend in the ListItemPanel for all layers except group layers.

    main.js
    Expand
    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
    40
    41
    42
    43
    44
    45
    46
    47
    48
    // 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"
        };
      }
    };
    
    Expand

Interacting with the the View, Map, and layers

  1. Use document.querySelector() to get a reference for the arcgis-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
    Expand
    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
    40
    41
    42
    43
    44
    45
    46
    47
    48
    // Get a reference to the arcgis-map element
    const arcgisMap = document.querySelector("arcgis-map");
    
    // Since we are using property values from the map component,
    // we use the arcgisViewReadyChange event to determine when the map is ready.
    arcgisMap.addEventListener("arcgisViewReadyChange", () => {
    
    });
  2. Create a variable for the map's PortalItem instance.

    main.js
    Expand
    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
    40
    41
    42
    43
    44
    45
    46
    47
    48
    // Since we are using property values from the map component,
    // we use the arcgisViewReadyChange event to determine when the map is ready.
    arcgisMap.addEventListener("arcgisViewReadyChange", () => {
    
      const { portalItem } = arcgisMap.map;
    
    });
  3. Next, 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
    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
    40
    41
    42
    43
    44
    45
    46
    47
    48
    // Since we are using property values from the map component,
    // we use the arcgisViewReadyChange event to determine when the map is ready.
    arcgisMap.addEventListener("arcgisViewReadyChange", () => {
    
      const { portalItem } = arcgisMap.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
    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
    40
    41
    42
    43
    44
    45
    46
    47
    48
      const layer = arcgisMap.map.layers.find((layer) => layer.id === "Accidental_Deaths_8938");
    
    
    Expand
  5. Modify the layer's PopupTemplate title.

    main.js
    Expand
    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
    40
    41
    42
    43
    44
    45
    46
    47
    48
      const layer = arcgisMap.map.layers.find((layer) => layer.id === "Accidental_Deaths_8938");
    
      layer.popupTemplate.title = "Accidental Deaths";
    
    Expand

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.

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.

The developer dashboard has moved

You can no longer sign into this site. Go to your ArcGIS portal or the ArcGIS Location Platform dashboard to perform management tasks.

Your ArcGIS portal

Create, manage, and access API keys and OAuth 2.0 developer credentials, hosted layers, and data services.

Your ArcGIS Location Platform dashboard

Manage billing, monitor service usage, and access additional resources.

Learn more about these changes in the What's new in Esri Developers June 2024 blog post.

Close