Get started | ArcGIS Maps SDK for JavaScript

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 six component libraries: Map, Charts, AI (beta), Embeddable, Coding and Common components.

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 best way to start with the JavaScript Maps SDK depends on your goals and requirements:

Build with vanilla JavaScript and HTML app without installing local packages — see Create an app with the ArcGIS CDN
Create a project from a template — see Create an app with npm.

Prerequisites

To use the ArcGIS Maps SDK for JavaScript to access content , services , or an organization, you need an ArcGIS Location Platform account , ArcGIS Online account , or ArcGIS Enterprise account . The type of account, user type, and role you need depends on the resources you need to access and the operations you wish to undertake.

If you do not have an account, select one of the options below:

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.

See the Create an API key tutorial for more information.

Create an app with the ArcGIS CDN

This section covers manual setup. If you prefer a starter project, use the CDN template.

The JavaScript Maps SDK can be integrated into a vanilla JavaScript and HTML application using the ArcGIS CDN. This approach leverages optimized cloud caching, removes local build requirements, and makes it easier to stay up to date with the latest SDK versions.

Setup

To get started, include the ArcGIS CDN <script> in the <head> section of a basic HTML file. This is the main entry point for adding the core API library, all component packages, and the CSS to your application. The CDN is available in MAJOR.MINOR format, and patch-specific versions are available in MAJOR.MINOR.PATCH format. See the Release Notes for the latest patch version.

index.html

<!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
<script type="module" src="https://js.arcgis.com/5.0/"></script>

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

<style>
  html,
  body {
    height: 100%;
    margin: 0;
  }
</style>

Choose a light or dark theme through Calcite modes.

Attention

If you haven’t migrated to the SDK’s components yet and are still using widgets, consider migrating to components today. If you use widgets and/or programmatically initialize a MapView or SceneView, you must still manually include the core API CSS stylesheet:

index.html

<!-- Load the CSS for the widgets -->
<link rel="stylesheet" href="https://js.arcgis.com/5.0/esri/themes/light/main.css" />

Create a layout

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 or WebScene 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.

index.html

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

Alternatively, you can set the basemap, center and zoom attributes manually on the Map or Scene components if you’re not using a WebMap or WebScene.

Add core API modules

You can set properties, watch for changes, and add custom JavaScript logic using the core API in a <script> tag at the bottom but within 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

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

Create an app with npm

When working with local builds, you can install the JavaScript Maps SDK manually, use the @arcgis/create CLI tool, or visit the Esri/jsapi-resources GitHub repository to download application templates. The repository contains a variety of templates for quickly scaffolding your first application. These templates demonstrate working with the SDK’s core API, components, OAuth, and Calcite.

Manually install

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

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

For additional configuration information on framework and tooling setup, see the following guide topics:

Use @arcgis/create

The @arcgis/create CLI tool can be used with either npm init or npx. Before you start, make sure you are using the latest long-term support (LTS) version of Node.js and npm.

Run npm init @arcgis or npx @arcgis/create to quickly scaffold a new mapping application.

When using npx, you can also pass CLI options to skip all interactive prompts:

# CLI options:
#   -n, --name <name>          Name of the project
#   -t, --template <template>  Template to use

# Vite app template with SDK integration
npx @arcgis/create -n my-arcgis-app -t vite

Other templates include:

# React app template with SDK integration
npx @arcgis/create -n my-arcgis-app -t react

Additional information

Please refer to these additional links for further information:

PreviousKey features NextTutorials