Hide Table of Contents
esri/dijit/util
esri/layer/pixelFilters
esri/process
esri/workers
Class: BasemapToggle

require(["esri/dijit/BasemapToggle"], function(BasemapToggle) { /* code goes here */ });

Description

(Added at v3.7)
BasemapToggle provides a simple button to toggle between two basemaps. Use the BasemapGallery dijit to pick from more than two basemaps.

All basemaps added to the gallery need to have the same spatial reference. If the default ArcGIS.com basemaps are used then all additional items added to the gallery need to be in Web Mercator (wkids: 102100, 102113 and 3857). If the default basemaps are not used you can add basemaps in any spatial reference as long as all the items added to the gallery share that spatial reference. To achieve the best performance, it is recommended that all basemaps added to the gallery are cached (tiled) layers.

Note: At version 3.7 (only) the basemap toggle does not work with maps created from web maps using createMap.

Samples

Search for samples that use this class.

Constructors

NameSummary
new BasemapToggle(params, srcNodeRef)Creates a new BasemapToggle dijit using the given DOM node.

CSS

esri/dijit/BasemapToggle | Download source

NameDescription
basemapContainerContaining class for the widget's node.
basemapImageClass put onto the basemap image.
basemapTitleClass put onto the basemap div that holds the label of the basemap.
toggleButtonClass for the button.

Properties

NameTypeSummary
basemapStringThe secondary basemap to toggle to.
basemapsObjectObject containing the title and thumbnailURL for the image of each basemap.
loadedBooleanWhether the widget has been loaded.
mapMapMap object that this dijit is associated with.
themeStringClass used for styling the widget.
visibleBooleanWhether the widget is visible by default.

Methods

NameReturn typeSummary
destroy()NoneDestroys the widget.
hide()NoneHides the widget.
show()NoneShows the widget.
startup()NoneFinalizes the creation of this dijit.
toggle()NoneToggles to the next basemap.

Events

[ On Style Events | Connect Style Event ]
All On Style event listeners receive a single event object. Additionally, the event object also contains a 'target' property whose value is the object which fired the event.

Events

NameEvent ObjectSummary
loadFires when the widget has been loaded.
toggle
{
  currentBasemap: <String>,
  error: <Object>,
  previousBasemap: <String>
}
Fires when the toggle method has been called.
Constructor Details

new BasemapToggle(params, srcNodeRef)

Creates a new BasemapToggle dijit using the given DOM node.
Parameters:
<Object> params Required Various parameters to configure this dijit. See the list below for details.
<Node | String> srcNodeRef Required Reference or id of a HTML element that this dijit is rendered into.
params properties:
<String> basemap Optional The secondary basemap to toggle to. Default value is "hybrid".
<Object> basemaps Optional Object containing the labels and URLs for the image of each basemap. Refer to the basemap property for syntax.
<Map> map Required Map object that this dijit is associated with. Required.
<String> theme Optional Class used for styling the widget. Default value is "BasemapToggle".
<Boolean> visible Optional Whether the widget is visible by default. Default value is true.
Sample:
var basemapToggle = new BasemapToggle({
  theme: "basemapToggle",
  map: map,
  visible: true,
  basemap: "hybrid"
}, "<dom_id>");
basemapToggle.startup();
Property Details

<String> basemap

The secondary basemap to toggle to. The "terrain" and "dark-gray" options were added at v3.12. The "dark-gray-vector", "gray-vector", "streets-vector", "streets-night-vector", "streets-relief-vector", "streets-navigation-vector" and "topo-vector" options were added at v3.16.

NOTE: Basemap objects created using the esri/basemaps class may also be passed as values to this property.

Known values: "streets" | "satellite" | "hybrid" | "topo" | "gray" | "dark-gray" | "oceans"| "national-geographic" | "terrain" | "osm" | "dark-gray-vector" | "gray-vector" | "streets-vector" | "streets-night-vector" | "streets-relief-vector" | "streets-navigation-vector" | "topo-vector"
Default value: "hybrid"

<Object> basemaps

Object containing the title and thumbnailURL for the image of each basemap.
Sample:
{
  "streets":{
    "title":"Streets",
    "thumbnailUrl":"https://js.arcgis.com/3.15/esri/images/basemap/streets.jpg"
  },
  "satellite":{
    "title":"Satellite",
    "thumbnailUrl":"https://js.arcgis.com/3.15/esri/images/basemap/satellite.jpg"
  },
  ...
}

<Boolean> loaded

Whether the widget has been loaded.
Known values: true | false

<Map> map

Map object that this dijit is associated with.

<String> theme

Class used for styling the widget.
Default value: "BasemapToggle"

<Boolean> visible

Whether the widget is visible by default.
Known values: true | false
Default value: true
Method Details

destroy()

Destroys the widget.

hide()

Hides the widget.

show()

Shows the widget.

startup()

Finalizes the creation of this dijit. This method should be called after the constructor for this dijit is called and before letting the users interact with it.

toggle()

Toggles to the next basemap.
Event Details
[ On Style Events | Connect Style Event ]

load

Fires when the widget has been loaded.

toggle

Fires when the toggle method has been called.
Event Object Properties:
<String> currentBasemap The basemap that has been switched to.
<Object> error An error objection. Returned if an error has occurred.
<String> previousBasemap The basemap that was switched from.