Get started

The ArcGIS Maps SDK for JavaScript includes a core API and a set of web component libraries that encapsulate the API's functionality into ready-to-use UI elements. Depending on your application's needs, you can use components from any of the four component libraries: Map, Coding, Charts, and Embeddable. The SDK also integrates with Esri's Calcite Design System for a consistent and accessible user experience. Calcite provides a complete UI toolkit, including a rich library of web components, icons, color schemes, and design patterns.

The starting point for using the JavaScript Maps SDK depends on your goals and requirements. If you want to build a vanilla JavaScript and HTML app without installing local packages, you can use the CDN. For more structured or scalable web applications, especially those using a frontend framework or build tool, consider installing the SDK with npm.

CDN

The JavaScript Maps SDK can be easily integrated into a vanilla JavaScript and HTML application using the ArcGIS CDN. This approach leverages optimized cloud caching, removing the need for local builds and making it easier to stay up to date with the latest SDK versions.

Setup

To get started, include all the necessary library scripts in the order shown below to the <head> section of a basic HTML file.

index.html
Use dark colors for code blocksCopy
<!-- Load Calcite Design System -->
<script type="module" src="https://js.arcgis.com/calcite-components/3.3.3/calcite.esm.js"></script>

<!-- Load the JavaScript Maps SDK core API -->
<script src="https://js.arcgis.com/4.34/"></script>

<!-- Load the JavaScript Maps SDK Map components or other component packages -->
<script type="module" src="https://js.arcgis.com/4.34/map-components/"></script>

Attention

If haven't migrated to the SDK's components yet and are still using widgets, consider migrating to components today. Any use of widgets and/or programmatically initializing a new MapView/SceneView will still require the core API stylesheet:

index.html
Use dark colors for code blocksCopy
<link rel="stylesheet" href="https://js.arcgis.com/4.34/esri/themes/light/main.css" />

Configure CSS

Add custom CSS so that components will be visible in your application. This needs to be the last item in the <head> section, after importing the ArcGIS libraries from the CDN:

index.html
Use dark colors for code blocksCopy
<style>
  html,
  body {
    height: 100%;
    margin: 0;
  }
</style>

Choose a light or dark theme through Calcite modes.

Create a layout

Now, add the 2D Map component (or 3D Scene component) to the <body> of your HTML and assign it an optional item-id if using a WebMap from ArcGIS Online or ArcGIS Enterprise portal. Use the Map or Scene's slots to position other components, like Zoom, within the map or scene.

For more information, see Programming Patterns, the Display a web map tutorial, and the Create a 2D map sample.

index.html
Use dark colors for code blocksCopy
<!-- There is no need to programmatically set the basemap, extent or zoom -->
<!-- All this information comes from the WebMap -->
<arcgis-map item-id="02b37471d5d84cacbebcccd785460e94">
  <arcgis-zoom slot="top-left"></arcgis-zoom>
</arcgis-map>

Next, you can set properties, watch for changes, and add custom JavaScript logic using the core API in a <script> tag below the <body> of your HTML. Ensure the script is marked as <script type="module">.

Modules from the core API can be loaded via the global $arcgis.import() method. The method accepts a module path or an array of module paths, and returns a promise that resolves with the requested modules. You can find the module identifier at the top of each API reference page. See Graphic for reference.

The code below will wait for the map's View to be ready. Once the View is ready, more functionality can be added.

index.html
Use dark colors for code blocksCopy
<script type="module">
  const Graphic = await $arcgis.import("@arcgis/core/Graphic.js");
  const viewElement = document.querySelector("arcgis-map");
  // Wait for the view to be ready before adding additional functionality
  await viewElement.viewOnReady();

  // ...

  // Create a graphic and add the geometry and symbol to it
  const pointGraphic = new Graphic({
    geometry: point, // A point geometry
    symbol: markerSymbol // A symbol for drawing the point
  })
  viewElement.graphics.add(pointGraphic);
</script>

npm

