Map

// Load the Map and MapView modules
require(["esri/Map", "esri/views/MapView"], function(Map, MapView) {
  // Create a Map instance
  const myMap = new Map({
    basemap: "streets-vector"
  });
  // Create a MapView instance (for 2D viewing) and reference the map instance
  const view = new MapView({
    map: myMap
  });
});

Property Overview

Property Details

allLayers Collection<Layer>readonly

A flattened collection of all layers in the map. This collection contains basemap layers, operational layers and ground layers. Group Layers and their children layers are also part of this collection. Reference layers in the basemap will always be included at the end of the collection.

Layers should not be added directly to this collection. They must only be added via the layers, basemap or ground properties.

To access a flattened collection of tables, use the allTables property instead.

Example

// Find a layer with title "US Counties"
const foundLayer = map.allLayers.find(function(layer) {
 return layer.title === "US Counties";
});

// Create a filtered collection of the non-group layers
const nonGroupLayers = map.allLayers.filter(function(layer) {
 return !foundLayer.layers;
});

// Listen for any layer being added or removed in the Map
map.allLayers.on("change", function(event) {
 console.log("Layer added: ", event.added);
 console.log("Layer removed: ", event.removed);
 console.log("Layer moved: ", event.moved);
});

allTables Collection<Layer>readonly

Since: ArcGIS Maps SDK for JavaScript 4.17

A flattened collection of tables anywhere in the map's hierarchy. This will contain individual tables within the map's tables, in addition to any group layer tables. In order for the table(s) to be recognized as such, the FeatureLayer property must return true.

Currently, only feature layer tables are recognized.

To access spatial layers, use the allLayers property instead.

Example

// A feature layer where isTable = true.
const foundTable = map.allTables.find(function(table) {
  // Find a table with title "US Counties"
  return table.title === "US Counties";
});

basemap Basemapautocast

Autocasts from String|Object

Specifies a basemap for the map. The basemap is a set of tile layers that give geographic context to the MapView or SceneView and the other operational layers in the map.

This value can be an instance of Basemap or one of the strings listed in the table below.

Basemaps for use with API keys

Use of these basemaps requires an ArcGIS Developer subscription. To learn more about API keys, see the API keys section in the ArcGIS Developer documentation.

Value	Source
arcgis-imagery	Imagery Hybrid
arcgis-imagery-standard	Imagery
arcgis-imagery-labels	The reference layer from arcgis-imagery
arcgis-light-gray	Light Gray Canvas
arcgis-dark-gray	Dark Gray Canvas
arcgis-navigation	Navigation
arcgis-navigation-night	Navigation (Night)
arcgis-streets	Streets
arcgis-streets-night	Streets (Night)
arcgis-streets-relief	Streets (with Relief)
arcgis-topographic	Topographic
arcgis-oceans	Oceans
arcgis-human-geography	Human Geograpy Map - added in v.4.25
arcgis-human-geography-dark	Human Geograpy Map Canvas - added in v.4.25
osm-standard	OpenStreetMap
osm-standard-relief	OpenStreetMap (with Relief)
osm-streets	OpenStreetMap (Streets)
osm-streets-relief	OpenStreetMap (Streets with Relief)
osm-light-gray	OpenStreetMap (Light Gray Canvas)
osm-dark-gray	OpenStreetMap (Dark Gray Canvas)
arcgis-terrain	Terrain with Labels
arcgis-community	Community Map
arcgis-charted-territory	Charted Territory Map
arcgis-colored-pencil	Colored Pencil Map
arcgis-nova	Nova Map
arcgis-modern-antique	Modern Antique Map
arcgis-midcentury	Mid-Century Map
arcgis-newspaper	Newspaper Map
arcgis-hillshade-light	The hillshade layer from arcgis-topographic
arcgis-hillshade-dark

For use without an API key

Use of these basemaps requires a valid ArcGIS Online organizational subscription or an ArcGIS Enterprise license.

Value	Source
satellite	World Imagery
hybrid	Hybrid Reference Layer and World Imagery
oceans	World Ocean Reference and World Ocean Base
osm	OpenStreetMapLayer
terrain	World Reference Overlay and World Terrain Base
dark-gray-vector	Dark Gray Canvas
gray-vector	Light Gray Canvas
streets-vector	World Street Map
streets-night-vector	World Street Map (Night)
streets-navigation-vector	World Navigation Map
topo-vector	World Hillshade and World Topographic Map
streets-relief-vector	World Hillshade and World Street Map (with Relief)
topo (deprecated)	This basemap/service is now in Mature Support and is no longer updated. Please use topo-vector instead. World Topo Map
streets (deprecated)	This basemap/service is now in Mature Support and is no longer updated. Please use streets-vector instead. World Street Map
dark-gray (deprecated)	This basemap/service is now in Mature Support and is no longer updated. Please use dark-gray-vector instead. World Dark Gray Reference and World Dark Gray Base
gray (deprecated)	This basemap/service is now in Mature Support and is no longer updated. Please use gray-vector instead. World Light Gray Reference and World Light Gray Base
national-geographic (deprecated)	This basemap/service is now in Mature Support and is no longer updated. Please use the National Geographic Style WebMap instead. NatGeo World Map

