Core Maps

When to use: Activate this skill whenever the user creates a 2D map or 3D scene, picks a basemap, controls the view (center/zoom/camera), or asks whether to use Map Components or the Core API.

Overview

A map in the SDK has two parts: a Map (the data model — basemap, layers, ground) and a view that renders it — MapView for 2D or SceneView for 3D.

• Problem it solves: getting a correct, performant map or scene on screen with the right API choice.
• Who it serves: any web developer starting an ArcGIS app.
• Pattern it teaches: model/view separation, and Map-Components-first with Core API as the escape hatch.
• What it does NOT cover: adding data layers (see arcgis-layers), widgets (see arcgis-widgets-ui).

Quick Start

import "@arcgis/map-components/components/arcgis-map";
// <arcgis-map basemap="arcgis/topographic" center="-74.08,4.6" zoom="11"></arcgis-map>
const mapEl = document.querySelector("arcgis-map")!;
await mapEl.viewOnReady(); // the event carries no detail: read the view from the element
console.log("ready", mapEl.view.zoom);

Decision Tree

1. Starting a new project or embedding a map quickly?
   • Yes → Map Components (<arcgis-map> / <arcgis-scene>) — less boilerplate, declarative.
   • No → continue.
2. Do you need fine-grained programmatic control of the view lifecycle, or a non-DOM context?
   • Yes → Core API (new MapView(...) / new SceneView(...)).
   • No → Map Components.

Default: Map Components, unless you have a concrete reason for the Core API.

Import Patterns

Direct ESM (recommended for npm/Vite/Webpack)

import Map from "@arcgis/core/Map.js";
import MapView from "@arcgis/core/views/MapView.js";

Dynamic Imports (CDN)

const Map = await $arcgis.import("@arcgis/core/Map.js");

Map Components (recommended for new projects)

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

Key Concepts

Concept 1: Map vs View

The Map holds basemap, ground, and layers. The view (MapView/SceneView) binds that model to a DOM container and handles rendering, navigation, and events. One Map can feed multiple views.

Concept 2: Basemap identifiers

Pass a basemap style string such as "arcgis/topographic", "arcgis/imagery", or "arcgis/navigation". These resolve through the basemap styles service and require an API key set on esriConfig.apiKey.

Concept 3: View readiness

Never use the view before it is ready. With the Core API, await view.when(). With Map Components, await el.viewOnReady() or listen for arcgisViewReadyChange and read el.view (or event.target.view): in 5.1.27 the event's detail is null, so event.detail.view throws. el.view already exists before that (an object with ready === false), so "is it defined?" is not a readiness check. A view whose container has no height, or whose basemap cannot load, never becomes ready (measured: when() still pending after 10–30 s).

Common Pitfalls (Top 3)

Pitfall 1: Reading the view from the event detail

// ❌ Anti-pattern
el.addEventListener("arcgisViewReadyChange", (e) => {
  console.log((e as CustomEvent).detail.view.zoom);
});

// ✅ Correct
el.addEventListener("arcgisViewReadyChange", () => {
  console.log(el.view.zoom);
});
// or: await el.viewOnReady(); console.log(el.view.zoom);

Impact: measured with 5.1.27: detail is null, the handler throws "Cannot read properties of null (reading 'view')" and nothing after it runs. The cast to CustomEvent is what hides it from TypeScript.

Pitfall 2: Forgetting the API key for basemap styles

// ❌ Anti-pattern
const map = new Map({ basemap: "arcgis/topographic" }); // no esriConfig.apiKey

// ✅ Correct
import esriConfig from "@arcgis/core/config.js";
esriConfig.apiKey = import.meta.env.VITE_ARCGIS_API_KEY as string;
const map = new Map({ basemap: "arcgis/topographic" });

Impact: measured: the style request answers 401, the basemap stays in loading and view.when() does not resolve: everything waiting on the view waits forever. For a keyless demo, basemap: "osm" loads.

Pitfall 3: Using SceneView options on a MapView

// ❌ Anti-pattern
const view = new MapView({ container: "viewDiv", map, camera: { tilt: 65 } });

// ✅ Correct
const view = new SceneView({ container: "viewDiv", map, camera: { tilt: 65 } });

Impact: MapView has no camera in its typings, so typed code fails to compile; untyped code runs and the tilt is ignored (measured: the view is ready, flat, at the given zoom).

When to Read references/

Related Skills

• arcgis-starter-app — scaffold the project first
• arcgis-layers — add data to the map
• arcgis-widgets-ui — add UI components

Reference Samples

• intro-mapview
• intro-sceneview
• intro-map-components

Changelog

• 0.2.0 (2026-10-27): SDK 5.1. The Quick Start threw: arcgisViewReadyChange has a null detail, so event.detail.view fails (measured); now viewOnReady() / el.view. No API key → 401 and a view that never becomes ready (not just a grey canvas); a zero-height container also never becomes ready; swapped center lands in Antarctica, not off Africa. Run in tests/runtime/casos/arcgis-core-maps.ts.
• 0.1.0 (2026-05-31): Initial release.