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.
Code examplesCheck out ArcGIS Maps SDK for JavaScript core API and Map components template projects to get started quickly:
CDNThe 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.
SetupTo get started, include all the necessary library scripts and CSS link tags in the order shown below to the <head> section of a basic HTML file.
index.html
Use dark colors for code blocks Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
<!-- Load Calcite Design System -->
<script
type="module"
src="https://js.arcgis.com/calcite-components/3.2.1/calcite.esm.js"></script>
<!-- Load the JavaScript Maps SDK core API -->
<link rel="stylesheet" href="https://js.arcgis.com/4.33/esri/themes/light/main.css" />
<script src="https://js.arcgis.com/4.33/"></script>
<!-- Load the JavaScript Maps SDK Map components or other component packages -->
<script
type="module"
src="https://js.arcgis.com/4.33/map-components/"></script>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 stylesheets and libraries from the CDN:
Choose a light or dark theme by including your preferred CSS stylesheets and Calcite modes.
index.html
Use dark colors for code blocks Copy
1
2
3
4
5
6
7
<style>
html,
body {
height: 100%;
margin: 0;
}
</style>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.
index.html
Use dark colors for code blocks Copy
1
2
3
4
5
<!-- 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 position="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 $arcgis.import() method is exclusive to the ArcGIS Maps SDK for JavaScript when used via CDN and is not a native feature of the standard ES module system.
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 blocks Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<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>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.
SetupMake 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 blocks Copy
1
npm install @arcgis/map-componentsCSS stylesheets can be loaded from CDN or locally from /node_modules. Using the CDN will provide the smallest on-disk build size because the files will be loaded at runtime and not bundled locally.
Choose a light or dark theme by including your preferred CSS stylesheets and Calcite modes. The SDK uses Calcite for the styling of its components. You can also add your own custom UI using Calcite.
CDN CDN /node_modules index.css
Use dark colors for code blocks Copy
1
2
3
4
5
6
7
8
9
10
11
/* Include calcite, core API and SDK component CSS */
@import "https://js.arcgis.com/calcite-components/3.2.1/calcite.css";
@import "https://js.arcgis.com/4.33/@arcgis/core/assets/esri/themes/light/main.css";
@import "https://js.arcgis.com/4.33/map-components/main.css";
#root,
html,
body {
height: 100%;
margin: 0;
}The pattern for specifying the @import url path is dependent on your framework or module bundler. You can find examples of CSS configurations for a variety of frameworks and module bundlers in the jsapi-resources GitHub repository. MDN also provides more information on the various patterns for using @import.
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 blocks Copy
1
2
3
4
5
6
<body>
<arcgis-map item-id="02b37471d5d84cacbebcccd785460e94">
<arcgis-zoom position="top-left"></arcgis-zoom>
</arcgis-map>
<script type="module" src="./main.js"></script>
</body>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 blocks Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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 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 blocks Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
"$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,
},
}Visit TypeScript's Get Started guide to learn more.
ReactUsing 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 blocks Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import "@arcgis/map-components/dist/components/arcgis-map";
import "./index.css";
const root = createRoot(document.getElementById("root"));
root.render(
<StrictMode>
<arcgis-map
itemId="45b77c869ba14b6dbc2de43a817304a6"
// All events for the SDK's components in React will start with `onarcgis`
onarcgisViewReadyChange={(event) => {
// The view is ready, add additional functionality below
}}>
></arcgis-map>
</StrictMode>,
);See the 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 blocks Copy
1
/// <reference types="@arcgis/map-components/types/react" />If you use React 18, check out the @arcgis/map-components-react package.
AngularThe 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 blocks Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
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.component.html",
styleUrl: "./app.component.css",
schemas: [CUSTOM_ELEMENTS_SCHEMA], // Set the schema here
})
export class AppComponent {
arcgisViewReadyChange(event: CustomEvent) {
// The view is ready, add additional functionality below
}
}For HTML IntelliSense in app.html, visit the IntelliSense documentation. When working in a framework like Angular, it's generally recommended to use events rather than direct method calls for better integration with the component lifecycle.
app.html
Use dark colors for code blocks Copy
1
2
3
4
5
6
<arcgis-map
item-id="45b77c869ba14b6dbc2de43a817304a6"
(arcgisViewReadyChange)="arcgisViewReadyChange($event)"
>
<arcgis-zoom position="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 NoteIf your application is using only ArcGIS Identities for authentication you can skip this section. See the security and authentication documentation for more information.
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 informationPlease refer to these additional links for further information:
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4