Get started with the map components Vite template or the map components Vue template
Component packages can be incorporated into your project via npm for building scalable applications, and incorporating the components into continuous integration (CI) processes. This pattern is similar to the one used with the @arcgis/core ES modules.
Setup
Begin by installing the component package. In this example, we are using @arcgis/map-components:
npm install @arcgis/map-componentsIn your index.html file, add the <arcgis-map/> component and reference the main.js file:
<body>
<arcgis-map item-id="e691172598f04ea8881cd2a4adaa45ba" />
<script type="module" src="/main.js"></script>
</body>Then, in the main.js file, reference the @arcgis/map-components package in your application and its CSS:
import "@arcgis/core/assets/esri/themes/dark/main.css";
import { defineCustomElements as defineMapElements } from "@arcgis/map-components/dist/loader";Once that's completed, you can now:
- Set properties, e.g. which web map or basemap to use
- Add custom JavaScript logic using the core API library - see the tutorial for easy step-by-step instructions.
In the code snippet below, define and lazy load the map components package and then get a reference to it so that you can add further customizations.
/**
* Define and lazy load the component package.
*/
defineMapElements();
/**
* Use `document.querySelector()` to get a reference to the `arcgis-map` component.
* Add an event listener for the `arcgis-map` component's `viewReadyChange` event.
*/
document
.querySelector("arcgis-map")
.addEventListener("arcgisViewReadyChange", async (event) => {
/**
* Get a reference to the `WebMap`
* from the `event.detail` object.
*/
const { map } = event.detail;
// Add more functionality here.
});The last step will be to compile your application with a framework or module bundler.
Registering components in ESM
Registering components is the process of making them available for use in an application. This can either be done using the lazy loading approach or individually loading each component. The lazy loading approach was covered in the previous section of this page.
Lazy loading components
When lazy loading components, components are loaded and registered once, making them all available for use in your application at runtime.
The define function is used to register components in the browser.
You only need to call this function once for each component package you wish to use.
Each component package must specify the location of its (local or CDN) assets.
This can be done by setting the resources option.
Setting the asset path for one component package will not affect other component packages, such as Calcite.
Pointing to ArcGIS CDN hosted assets is recommended for performance improvements and reducing the build size of your application.
import { defineCustomElements as defineCalciteElements } from "@esri/calcite-components/dist/loader";
import { defineCustomElements as defineMapElements } from "@arcgis/map-components/dist/loader";
// Point to ArcGIS CDN hosted assets
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",
});Corresponding HTML:
<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>Individually loading components
In this approach, you manually load and initialize each component in your application before using them. This allows the application framework's build tool to tree shake, including only those components that are actually used in your application. You only need to set the asset path once for all the components which had their local assets copied to the application build folder during the build process. Using CDN hosted assets is not recommended in this case if two or more component packages since setting the asset path will affect all component packages.
// Set the asset path for all the components (i.e., map and calcite components)
// This also could've been done using setAssetPath from "@esri/calcite-components/dist/components";
import { setAssetPath } from "@arcgis/map-components/dist/components";
// Use local assets and configure the asset path to your desired directory
setAssetPath(`${location.origin}${location.pathname}assets`);
// Individually import each component you wish to use
import "@arcgis/map-components/dist/components/arcgis-map";
import "@esri/calcite-components/dist/components/calcite-shell";Configure CSS
Begin by choosing a light or dark theme for the map components package and then include the corresponding CSS files in your application. The best practice is to use stylesheets from the ArcGIS CDN:
@import "https://js.arcgis.com/4.29/@arcgis/core/assets/esri/themes/dark/main.css";
@import "https://js.arcgis.com/calcite-components/2.5.1/calcite.css";However, you can also use local copies of the stylesheets if you prefer:
@import "@arcgis/core/assets/esri/themes/dark/main.css";
@import "@esri/calcite-components/dist/calcite/calcite.css";The pattern for specifying this @import url path is dependent on your framework or module bundler. MDN provides more information on the various patterns for using @import.