Example

// Set the basemap in the constructor
const map = new Map({
  basemap: "hybrid"
});

// Set the basemap after the map instance is created
map.basemap = "topo-vector";

declaredClass Stringreadonly inherited

Since: ArcGIS Maps SDK for JavaScript 4.7

The name of the class. The declared class name is formatted as esri.folder.className.

editableLayers Collection<(FeatureLayer|SceneLayer|SubtypeGroupLayer)>readonly

Since: ArcGIS Maps SDK for JavaScript 4.20

A collection of editable layers. Layers are considered editable if they have editing capabilities, and if the authenticated user has the necessary privileges needed to edit the layers.

See also

• Editor

• Sample - Edit features with the Editor widget

• Sample - Editor widget with configurations

ground Groundautocast

Autocasts from String|Object

Specifies the surface properties for the map. In MapView, this property is used by the ElevationProfile widget when the profile contains an ElevationProfileLineGround. In 3D SceneView, it renders the terrain or topographical variations in the real world on the map's surface with a collection of ElevationLayers.

This value can be an instance of Ground, or one of the following strings:

• world-elevation for a default instance of ground using the Terrain3D Service.
• world-topobathymetry for an instance of ground that combines surface elevation and bathymetry using the TopoBathy3D Service.

The ground may not be set to null or undefined, it is guaranteed to always contain an instance of type Ground. The elevation can be removed from the ground by setting the ground property to a new empty Ground instance or by removing all the ground layers.

See also

• ElevationLayer
• Ground

Examples

// Use the world elevation service
const map = new Map({
  basemap: "topo-vector",
  ground: "world-elevation"
});

// Create a map with the world elevation layer overlaid by a custom elevation layer
const worldElevation = ElevationLayer({
  url: "//elevation3d.arcgis.com/arcgis/rest/services/WorldElevation3D/Terrain3D/ImageServer"
});
const customElevation = ElevationLayer({
  url: "https://my.server.com/arcgis/rest/service/MyElevationService/ImageServer"
});
const map = new Map({
  basemap: "topo-vector",
  ground: new Ground({
   layers: [ worldElevation, customElevation ]
  })
});

layers Collection<Layer>autocast

Autocasts from Layer[]

A collection of operational layers. This property contains the operational layers, such as FeatureLayers, WebTileLayers and GraphicsLayers that may be queried, assigned different renderers, analyzed, etc. It does not include basemaps.

A layer is a collection of one or more features, or graphics, that represent real-world phenomena. Each feature contains a symbol and geographic data that allows it to be rendered on the map as a graphic with spatial context. Features within the layer may also contain data attributes that provide additional information that may be viewed in popup windows and used for rendering the layer.

Layers may be added in the constructor, with the add() or addMany() methods, or directly to the layers collection using add() or addMany().

In 3D, for layers that are rendered on the terrain, the order of the layers also depends on the type of layer. Tiled layers (VectorTileLayer, WebTileLayer, WMTSLayer) are always drawn first in the same order as specified in the layer collection. Dynamic layers (MapImageLayer, ImageryLayer, WMSLayer, and feature based layers with elevation mode on-the-ground) are rendered on top using the order from the layer collection.

A layer may only be added to one parent. Adding the same layer to multiple Maps or GroupLayers is not possible. If you attempt to do so, the layer will automatically be removed from its current parent and placed in the new parent.

let layer = new GraphicsLayer();
// The layer belongs to map1
map1.layers.add(layer);
// The layer now belongs to map2
// and implicitly does: map1.layers.remove(layer)
map2.layers.add(layer);

To access tables from feature layers, use the tables property in either Map or WebMap classes.

Example

// Add layers in the constructor of Map using an array
let fl = new FeatureLayer(url);
let gl = new GraphicsLayer();
let map = new Map({
  layers: [fl, gl]
});

// Add layers using add()
map.addMany([fl, gl]);

// Add layers using layers collection
map.layers.addMany([fl, gl]);

// Add layers using layers collection's push method
map.layers.push(fl, gl);

tables Collection<Layer>autocast

Autocasts from Layer[]

