require(["esri/WebMap"], function(WebMap) { /* code goes here */ });
Class: esri/WebMap
Inheritance: WebMap Map Accessor
Since: ArcGIS API for JavaScript 4.0

Loads a WebMap from ArcGIS Online or ArcGIS Enterprise portal into a MapView.

To load a WebMap into a MapView, you must reference the ID of the webmap in the portalItem property of this class.

var webmap = new WebMap({
  portalItem: { // autocasts as new PortalItem()
    id: "e691172598f04ea8881cd2a4adaa45ba"
  }
});

Then you must reference the WebMap instance in the map property of the view.

var view = new MapView({
  map: webmap,  // The WebMap instance created above
  container: "viewDiv"
});

Working with the WebMap is partially supported. This means it relies on capabilities already available in the API. For example, although it is possible to read WebMaps if they contain layer types that are not yet implemented (e.g. KML layers), only layer types supported by the API will display.

In these instances, the layer types that are not yet supported in the API will be created as an UnsupportedLayer. This layer type is used specifically in these instances where the layer may exist in a given WebMap, e.g. WFS layers, but may not be currently supported in the version of the API accessing it (e.g. 4.5 does not support WFS layers).

An UnknownLayer will be used if future versions of the WebMap contains a new type of layer. The API version may not recognize this layer type, therefore it would come across as an UnknownLayer.

Various sample WebMaps are made available and can be accessed here.

See also:

Constructors

new WebMap(properties)
Parameter:
properties Object
optional

See the properties for a list of all the properties that may be passed into the constructor.

Example:
// Typical usage
var map = new WebMap({
  portalItem: {
    id: "e691172598f04ea8881cd2a4adaa45ba"
  }
});

Property Overview

Any properties can be set, retrieved or listened to. See the Working with Properties topic.
NameTypeSummaryClass
Collection<Layer>

A flat collection of all the layers in the map.

more details
more detailsMap
Object

Object responsible for containing the viewing and editing properties of the WebMap.

more details
more detailsWebMap
Basemap

Specifies a basemap for the map.

more details
more detailsMap
Object[]

An array of saved geographic extents that allow end users to quickly navigate to a particular area of interest.

more details
more detailsWebMap
String

The name of the class.

more details
more detailsAccessor
Ground

Specifies the surface properties for the map.

more details
more detailsMap
InitialViewProperties

The initial view of the WebMap.

more details
more detailsWebMap
Collection<Layer>

A collection of operational layers.

more details
more detailsMap
Boolean

Indicates whether the instance has loaded.

more details
more detailsWebMap
Error

The Error object returned if an error occurred while loading.

more details
more detailsWebMap
String

Represents the status of a load operation.

more details
more detailsWebMap
PortalItem

The portal item from which the WebMap is loaded.

more details
more detailsWebMap
Object

Provides multiple slides.

more details
more detailsWebMap
Object

The version of the source document from which the WebMap was read.

more details
more detailsWebMap
Object[]

An array of table objects in the WebMap.

more details
more detailsWebMap
Object

The widgets object contains widgets that should be exposed to the user.

more details
more detailsWebMap

Property Details

allLayersCollection<Layer>readonly inherited

A flat collection of all the 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.

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

// Create a filtered collection of the non-group layers
var 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);
});
applicationPropertiesObject

Object responsible for containing the viewing and editing properties of the WebMap.

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.

ValueDescription
streetsbasemap-streets
satellitebasemap-satellite
hybridbasemap-hybrid
topobasemap-topo
graybasemap-gray
dark-graybasemap-dark-gray
oceansbasemap-oceans
national-geographicbasemap-national-geographic
terrainbasemap-terrain
osmbasemap-osm
dark-gray-vectordark-gray-vector
gray-vectorgray-vector
streets-vectorstreets-vector
topo-vectortopo-vector
streets-night-vectorstreets-night-vector
streets-relief-vectorstreets-relief-vector
streets-navigation-vectorstreets-navigation-vector
Example:
// Set the basemap in the constructor
var map = new Map({
  basemap: "streets"
});

