Introduction to maps (2D)

The Map component is used to display a map and handle user interactions, popups, and the viewpoint.

Creating a map

Maps are created from the Map or WebMap class and displayed using the Map component. To display maps in 3D, use the Scene component.

Create a map from a web map

One way to create a map is to load a web map (for 2D maps) or a web scene (for 3D maps).

Web maps and web scenes are JSON structures that contain settings for a map or a scene. This includes settings for the basemap, layers, layer styling, popups, legends, labels, and more. They are typically created interactively with the ArcGIS Online map viewer or the ArcGIS Online scene viewer. ArcGIS Online or ArcGIS Enterprise stores them as portal items that can be referenced by a unique item ID.

You can load a web map by referencing its item ID in the item-id attribute of the Map component:

<arcgis-map item-id="237b9584339446a0b56317b5962a4971"></arcgis-map>

You can also access web map and web scene properties in JavaScript with the WebMap and WebScene classes. To render a map in JavaScript, set the web map instance to the map property of arcgis-map.

When the WebMap object loads a web map, all of the settings are automatically applied to the Map. For example, the basemap and layers are set, the layer styles are applied, and the popups are defined for each layer.

// import the webmap class
const WebMap = await $arcgis.import("@arcgis/core/WebMap.js");
// get the Map component from HTML
const mapElement = document.querySelector("arcgis-map");
// create the webmap and set it on the Map component
const webMap = new WebMap({
  // Define the web map reference
  portalItem: {
    id: "237b9584339446a0b56317b5962a4971",
    portal: "https://www.arcgis.com", // Default: The ArcGIS Online Portal
  },
});
mapElement.map = webMap;

Create a new map from scratch

The second way to create a map is to start from scratch with a basemap and optionally a collection of layers.

The basemap attribute can be set from a named ID on the Map component in HTML:

<arcgis-map basemap="arcgis/topographic" zoom="4" center="15, 65"></arcgis-map>

Or a new instance of a Map or WebMap class can be created and set on the Map component in JavaScript. Creating a new instance allows layers to load in parallel with the rest of the map’s resources. Additionally, when using a WebMap, this pattern ensures the map property on the component is correctly typed:

<arcgis-map zoom="4" center="15, 65"></arcgis-map>

<script type="module">
  // import the Map class
  const Map = await $arcgis.import("@arcgis/core/Map.js");
  // get the Map component from HTML
  const viewElement = document.querySelector("arcgis-map");

  // create the map and set it on the Map component
  const myMap = new Map({
    basemap: "arcgis/streets",
    layers: additionalLayers, // Optionally, add additional layers collection
  });
  viewElement.map = myMap;
</script>

Working with the Map component

The primary role of the Map component is to display layers, popups, and other components, handle user interactions, and to specify which portion of the world the map should be focused on (i.e. the “extent” of the map).

Set the visible portion of the map

The initial position for the map can be set by setting the center and the zoom or scale attributes when the Map component is created. The position can also be updated after it is initialized by updating the properties programmatically.

<!-- set the zoom and center as attributes on the map component -->
<arcgis-map basemap="arcgis/topographic" zoom="4" center="15, 65"></arcgis-map>

<script type="module">
  const viewElement = document.querySelector("arcgis-map");

  // change the zoom property programmatically
  viewElement.zoom = 10;
</script>

Animate the map to a new position

The goTo method also changes the location of the map but provides the additional option to transition smoothly. This technique is often used to “fly” from one location to another on the surface or to zoom to results of a search.

The goTo method can accept a Geometry, Graphic, or Viewpoint object. Additional options can control the animation.

<arcgis-map item-id="237b9584339446a0b56317b5962a4971"></arcgis-map>

<script type="module">
  const viewElement = document.querySelector("arcgis-map");
  // wait for the view to be ready
  await viewElement.viewOnReady();

  viewElement.goTo(
    // go to point with a custom animation duration
    { center: [-114, 39] },
    { duration: 5000 },
  );
</script>

Interacting with the map

The Map component is also responsible for handling user interaction and displaying popups. The component provides multiple events for user interactions such as mouse clicks, keyboard input, touch screen interactions, joysticks, and other input devices.

When a user clicks on the map, the default behavior is to show any popups that have been pre-configured in your layers. This behavior can also be approximated manually with the following code by listening for the arcgisViewClick event and using the hitTest() method to find features where the user clicked.

viewElement.popupEnabled = false; // Disable the default popup behavior

viewElement.addEventListener("arcgisViewClick", (event) => {
  // Listen for the click event
  viewElement.hitTest(event.detail).then((hitTestResults) => {
    // Search for features where the user clicked
    if (hitTestResults.results) {
      viewElement.openPopup({
        // open a popup to show some of the results
        location: event.detail.mapPoint,
        title: "Hit Test Results",
        content: hitTestResults.results.length + "Features Found",
      });
    }
  });
});

Adding UI components to the Map

The Map is also a container for overlaying components and HTML Elements. The Map contains many named slots for placing components and elements in the view, such as “top-right” or “bottom-left”.

The code snippet below demonstrates adding a component that allows users to search for an address or place.

<arcgis-map item-id="237b9584339446a0b56317b5962a4971">
  <!-- search component will be placed in the top right slot of the map -->
  <arcgis-search slot="top-right"></arcgis-search>
</arcgis-map>