A collection of layer instances that are tables saved in a Map and/or a WebMap. In order for the table(s) to be recognized as such, the FeatureLayer's isTable property must return true. A table can be created via one of the options below:

• Referencing the URL to a table in a feature service.
• Create a feature layer using the Layer.fromArcGISServerUrl method and confirm that it is a table using feature layer's isTable property. This can be either a feature service or feature collection.
• Create a feature layer using the Layer.fromPortalItem method and confirm that it is a table using feature layer's isTable property. This can be either a feature service or feature collection.
• Create an in-memory, non-spatial, client-side feature layer.

Beginning with 4.17, it is possible to persist non-spatial, tables in a feature service to a WebMap, although in-memory (feature collection) tables are not yet supported.

Persisting tables within a GroupLayer is not yet supported. If this is needed, add them to the Map and/or WebMap.

• Currently, only feature service feature layers are recognized.
• To access spatial layers, use the layers property in either Map or WebMap classes

See also

• Sample - Creating a FeatureLayer - Add an array of client-side features

• FeatureLayer.isTable

• Sample - Save a web map

Examples

// This snippet shows how to add a table to a map's table collection.

// FeatureLayer.isTable = false
const featureLayer = new FeatureLayer({
  url: "https://sampleserver6.arcgisonline.com/arcgis/rest/services/SF311/FeatureServer/0"
});

// FeatureLayer.isTable = true
const table = new FeatureLayer({
  url: "https://sampleserver6.arcgisonline.com/arcgis/rest/services/SF311/FeatureServer/1"
});

// Add featureLayer to the map
map.add(featureLayer);

// In order for the table to be stored within
// the map's table collection, load it and confirm it is the right type.

table.load().then(() => {
  // Add the table to the collection
  map.tables.add(table);
  console.log("Table is added to map's table collection");
});

// This snippet shows how to persist a table to an existing web map

// FeatureLayer.isTable = true
const table = new FeatureLayer({
  url: "https://services.arcgis.com/V6ZHFr6zdgNZuVG0/arcgis/rest/services/Crash_details_table/FeatureServer/0"
});

// Create Webmap instance
const webmap = new WebMap({
  portalItem: {
    id: webmapId
  }
});

// When web map is ready, load the table and add it to the web map
webmap.when(() => {
  table.load().then(() => {
    console.log("Adding table");
    // Add table to the webmap's table collection
    webmap.tables.add(table);
  });
});

// Call updateFrom on webmap and pass in the existing view
webmap.updateFrom(view).then(() => {
  // Call saveAs (or save) on the web map
  webmap.saveAs({
    // autocasts as new PortalItem()
    title: "New WebMap"
  });
});

// This snippet shows how to add an in-memory table to a map

// Create the array of objects containing field info
const fields = [{
  name: "ObjectID",
  alias: "ObjectID",
  type: "oid"
},
{
  name: "tree_type",
  alias: "Tree type",
  type: "string"
},
{
  name: "species",
  alias: "Species",
  type: "string"
}];

// Create the array of graphics holding attribute info
const graphics = [{
  attributes: {
    "tree_type": "deciduous",
    "species": "maple",
    "ObjectID": 2
  }
}, {
  attributes: {
    "tree_type": "coniferous",
    "species": "pine",
    "ObjectID": 3
  }
}];

// Create the feature layer (feature collection) table
const table = new FeatureLayer({
  fields: fields,
  objectIdField: "ObjectID",
  source: graphics
});

// Check when map is ready and load the table
map.when(() => {
  table.load().then(() => {
    console.log("Adding table");
    map.tables.add(table);
  });
});

Method Overview

Method Details

add(layer, index)

Adds a layer to the layers collection. The before-changes, before-add, after-add, after-changes and change events will be emitted when this method is called.

Parameters

layer Layer|Promise Layer or a promise that resolves to a layer to add to the layers collection.

index Number optional A layer can be added at a specified index in the layers collection. If no index is specified or the index specified is greater than the current number of layers, the layer is automatically appended to the list of layers in the layers collection and the index is normalized.

See also

• layer collection's push() method

Example

// add() and push methods can be used
// to add a layer to layers collection

// add a layer to layers collection using add
map.add(layer);

// add a layer at the end of layers collection
map.layers.push(layer);

addHandles(handleOrHandles, groupKey)inherited

Since: ArcGIS Maps SDK for JavaScript 4.25

Adds one or more handles which are to be tied to the lifecycle of the object. The handles will be removed when the object is destroyed.

// Manually manage handles
const handle = reactiveUtils.when(
  () => !view.updating,
  () => {
    wkidSelect.disabled = false;
  },
  { once: true }
);

this.addHandles(handle);

