require(["esri/Map"], (Map) => { /* code goes here */ });
import Map from "@arcgis/core/Map.js";
esri/Map
The Map class contains properties and methods for storing, managing, and overlaying layers common to both 2D and 3D viewing. Layers can be added and removed from the map, but are rendered via a MapView (for viewing data in 2D) or a SceneView (for viewing data in 3D). Thus a map instance is a simple container that holds the layers, while the View is the means of displaying and interacting with a map's layers and basemap.
A single map may be referenced by multiple views. This sample for example, contains a single Map that is visible in two separate views - one in 2D and the other in 3D. Because one map may be accessed by multiple views in the same application, all user interaction with a map's layers is handled on the View, not the Map.
An instance of Map is an essential component of the MapView
and SceneView. A Map object should be created prior to a
view so it can be passed into the map
property of that view
(e.g. MapView.map, SceneView.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
});
});
Constructors
-
Parameterproperties Objectoptional
See the properties for a list of all the properties that may be passed into the constructor.
Example// Typical usage const map = new Map({ basemap: "topo-vector" });
Property Overview
Name | Type | Summary | Class |
---|---|---|---|
A flattened collection of all layers in the map. | Map | ||
A flattened collection of tables anywhere in the map's hierarchy. | Map | ||
Specifies a basemap for the map. | Map | ||
The name of the class. | Accessor | ||
A collection of editable layers. | Map | ||
Specifies the surface properties for the map. | Map | ||
A collection of operational layers. | Map | ||
A collection of layer instances that are tables saved in a Map and/or a WebMap. | Map |
Property Details
-
allLayers
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); }); // Watching for changes to the visible layers in the Map reactiveUtils.watch( () => view.map.allLayers.filter((layer) => layer.visible), (newVisibleLayers, oldVisibleLayers) => { const added = newVisibleLayers.filter( (layer) => !oldVisibleLayers.includes(layer) ); const removed = oldVisibleLayers.filter( (layer) => !newVisibleLayers.includes(layer) ); added.forEach((layer) => console.log(layer.title, "is visible")); removed.forEach((layer) => console.log(layer.title, "is not visible")); } );
-
allTables
allTables Collection<Layer>readonly
Since: ArcGIS Maps SDK for JavaScript 4.17Map since 4.0, allTables added at 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"; });
-
Specifies a basemap for the map. The basemap is a set of layers that give geographic context to the MapView or SceneView and the other operational layers in the map.
The basemap can be created in a variety of ways:
- From the basemap styles service (v2)
- From an instance of the Basemap class
- From a basemap id
Use of these basemaps requires either an ArcGIS Location Platform account, ArcGIS Online organizational subscription, or an ArcGIS Enterprise license.
To authenticate basemap requests, you may need an access token. You can use an API key or OAuth 2.0. When using an API key, the key must have privileges to access the appropriate location service.
Basemap Id
3D
Since version 4.28
The 3D Basemaps can be accessed using the basemap id in the table below. They are designed to be used as basemaps in SceneView.
Value Source topo-3d
Topographic navigation-3d
Navigation navigation-dark-3d
Navigation (Dark) osm-3d
OpenStreetMap gray-3d
Light Gray Canvas dark-gray-3d
Dark Gray Canvas streets-3d
Streets streets-dark-3d
Streets (Dark) Known Limitations
- 3D Basemaps can only be used in SceneView.
2D (legacy)
Since version 4.0
The legacy basemaps can be accessed using the basemap id in the table below. These are references to enhanced basemap endpoints.
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
/dark-gray-vector
Dark Gray Canvas gray
/gray-vector
Light Gray Canvas streets
/streets-vector
World Street Map streets-night-vector
World Street Map (Night) streets-navigation-vector
World Navigation Map topo
/topo-vector
World Hillshade and World Topographic Map streets-relief-vector
World Hillshade and World Street Map (with Relief) Examples// create the basemap from a string id representing the basemap style const map = new Map({ basemap: "osm/blueprint" }); // create the basemap from a BasemapStyle object const map = new Map({ basemap: { style: { id: "arcgis/outdoor", language: "es" // place labels will be displayed in spanish } } });
// Set the basemap from a string ID in the constructor const map = new Map({ basemap: "dark-gray-3d" }); // Set the basemap after the map instance is created map.basemap = "topo-3d";
// Create a VectorTileLayer from a style URL const mapBaseLayer = new VectorTileLayer({ url: "https://arcgis.com/sharing/rest/content/items/b5676525747f499687f12746441101ef/resources/styles/root.json" }); // Create a Basemap with the VectorTileLayer const customBasemap = new Basemap({ baseLayers: [mapBaseLayer], title: "Terrain" }); // Set the basemap to the customBasemap const map = new Map({ basemap: customBasemap });
-
editableLayers
editableLayers Collection<(FeatureLayer|SceneLayer|SubtypeGroupLayer|GeoJSONLayer|OrientedImageryLayer)>readonly
Since: ArcGIS Maps SDK for JavaScript 4.20Map since 4.0, editableLayers added at 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.
-
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
orundefined
, 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
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 = new ElevationLayer({ url: "//elevation3d.arcgis.com/arcgis/rest/services/WorldElevation3D/Terrain3D/ImageServer" }); const customElevation = new 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
layers Collection<Layer>autocast
-
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 (BaseTileLayer, ImageryTileLayer, OpenStreetMapLayer, TileLayer, VectorTileLayer, WCSLayer, WebTileLayer and 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
tables Collection<Layer>autocast
-
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
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
Name | Return Type | Summary | Class |
---|---|---|---|
Adds a layer to the layers collection. | Map | ||
Adds one or more handles which are to be tied to the lifecycle of the object. | Accessor | ||
Adds a layer or an array of layers to the layers collection. | Map | ||
Destroys the map, and any associated resources, including its layers, basemap, tables, and ground. | Map | ||
Returns a layer based on the given layer ID. | Map | ||
Returns a table based on the given table ID. | Map | ||
Returns true if a named group of handles exist. | Accessor | ||
Removes the specified layer from the layers collection. | Map | ||
Removes all layers. | Map | ||
Removes a group of handles owned by the object. | Accessor | ||
Removes the specified layers. | Map | ||
Changes the layer order. | Map |
Method Details
-
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.
Parameterslayer Layer|PromiseLayer or a promise that resolves to a layer to add to the layers collection.
index NumberoptionalA 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
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);
-
Inherited from Accessor
Since: ArcGIS Maps SDK for JavaScript 4.25Accessor since 4.0, addHandles added at 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();
ParametershandleOrHandles WatchHandle|WatchHandle[]Handles marked for removal once the object is destroyed.
groupKey *optionalKey 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.
-
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.
ParametersLayer(s) to be added to the layers collection.
index NumberoptionalA 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
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);
-
Since: ArcGIS Maps SDK for JavaScript 4.17Map since 4.0, destroy added at 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; // remove ground layers from the map so that they aren't destroyed const groundLayers = map.ground.removeAll(); // destroy the map and any remaining associated resources map.destroy();
-
findTableById
findTableById(tableId){Layer}
Since: ArcGIS Maps SDK for JavaScript 4.18Map since 4.0, findTableById added at 4.18. -
Returns a table based on the given table ID.
ParametertableId StringThe ID assigned to the table.
ReturnsType Description Layer Returns the requested table object.
-
hasHandles
InheritedMethodhasHandles(groupKey){Boolean}
Inherited from AccessorSince: ArcGIS Maps SDK for JavaScript 4.25Accessor since 4.0, hasHandles added at 4.25. -
Returns true if a named group of handles exist.
ParametergroupKey *optionalA group key.
ReturnsType 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
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.
Parameterlayer LayerLayer to remove from the layers collection.
ReturnsType Description Layer Returns the layer removed from the layers collection.
-
Removes all layers. The before-changes, before-remove, after-remove, after-changes and change events will be emitted when this method is called.
Returns
-
Inherited from Accessor
Since: ArcGIS Maps SDK for JavaScript 4.25Accessor since 4.0, removeHandles added at 4.25. -
Removes a group of handles owned by the object.
ParametergroupKey *optionalA group key or an array or collection of group keys to remove.
Exampleobj.removeHandles(); // removes handles from default group obj.removeHandles("handle-group"); obj.removeHandles("other-handle-group");
-
Removes the specified layers. The before-changes, before-remove, after-remove, after-changes and change events will be emitted when this method is called.
Returns
-
reorder
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 (BaseTileLayer, ImageryTileLayer, OpenStreetMapLayer, TileLayer, VectorTileLayer, WCSLayer, WebTileLayer and 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.ParametersReturnsType Description Layer Returns the layer that was moved.