Using the SDK in a Vue app

The ArcGIS Maps SDK for JavaScript components are standards-based custom elements, so they can be used directly in Vue templates. The key differences from a vanilla JavaScript application involve Vue’s single-file component syntax and event binding.

Before you start, make sure you are using the latest long-term support (LTS) version of Node.js and npm.

Installation

To use Map components in your Vue project, install the @arcgis/map-components package and its dependencies:

npm install @arcgis/map-components @arcgis/core @esri/calcite-components

yarn add @arcgis/map-components @arcgis/core @esri/calcite-components

pnpm add @arcgis/map-components @arcgis/core @esri/calcite-components

Configure CSS

When using components with npm, the SDK’s component styles and Calcite styles are loaded for you. However, you still need a small amount of app CSS to make the page (and therefore the map component) fill the viewport.

Create or update src/style.css with the following, and import it in the application’s entry file:

html,
body {
  height: 100%;
  margin: 0;
}

Configure Vue custom elements

Configure Vue to recognize the SDK custom elements. If you do not add this setting, Vue can show unresolved component warnings for arcgis-* and calcite-* elements.

Add isCustomElement to vite.config.js:

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";

export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: (tag) => tag.startsWith("arcgis-") || tag.startsWith("calcite-"),
        },
      },
    }),
  ],
});

Add a prefix for each custom element library that your application uses.

Create a Vue component

In a Vue single-file component, import the SDK components you want to use in the <script setup> block. These side-effect imports register the components with the browser’s CustomElementRegistry.

In Vue, use component events to respond when a component is ready or its state changes. In this example, arcgisViewReadyChange runs handleViewReady when the map view is ready. The handler uses event.target to access the Map component and adds the graphic to its graphics collection.

<script setup>
import "@arcgis/map-components/components/arcgis-map";
import "@arcgis/map-components/components/arcgis-zoom";

import Graphic from "@arcgis/core/Graphic.js";
import Point from "@arcgis/core/geometry/Point.js";
import SimpleMarkerSymbol from "@arcgis/core/symbols/SimpleMarkerSymbol.js";

const handleViewReady = (event) => {
  const viewElement = event.target;

  const pointGraphic = new Graphic({
    geometry: new Point({
      longitude: -98.38,
      latitude: 38.34,
    }),
    symbol: new SimpleMarkerSymbol({
      color: "red",
      size: 20,
    }),
  });

  viewElement.graphics.add(pointGraphic);
};
</script>

<template>
  <arcgis-map item-id="02b37471d5d84cacbebcccd785460e94" @arcgisViewReadyChange="handleViewReady">
    <arcgis-zoom slot="top-left"></arcgis-zoom>
  </arcgis-map>
</template>

In your application entry file, import the stylesheet and mount the root component:

import { createApp } from "vue";
import "./style.css";
import App from "./App.vue";

createApp(App).mount("#app");

Your App.vue can render the map component:

<script setup>
import Map from "./components/Map.vue";
</script>

<template>
  <Map />
</template>

See the SDK’s Vue template project for a complete example that shows how to work with Map, Charts, and Calcite components, the core API, OAuth, and a Calcite shell layout.