// Destroy the object
this.destroy();

Parameters

handleOrHandles WatchHandle|WatchHandle[] Handles marked for removal once the object is destroyed.

groupKey * optional Key identifying the group to which the handles should be added. All the handles in the group can later be removed with Accessor.removeHandles(). If no key is provided the handles are added to a default group.

addMany(layers, index)

Adds a layer or an array of layers to the layers collection. The before-changes, before-add, after-add, after-changes and change events will be emitted when this method is called.

The push() method on the layers collection also can be used to add a layer or layers.

Parameters

layers Layer[] Layer(s) to be added to the layers collection.

index Number optional A layer can be added at a specified index in the layers collection. If no index is specified or the index specified is greater than the current number of layers, the layer is automatically appended to the list of layers in the layers collection and the index is normalized.

See also

• layer collection's push() method

Example

// addMany and push methods can be used
// to add layers to layers collection

// add an array of layers to layers collection using addMany
map.addMany([layer, layer2]);

// add layers to layers collection using push method
map.layers.push(layer, layer2);

destroy()

Since: ArcGIS Maps SDK for JavaScript 4.17

Destroys the map, and any associated resources, including its layers, basemap, tables, and ground. These can no longer be used once the map has been destroyed. To prevent these objects from being destroyed, remove them from the map before calling destroy().

// prevent the layers from being destroyed by removing them from the map
const layers = map.layers.removeAll();

// prevent the tables from being destroyed by removing them from the map
const tables = map.tables.removeAll();

// unset basemap from the map so that it is not destroyed
const basemap = map.basemap;
map.basemap = null;

// unset ground from the map so that it is not destroyed
const ground = map.ground;
map.ground = null;

// destroy the map and any remaining associated resources
map.destroy();

See also

• WebMap.destroy()
• WebScene.destroy()
• Basemap.destroy()
• Ground.destroy()
• Layer.destroy()
• PortalItem.destroy()

findLayerById(layerId){Layer}

Returns a layer based on the given layer ID.

Parameter

layerId String The ID assigned to the layer.

Returns

Type	Description
Layer	Returns the requested layer object.

findTableById(tableId){Layer}

Since: ArcGIS Maps SDK for JavaScript 4.18

Returns a table based on the given table ID.

Parameter

tableId String The ID assigned to the table.

Returns

Type	Description
Layer	Returns the requested table object.

hasHandles(groupKey){Boolean}inherited

Since: ArcGIS Maps SDK for JavaScript 4.25

Returns true if a named group of handles exist.

Parameter

groupKey * optional A group key.

Returns

Type	Description
Boolean	Returns true if a named group of handles exist.

Example

// Remove a named group of handles if they exist.
if (obj.hasHandles("watch-view-updates")) {
  obj.removeHandles("watch-view-updates");
}

remove(layer){Layer}

Removes the specified layer from the layers collection. The before-changes, before-remove, after-remove, after-changes and change events will be emitted when this method is called.

Parameter

layer Layer Layer to remove from the layers collection.

Returns

Type	Description
Layer	Returns the layer removed from the layers collection.

removeAll(){Layer[]}

Removes all layers. The before-changes, before-remove, after-remove, after-changes and change events will be emitted when this method is called.

Returns

Type	Description
Layer[]	Returns the layers removed from the layers collection.

removeHandles(groupKey)inherited

Since: ArcGIS Maps SDK for JavaScript 4.25

Removes a group of handles owned by the object.

Parameter

groupKey * optional A group key or an array or collection of group keys to remove.

Example

obj.removeHandles(); // removes handles from default group

obj.removeHandles("handle-group");
obj.removeHandles("other-handle-group");

removeMany(layers){Layer[]}

Removes the specified layers. The before-changes, before-remove, after-remove, after-changes and change events will be emitted when this method is called.

Parameter

layers Layer[] Array of layers to remove from the layers collection.

Returns

Type	Description
Layer[]	Returns the layers removed from the layers collection.

reorder(layer, index){Layer}

Changes the layer order. The first layer added is always the base layer, even if its order is changed. The change event will be emitted when this method is called.

In 3D, for layers that are rendered on the terrain, the order of the layers also depends on the type of layer. Tiled layers (VectorTileLayer, WebTileLayer, WMTSLayer) are always drawn first in the same order as specified in the layer collection. Dynamic layers (MapImageLayer, ImageryLayer, WMSLayer, and feature based layers with elevation mode on-the-ground) are rendered on top using the order from the layer collection.

Parameters

layer Layer The layer to be moved.

index Number The index location for placing the layer. The bottom-most layer has an index of 0.

Returns

Type	Description
Layer	Returns the layer that was moved.