// Set the basemap after the map instance is created
map.basemap = "topo";
bookmarksObject[]

An array of saved geographic extents that allow end users to quickly navigate to a particular area of interest.

declaredClassStringreadonly inherited
Since: ArcGIS API for JavaScript 4.7

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

Autocasts from String|Object

Specifies the surface properties for the map. This property is only relevant when adding the map to a 3D SceneView. It renders the terrain or topographical variations in the real world on the map's surface with a collection of ElevationLayer.

This value can be an instance of Ground, or the string world-elevation for a default instance of ground using the World Elevation 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:
Examples:
// Use the world elevation service
var map = new Map({
  basemap: "topo",
  ground: "world-elevation"
});
// Create a map with the world elevation layer overlaid by a custom elevation layer
var worldElevation = ElevationLayer({
  url: "//elevation3d.arcgis.com/arcgis/rest/services/WorldElevation3D/Terrain3D/ImageServer"
});
var customElevation = ElevationLayer({
  url: "http://my.server.com/arcgis/rest/service/MyElevationService/ImageServer"
});
var map = new Map({
  basemap: "topo",
  ground: new Ground({
   layers: [ worldElevation, customElevation ]
  })
});
initialViewPropertiesInitialViewPropertiesautocast

The initial view of the WebMap. This object contains properties such as viewpoint, spatialReference, that should be applied to the view when the WebMap loads.

Autocasts from Layer[]

A collection of operational layers. This property only contains interactive 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().

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.

var 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);
Example:
// Add layers in the constructor of Map using an array
var fl = new FeatureLayer(url);
var gl = new GraphicsLayer();
var map = new Map({
  layers: [fl, gl]
});

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

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

Indicates whether the instance has loaded. When true, the properties of the object can be accessed. A WebMap is considered loaded when its layers and basemap are created, but not yet loaded.

Default Value:false
loadErrorErrorreadonly

The Error object returned if an error occurred while loading.

Default Value:null
loadStatusStringreadonly

Represents the status of a load operation.

ValueDescription
not-loadedThe object's resources have not loaded.
loadingThe object's resources are currently loading.
loadedThe object's resources have loaded without errors.
failedThe object's resources failed to load. See loadError for more details.
Default Value:not-loaded

The portal item from which the WebMap is loaded.

presentationObject

Provides multiple slides. Each slide has a different "title", "extent", "basemap", "layers" etc.

sourceVersionObjectreadonly
Since: ArcGIS API for JavaScript 4.1

The version of the source document from which the WebMap was read. The WebMap must be version 2.x to load into an app.

Properties:
major Number

The major version of the WebMap.

minor Number

The minor version of the WebMap.

tablesObject[]

An array of table objects in the WebMap.

widgetsObject

The widgets object contains widgets that should be exposed to the user.

Method Overview

NameReturn TypeSummaryClass

Adds a layer to the layers collection.

more details
more detailsMap

Adds a layer or an array of layers to the layers collection.

more details
more detailsMap
Layer

Returns a layer based on the given layer id.

more details
more detailsMap
Boolean

isFulfilled() may be used to verify if creating an instance of the class is fulfilled (either resolved or rejected).

more details
more detailsWebMap
Boolean

isRejected() may be used to verify if creating an instance of the class is rejected.

more details
more detailsWebMap
Boolean

isResolved() may be used to verify if creating an instance of the class is resolved.

more details
more detailsWebMap
Promise

Triggers the loading of the WebMap instance.

more details
more detailsWebMap
Layer

Removes the specified layer from the layers collection.

more details
more detailsMap
Layer[]

Removes all layers.

more details
more detailsMap
Layer[]

Removes the specified layers.

more details
more detailsMap
Layer

Changes the layer order.

more details
more detailsMap
Promise

when() may be leveraged once an instance of the class is created.

more details
more detailsWebMap

Method Details