For modern build tools, such as Vite, or JavaScript frameworks like React, Angular or Vue, it's recommended to install the JavaScript Maps SDK via a package manager such as npm. Consult your build tool or framework's documentation for recommendations on events, properties, and web components. Any exceptions are outlined in this guide.

Setup

Make sure you are using the latest long-term support (LTS) version of node.js and npm. Next, scaffold your project using your preferred build tool or framework's recommended templates. Vite, a client-side build tool that includes a module bundler and a local web server, has many template projects to choose from. In this guide, we'll use the Vite + vanilla JavaScript template as a starting point.

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

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

Configure CSS

Starting with the 4.34 release, CSS is loaded automatically when using components with npm, including stylesheets for both the components and Calcite.

index.css
Use dark colors for code blocksCopy
html,
body {
  height: 100%;
  margin: 0;
}

Attention

index.css
Use dark colors for code blocksCopy
@import "@arcgis/core/assets/esri/themes/light/main.css";

Create a layout

In the index.html file of your Vite + vanilla JavaScript starter project, add the 2D Map component (or 3D Scene component) and reference the main.js file. Each component is a custom element that you can add to your application using an HTML tag, similar to other HTML elements such as a <div></div>.

index.html
Use dark colors for code blocksCopy
<body>
  <arcgis-map item-id="02b37471d5d84cacbebcccd785460e94">
    <arcgis-zoom slot="top-left"></arcgis-zoom>
  </arcgis-map>
  <script type="module" src="./main.js"></script>
</body>

Import components

Finally, in the main.js JavaScript file individually import the SDK's components that you need, such as the Map component.

This registers the component with the browser's CustomElementRegistry. When the browser encounters the custom element's HTML tag, such as <arcgis-map></arcgis-map>, it creates an instance of the element, adds it to the DOM and enables its functionality.

main.js
Use dark colors for code blocksCopy
import "./index.css";

import "@arcgis/map-components/components/arcgis-map";
import "@arcgis/map-components/components/arcgis-zoom";
import Graphic from "@arcgis/core/Graphic.js";

const viewElement = document.querySelector("arcgis-map");

// Wait for the view to be ready before adding additional functionality
viewElement.addEventListener("arcgisViewReadyChange", () => {
  // ...

  // Create a graphic and add the geometry and symbol to it
  const pointGraphic = new Graphic({
    geometry: point, // A point geometry
    symbol: markerSymbol // A symbol for drawing the point
  });
  viewElement.graphics.add(pointGraphic);
});

TypeScript

TypeScript is a powerful language that offers static type checking to identify errors during development instead of at runtime. This enhances productivity and reduces troubleshooting time. TypeScript definitions are provided when the SDK is installed locally using npm. To compile TypeScript to JavaScript, you must configure the TypeScript compiler by creating a tsconfig.json file. If a tsconfig.json file was created automatically during project installation, review all settings.

When using the core API's TypeScript decorators, such as when building Accessor subclasses or extending base layers, it may be necessary to set the useDefineForClassFields flag to false for backwards compatibility. More information on this flag is available in the TSConfig Reference.

Here is a minimal example of a tsconfig.json:

tsconfig.json
Use dark colors for code blocksCopy
{
  "$schema": "https://json.schemastore.org/tsconfig.json",
  // Array of `.ts` files to compile. You can also use glob patterns such as `"src/**/*"`.
  "include": ["src", "*.ts"],
  "compilerOptions": {
    // When `true`, this allows use of `import` syntax such as `import x from 'xyz'`.
    "esModuleInterop": true,
    // Specify library type definitions to be included in the compilation.
    "lib": ["DOM", "DOM.Iterable", "ES2023"],
    // The module system to use for compilation.
    // Here, ES modules are targeted (ESNext) to enable top-level await and dynamic imports.
    "module": "ES2022",
    // Respects package.json's "exports" conditions.
    "moduleResolution": "Bundler",
    // Allow importing from JSON files
    "resolveJsonModule": true,
    // This sets the output at the minimum version of JavaScript features that will be supported.
    "target": "ES2023",
    // Improves performance by checking only the .ts files you write
    // rather than the .d.ts files from the libraries you are using.
    "skipLibCheck": true,
  },
}

