Get started - components (beta)

There are two main ways to use the components:

Using the CDN via an HTML script tag.
Using NPM to install the @arcgis/map-components package in a JavaScript application framework.

Web components via CDN

To access the @arcgis/map-components package via the CDN, simply reference it and its dependencies. The snippet below demonstrates how to reference the CDN for the map components, the ArcGIS Maps for JavaScript API library and CSS. This approach is suitable for demos, testing, bug reporting, or simple applications.

Expand
Use dark colors for code blocksCopy
  <!-- Load Map Components from CDN-->
  <link rel="stylesheet" href="https://js.arcgis.com/4.28/esri/themes/light/main.css">
  <script src="https://js.arcgis.com/4.28/"></script>
  <script type="module" src="https://js.arcgis.com/map-components/4.28/arcgis-map-components.esm.js"></script>
Expand
TutorialComponent reference

Using map components is as simple as adding an <arcgis-map/> tag to your HTML and assigning it an item-id, which references the ID of a WebMap from ArcGIS Online or ArcGIS Enterprise portal. See the tutorial for easy step-by-step instructions.

Use dark colors for code blocksCopy
<arcgis-map item-id="05e015c5f0314db9a487a9b46cb37eca" />

Once that's completed, now you can:

set properties, e.g. the basemap, center and zoom
add custom JavaScript logic using the API library - see the tutorial for easy step-by-step instructions.

Use dark colors for code blocksCopy
document.querySelector("arcgis-map").addEventListener("viewReady", async (event) => {
  const view = event.detail.view;
  const map = view.map;
});

Web components via NPM

If you are using an application framework like React, Angular, or Vue, you can incorporate the component packages via NPM into your project. This is similar to the patterns used for the SDK's ES modules. This approach is suitable for building scalable applications, and incorporating the components into continuous integration (CI) processes.

First, install the component package. In this example, we are using @arcgis/map-components:

Use dark colors for code blocksCopy
npm install @arcgis/map-components

In your index.html add the map component element and reference the main.js file:

index.html

Use dark colors for code blocksCopy
<body>
   <arcgis-map item-id="e691172598f04ea8881cd2a4adaa45ba" />
   <script type="module" src="/main.js"></script>
</body>

Then, create the main.js file, reference the map components package in your application and the CSS:

main.js

Use dark colors for code blocksCopy
import "@arcgis/core/assets/esri/themes/dark/main.css";
import { defineCustomElements as defineMapElements } from "@arcgis/map-components/dist/loader";

Once that's completed, now you can:

set properties, e.g. which web map or basemap to use
add custom JavaScript logic using the API library - see the tutorial for easy step-by-step instructions.

In the code snippet below, define and lazy load a custom map element. And, then get a reference to it so that you can add further customizations.

main.js

Use dark colors for code blocksCopy

/**
 * Use the Map Components to define and lazy load the map element.
 */
defineMapElements();

/**
 * Use `document.querySelector()` to get a reference to the `arcgis-map` component.
 * Add an event listener for the `arcgis-map` component's `viewReady` event.
 */
document
  .querySelector("arcgis-map")
  .addEventListener("viewReady", async (event) => {
    /**
     * Get a reference to the ArcGIS Maps SDK for JavaScript `MapView`
     * from the `event.detail` object.
     */
    const view = event.detail.view;
    // Add more functionality here.
  });

The last step will be to compile your application with a framework or module bundler.

Web component dependencies

When building applications, it's important to understand the dependencies for the component packages. For more information about dependency versioning, see the npm CLI documentation.

Peer dependencies

The functionality of the component packages depends on compatible versions of @arcgis/core and @esri/calcite-components, which are defined in a component's package.json as peerDependencies. These peer dependencies are installed by default when using npm:

@arcgis/core: ~4.28.0
@esri/calcite-components: ^1.9.2

Dependencies

These packages are required for the component packages to work correctly and they are automatically installed when using npm. They are defined in the project's package.json as dependencies:

@stencil/core: 2.22.3.

Versioning

You may have your own requirements to use a specific version of these dependencies. In that case, you will need to install the dependencies manually and respect the following versioning rules:

@arcgis/core - only use a compatible patch version.
@esri/calcite-components - only use any compatible minor version.
@stencil/core - must use the same version.