add(layer, index)inherited

Adds a layer to the layers collection.

Parameters:

Layer or a Promise<Layer> 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.

addMany(layers, index)inherited

Adds a layer or an array of layers to the layers collection.

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.

findLayerById(layerId){Layer}inherited

Returns a layer based on the given layer id.

Parameter:
layerId String

The ID assigned to the layer.

Returns:
TypeDescription
LayerReturns the requested layer object.
isFulfilled(){Boolean}

isFulfilled() may be used to verify if creating an instance of the class is fulfilled (either resolved or rejected). If it is fulfilled, true will be returned.

Returns:
TypeDescription
BooleanIndicates whether creating an instance of the class has been fulfilled (either resolved or rejected).
isRejected(){Boolean}

isRejected() may be used to verify if creating an instance of the class is rejected. If it is rejected, true will be returned.

Returns:
TypeDescription
BooleanIndicates whether creating an instance of the class has been rejected.
isResolved(){Boolean}

isResolved() may be used to verify if creating an instance of the class is resolved. If it is resolved, true will be returned.

Returns:
TypeDescription
BooleanIndicates whether creating an instance of the class has been resolved.
load(){Promise}

Triggers the loading of the WebMap instance.

A WebMap is considered loaded when its operational layers and basemap are fully created. When created with a portalItem, load() will first fetch its data to create the content, otherwise it resolves immediately.

The MapView automatically calls the load() method when a WebMap instance is added to its map property so it can display in the view and load each individual layer. If the WebMap is used outside of a view, for example to preload it, you must call load() explicitly to interact with its resources.

Returns:
TypeDescription
PromiseResolves when the WebMap is loaded.
See also:
Example:
require([
  "esri/WebMap",

  "dojo/promise/all"
], function(
  WebMap,
  all
) {

  var map = new WebMap({
    portalItem: {
      id: "e691172598f04ea8881cd2a4adaa45ba"
    }
  });

  map.load()
    .then(function() {
      // load the basemap to get its layers created
      return map.basemap.load();
    })
    .then(function() {
      // grab all the layers and load them
      var allLayers = map.allLayers;
      var promises = allLayers.map(function(layer) {
        return layer.load();
      });
      return all(promises.toArray());
    })
    .then(function(layers) {
      // each layer load promise resolves with the layer
      console.log("all " + layers.length + " layers loaded");
    })
    .catch(function(error) {
      console.error(error);
    });
});
remove(layer){Layer}inherited

Removes the specified layer from the layers collection.

Parameter:
layer Layer

Layer to remove from the layers collection.

Returns:
TypeDescription
LayerReturns the layer removed from the layers collection.
removeAll(){Layer[]}inherited

Removes all layers.

Returns:
TypeDescription
Layer[]Returns the layers removed from the layers collection.
removeMany(layers){Layer[]}inherited

Removes the specified layers.

Parameter:
layers Layer[]

Array of layers to remove from the layers collection.

Returns:
TypeDescription
Layer[]Returns the layers removed from the layers collection.
reorder(layer, index){Layer}inherited

Changes the layer order. The first layer added is always the base layer, even if its order is changed.

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:
TypeDescription
LayerReturns the layer that was moved.
when(callback, errback){Promise}
Since: ArcGIS API for JavaScript 4.6

when() may be leveraged once an instance of the class is created. This method takes two input parameters: a callback function and an errback function. The callback executes when the instance of the class loads. The errback executes if the instance of the class fails to load.

Parameters:
callback Function
optional

The function to call when the promise resolves.

errback Function
optional

The function to execute when the promise fails.

Returns:
TypeDescription
PromiseReturns a new promise for the result of callback that may be used to chain additional functions.
Example:
// Although this example uses MapView, any class instance that is a promise may use then() in the same way
var view = new MapView();
view.when(function(){
  // This function will execute once the promise is resolved
}, function(error){
  // This function will execute if the promise is rejected due to an error
});

API Reference search results

NameTypeModule
Loading...