See SDK's TypeScript template project for a complete example that shows how to work with both components and the core API. It uses the Vite + TypeScript template as a starting point and mirrors the JavaScript sample but is written in TypeScript(.ts) to provide type safety.

React

Using the SDK with JSX in a React 19 project is similar to using it in a vanilla JavaScript and HTML project. The key differences involve JSX syntax and React programming patterns. When working in a framework like React, it's generally recommended to use events rather than direct method calls for better integration with the component lifecycle.

index.jsx
Use dark colors for code blocksCopy
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import "./index.css";

import "@arcgis/map-components/components/arcgis-map";
import "@arcgis/map-components/components/arcgis-zoom";
import Graphic from "@arcgis/core/Graphic.js";

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

    // ...

    // Create a graphic and add the geometry and symbol to it
    const pointGraphic = new Graphic({
      geometry: point, // A point geometry
      symbol: markerSymbol // A symbol for drawing the point
    });

    viewElement.graphics.add(pointGraphic);
  };

  return (
    <arcgis-map item-id="02b37471d5d84cacbebcccd785460e94" onarcgisViewReadyChange={handleViewReady}>
      <arcgis-zoom slot="top-left" />
    </arcgis-map>
  );
}

const root = createRoot(document.getElementById("root"));
root.render(
  <StrictMode>
    <App />
  </StrictMode>,
);

See the SDK's React template project for a complete example that shows how to work with both components and the core API.

If you already have TypeScript set up in your React 19 project and would like to use web components with TSX, you can do so with one line of code at the top of your main .tsx file or Vite's vite-env.d.ts file. This will provide increased type safety for event listeners, properties and more.

vite.env.d.ts
Use dark colors for code blocksCopy
/// <reference types="@arcgis/map-components/types/react" />

If you use React 18, check out the @arcgis/map-components-react package.

Angular

The SDK's web components are non-Angular elements. For them to be used inside of Angular components, you'll need to configure Angular's CUSTOM_ELEMENTS_SCHEMA.

app.ts
Use dark colors for code blocksCopy
import { Component, CUSTOM_ELEMENTS_SCHEMA, OnInit } from "@angular/core";

import "@arcgis/map-components/components/arcgis-map";

@Component({
  selector: "app-root",
  standalone: true,
  imports: [RouterOutlet],
  templateUrl: "./app.html",
  schemas: [CUSTOM_ELEMENTS_SCHEMA], // Set the schema here
})
export class AppComponent {
  arcgisViewReadyChange(event: CustomEvent) {
    // The view is ready, add additional functionality below
  }
}

Currently in Angular, the map component's CSS is bundled but not automatically loaded in production builds. The CSS should be imported explicitly in the project's root stylesheet. Add the following to src/styles.css:

styles.css
Use dark colors for code blocksCopy
@import "@esri/calcite-components/calcite/calcite.css";
@import "@arcgis/map-components/main.css";
@import "@arcgis/coding-components/main.css";

For HTML IntelliSense in app.html, visit the IntelliSense documentation. When working in a framework like Angular, it's generally recommended to use the events from the SDK's components rather than direct method calls for better integration with the component and Angular lifecycle.

app.html
Use dark colors for code blocksCopy
<arcgis-map
  item-id="45b77c869ba14b6dbc2de43a817304a6"
  (arcgisViewReadyChange)="arcgisViewReadyChange($event)"
>
  <arcgis-zoom slot="top-left"></arcgis-zoom>
</arcgis-map>

Refer to the SDK's Angular template project for a complete example that shows how to work with both components and the core API and set up CSS.

Access tokens

Access tokens are required to access ArcGIS services, such as basemaps, geocoding, and routing. Visit your portal and create an access token with custom privileges and referrers for your specific needs. Include your access token in the tutorials and samples when required in the instructions. You can use a global API key, as well as more fine-grained API keys on specific classes.

Additional information

Please refer to these additional links for further information: