WebMap

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. It defines the content, style, and bookmarks of your webmap, and it can be shared across multiple ArcGIS web and desktop applications. The webmap is saved as a JSON document that can be consumed by the ArcGIS API for JavaScript via the WebMap class to easily create compelling 2D applications. The JSON document is written according to the webmap specification. Although you can easily create your own webmaps, there are many sample webmaps in ArcGIS Online that you can use to get started with the API. You may modify or add new content to these webmaps.

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

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

To load a Webmap from an on-premise portal, set the portal url in esriConfig.portalurl.

esriConfig.portalUrl = "https://myHostName.esri.com/arcgis";

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

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

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

Known Limitations

  • WCS and WFS layers are currently not supported.

In instances when the webmap contains layer types that are not yet supported in the API, layers 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 layer), but may not be currently supported in the version of the API accessing it.

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.

  • Embedded Routes

Prior to the ArcGIS Online 8.1 release (March 2020) when copying a route layer from an item to be stored inside a WebMap it would be stored as an embedded feature collection, and inadvertently not attributed as a route. When these webmaps are loaded by the JS API, the routes will be represented by a GroupLayer rather than a esri/layers/RouteLayer. This does not affect copied route layer items after the ArcGIS Online 8.1 release or routes stored as portal items. Copying route layer items to be stored as part of the webmap is not a common scenario.

  • Accessing geometries from popup features

Beginning with version 4.17, webmaps no longer return geometries in its popup's features. If a popup does not have a referenced Arcade expression that works with geometry, it is now required to set either the webmap layer's outFields or its PopupTemplate outFields.

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
const map = new WebMap({
  portalItem: {
    id: "e691172598f04ea8881cd2a4adaa45ba"
  }
});

Property Overview

Any properties can be set, retrieved or listened to. See the Working with Properties topic.
Show inherited properties Hide inherited properties
Name Type Summary Class
Collection<Layer>

A flattened collection of all layers in the map.

more details
more detailsMap
Collection<Layer>

A flattened collection of tables anywhere in the map's hierarchy.

more details
more detailsMap
ApplicationProperties

The applicationProperties contains the viewing properties of the WebMap.

more details
more detailsWebMap
String

The name of the application that authored the WebMap.

more details
more detailsWebMap
String

The version of the application that authored the WebMap.

more details
more detailsWebMap
Basemap

Specifies a basemap for the map.

more details
more detailsMap
Collection<Bookmark>

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
Collection<Layer>

A collection of layer instances that are tables saved in a Map and/or a WebMap.

more details
more detailsMap
String

The URL to the thumbnail used for the webmap.

more details
more detailsWebMap
Widgets

The widgets object contains widgets that are exposed to the user.

more details
more detailsWebMap

Property Details

allLayers Collection<Layer>readonly inherited

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 inherited
Since: ArcGIS API 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";
});
applicationProperties ApplicationProperties
Since: ArcGIS API for JavaScript 4.14

The applicationProperties contains the viewing properties of the WebMap.

authoringApp String
Since: ArcGIS API for JavaScript 4.14

The name of the application that authored the WebMap.

authoringAppVersion String
Since: ArcGIS API for JavaScript 4.14

The version of the application that authored 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.

Basemaps for use with API keys

Use of these basemaps requires an ArcGIS Developer subscription.

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
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 argis-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
topo https://services.arcgisonline.com/ArcGIS/rest/services/World_Topo_Map/MapServer
streets https://services.arcgisonline.com/ArcGIS/rest/services/World_Street_Map/MapServer
satellite https://services.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer
hybrid https://services.arcgisonline.com/ArcGIS/rest/services/Reference/World_Boundaries_and_Places/MapServer
and
https://services.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer
dark-gray https://services.arcgisonline.com/ArcGIS/rest/services/Canvas/World_Dark_Gray_Reference/MapServer
and
https://services.arcgisonline.com/ArcGIS/rest/services/Canvas/World_Dark_Gray_Base/MapServer
gray https://services.arcgisonline.com/ArcGIS/rest/services/Canvas/World_Light_Gray_Reference/MapServer
and
https://services.arcgisonline.com/ArcGIS/rest/services/Canvas/World_Light_Gray_Base/MapServer
national-geographic https://services.arcgisonline.com/ArcGIS/rest/services/NatGeo_World_Map/MapServer
oceans https://services.arcgisonline.com/arcgis/rest/services/Ocean/World_Ocean_Reference/MapServer
and
https://services.arcgisonline.com/arcgis/rest/services/Ocean/World_Ocean_Base/MapServer
osm OpenStreetMapLayer
terrain https://services.arcgisonline.com/ArcGIS/rest/services/Reference/World_Reference_Overlay/MapServer
and
https://services.arcgisonline.com/ArcGIS/rest/services/World_Terrain_Base/MapServer
dark-gray-vector Dark Gray Canvas [v2]
gray-vector Light Gray Canvas [v2]
streets-vector World Street Map [v2]
streets-night-vector World Street Map (Night) [v2]
streets-navigation-vector World Navigation Map [v2]
topo-vector https://services.arcgisonline.com/arcgis/rest/services/Elevation/World_Hillshade/MapServer
and
World Topographic Map [v2]
streets-relief-vector https://services.arcgisonline.com/arcgis/rest/services/Elevation/World_Hillshade/MapServer
and
World Street Map (with Relief) [v2]
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";

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

declaredClass Stringreadonly 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. 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:
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 ]
  })
});
initialViewProperties InitialViewPropertiesautocast

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 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.

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);

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
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]);

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

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
loadError Errorreadonly

The Error object returned if an error occurred while loading.

Default Value:null
loadStatus Stringreadonly

Represents the status of a load operation.

Value Description
not-loaded The object's resources have not loaded.
loading The object's resources are currently loading.
loaded The object's resources have loaded without errors.
failed The object's resources failed to load. See loadError for more details.

Possible Values:"not-loaded"|"loading"|"failed"|"loaded"

Default Value:not-loaded
portalItem PortalItemautocast

The portal item from which the WebMap is loaded.

presentation Object

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

sourceVersion Objectreadonly
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.

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:
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(function() {
  // 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(function() {
  table.load().then(function() {
    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(function() {
  // 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(function() {
  table.load().then(function() {
    console.log("Adding table");
    map.tables.add(table);
  });
});
thumbnailUrl String
Since: ArcGIS API for JavaScript 4.14

The URL to the thumbnail used for the webmap. The thumbnailUrl will default to the thumbnail URL from the portal item associated to the webmap. The thumbnail of the webmap may be updated by changing the thumbnail URL and saving the webmap. Use updateFrom to update the thumbnail automatically from a specified view.

Example:
webmap.updateFrom(view)
  .then(function() {
    return webmap.save();
  })
  // thumbnail will be updated based on current extent of webmap
  .then(function(portalItem) {
    console.log("Saved to portal", portalItem.id);
  })
  .catch(function(error) {
    console.error("Error saving to portal", error);
  });
widgets Widgets

The widgets object contains widgets that are exposed to the user.

Method Overview

Show inherited methods Hide inherited methods
Name Return Type Summary Class

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

Destroys the webmap, and any associated resources, including its layers, basemap, ground, tables, and portalItem.

more details
more detailsWebMap
Layer

Returns a layer based on the given layer ID.

more details
more detailsMap
SearchTable

Returns a table based on the given table ID.

more details
more detailsMap
*

Creates a new instance of this class and initializes it with values from a JSON object generated from a product in the ArcGIS platform.

more details
more detailsWebMap
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
Promise<WebMap>

Loads all the externally loadable resources associated with the webmap.

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<PortalItem>

Saves the webmap to its associated portal item.

more details
more detailsWebMap
Promise<PortalItem>

Saves the webmap to a new portal item.

more details
more detailsWebMap
Promise

Update properties of the WebMap related to the view.

more details
more detailsWebMap
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. 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:
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);
addMany(layers, index)inherited

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:
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 API for JavaScript 4.17

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

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

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

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

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

// unset portalItem from the webmap so that it is not destroyed
const portalItem = webmap.portalItem;
webmap.portalItem = null;

// destroy the webmap and any remaining associated resources
webmap.destroy();
See also:
findLayerById(layerId){Layer}inherited

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){SearchTable}inherited
Since: ArcGIS API 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
SearchTable Returns the requested table object.
fromJSON(json){*}static
Since: ArcGIS API for JavaScript 4.12

Creates a new instance of this class and initializes it with values from a JSON object generated from a product in the ArcGIS platform. The object passed into the input json parameter often comes from a response to a query operation in the REST API or a toJSON() method from another ArcGIS product. If the WebMap is used outside of a view, you must call load() explicitly to interact with its resources. See the Using fromJSON() topic in the Guide for details and examples of when and how to use this function.

Parameter:
json Object

A JSON representation of the instance in the ArcGIS format. See the web map specification for more detailed information on serializing web map to JSON.

Returns:
Type Description
* Returns a new instance of this class.
Example:
// Retrieve a WebMap JSON by url and deserialize it into a WebMap API instance
require(["esri/request", "esri/WebMap"], function(esriRequest, WebMap) {
  esriRequest("http://domain/url/to/webmap.json").then(function(json) {
    const webmap = WebMap.fromJSON(json);

    const view = new MapView({
      map: webmap,
      container: "viewDiv"
    });
  });
});
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:
Type Description
Boolean Indicates 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:
Type Description
Boolean Indicates 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:
Type Description
Boolean Indicates 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:
Type Description
Promise Resolves when the WebMap is loaded.
See also:
Example:
require([
  "esri/WebMap"
], function(
  WebMap
) {

  const 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
      const allLayers = map.allLayers;
      const promises = allLayers.map(function(layer) {
        return layer.load();
      });
      return Promise.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);
    });
});
loadAll(){Promise<WebMap>}
Since: ArcGIS API for JavaScript 4.9

Loads all the externally loadable resources associated with the webmap. For the webmap this will load the ground, basemap and layers.

Returns:
Type Description
Promise<WebMap> Resolves when all the loadable resources have been loaded. Rejects if at least one of the loadable resources failed to load.
See also:
Example:
// Load all resources but ignore if one or more of them failed to load
webmap.loadAll()
  .catch(function(error) {
    // Ignore any failed resources
  })
  .then(function() {
    console.log("All loaded");
  });
remove(layer){Layer}inherited

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[]}inherited

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.
removeMany(layers){Layer[]}inherited

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}inherited

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.
save(options){Promise<PortalItem>}
Since: ArcGIS API for JavaScript 4.14

Saves the webmap to its associated portal item. The portal item must already exist and be valid. This is a convenience method that will use update to store the webmap in the item. The webmap is saved according to web map specification standards.

Use updateFrom to store the current view properties in the webmap before saving it.

Note that this saves the webmap to its existing item. Depending on how the webmap is shared, users that do not own the webmap may be able to modify it. To save an existing webmap as a new item owned by the user signed into the portal instance, use saveAs().

The webmap will be automatically loaded if it is not already before saving.

Known Limitations

Parameters:
options Object
optional

Additional options.

Specification:
ignoreUnsupported Boolean
optional

When true, the webmap will save even if it contains unsupported content (layers, renderers, symbols). Any content that is not supported will not be saved and the webmap may appear different when reloaded from its portal item.

Returns:
Type Description
Promise<PortalItem> A promise that resolves with the PortalItem instance when the item has successfully been saved, or rejected otherwise.
See also:
Example:
webmap.updateFrom(view)
  .then(function() {
    return webmap.save();
  })
  .then(function(portalItem) {
    console.log("Saved to portal", portalItem.id);
  })
  .catch(function(error) {
    console.error("Error saving to portal", error);
  });
saveAs(portalItem, options){Promise<PortalItem>}
Since: ArcGIS API for JavaScript 4.14

Saves the webmap to a new portal item. If saving has completed successfully, then the saved portal item will be set in the portalItem property of the WebMap. This is a convenience method that will create a new PortalItem and use PortalUser.addItem() to store the webmap in a Portal.

Use updateFrom to store the current view properties in the webmap before saving it.

Note that this always saves the webmap as a new portal item owned by the user signed into the portal instance that executes the saveAs() method. If you want to modify an existing item without changing its ownership, use save().

The webmap will be automatically loaded if it is not already before saving.

Known Limitations

Parameters:
Specification:
portalItem PortalItem autocast
Autocasts from Object

The new portal item to which the webmap will be saved.

Portal item properties such as the title or description need to be explicitly set on the item and will not be automatically copied from the current associated webmap portal item (if any).

options Object
optional

Additional save options.

Specification:
folder PortalFolder
optional

The folder in which to save the item.

ignoreUnsupported Boolean
optional

Allow the webmap to be saved even in the case it contains unsupported content (layers, renderers, symbols). Any content that is not supported will not be saved and the webmap may appear different when reloaded from its portal item.

Returns:
Type Description
Promise<PortalItem> A promise that resolves with the PortalItem instance when the item has successfully been saved, or rejected otherwise.
See also:
Example:
const webmap = new WebMap();
// Use updateFrom to store the current view properties
// in the webmap before saving it
webmap.updateFrom(view);
webmap.saveAs({
  // autocasts as new PortalItem()
  title: "New WebMap"
});
updateFrom(view, options){Promise}
Since: ArcGIS API for JavaScript 4.14

Update properties of the WebMap related to the view. This should usually be called just before saving a webmap. The following properties are updated from the view:

  1. InitialViewProperties.spatialReference

Depending on the provided options, the following properties are also updated:

  1. The rotation, scale, and targetGeometry properties of InitialViewProperties.viewpoint
  2. The thumbnail of the PortalItem
Parameters:
Specification:
view MapView

The view to update from.

options Object
optional

Update options.

Specification:
backgroundExcluded Boolean
optional

When true, the view's background will not be updated for the webmap. The default is false meaning the background will be updated for the webmap if there is a background.

viewpointExcluded Boolean
optional

When true, the initial viewpoint of the view will not be updated for the webmap. Defaults to false, meaning the viewpoint will be updated for the webmap. Must set scalePreserved to true if the view's scale should be updated for the webmap.

scalePreserved Boolean
optional

When true, the view's scale will be updated for the webmap. Defaults to false meaning view's scale will not be updated for the webmap. It is ignored when viewpointExcluded is true.

thumbnailExcluded Boolean
optional

When true, the thumbnail will not be updated for the webmap. Defaults to false meaning the thumbnail will be updated for the webmap.

thumbnailSize Object
optional

The size of the thumbnail. Defaults to 600x400 (ratio 1.5:1). Note that the thumbnail size may currently not be larger than the size of the view.

Specification:
width Number

The width of the thumbnail.

height Number

The height of the thumbnail.

widgetsExcluded Boolean
optional

When true, the webmap's widgets property will not be updated. When false, the definition of the first TimeSlider assigned to the View will be used to update the WebMap.widgets property. The default value is false.

Returns:
Type Description
Promise Resolves when the update has completed.
See also:
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:
Type Description
Promise Returns 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 when() 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
});

Type Definitions

TimeSlider Object

Time animation is controlled by a configurable time slider. Those configurations are saved to the web map as a timeSlider widget.

Properties:
fullTimeExtent TimeExtent
optional

The temporal extent for the entire slider. See the fullTimeExtent property of the time slider widget for more information.

currentTimeExtent TimeExtent
optional

The current time extent of the time slider. See the timeExtent property of the time slider widget for more information.

numStops Number
optional

The number of stops. It divides the time slider's fullTimeExtent into equal parts. See the time slider widget's stops and StopsByCount properties.

numThumbs Number
optional

The thumb count. See the time slider widget's mode and timeExtent properties. This value defaults to 1.

stopDelay Number
optional

The time rate in milliseconds between animation steps. See the time slider widget's playRate property. This value defaults to 1000.

stopInterval TimeInterval
optional

Defines regularly spaced stops on the time slider from a TimeInterval object. See the time slider widget's stops and StopsByInterval properties.

Widgets Object

The widgets object contains widgets that are exposed to the user.

Property:
TimeSlider TimeSlider

Time animation is controlled by a configurable time slider. Those configurations are saved to the web map as a TimeSlider widget.