Get started with widgets using BasemapToggle

Working with widgets is an essential part of the ArcGIS API for JavaScript. Typically, a widget is thought of as a piece of the API that encapsulates a specific set of functionality. The API provides ready-to-use widgets with predefined functionality, some of which includes:

• locating your current location on a map via the Locate widget,
• adding a legend to help visualize your map using the Legend widget,
• show a list of layers to provide users an easy way toggle them on/off with the LayerList widget,
• or searching for features and locations within the map using the Search widget.

For a full listing of all available widgets, see the esri/widgets folder in the API reference.

Some widgets are automatically made available to the MapView and SceneView by default, whereas others need to be manually added into the application. The Zoom widget is an example of one that is automatically added as part of the View. Although the Zoom widget is added by default, it may not make sense for all of the widgets to be turned on automatically. For example, the Zoom widget provides functionality which is pretty standard and used throughout applications, regardless of what the application's main purpose may be. Whereas, having the View automatically add a widget like Locate would not make sense unless there was a specific need to have geolocation functionality within the application.

With all of this said, the fundamental concepts of working with widgets are consistent across the board, regardless of the widget being used. These concepts are:

1. Create and instantiate the widget
2. Set the properties of the widget

This tutorial will show you how to add a BasemapToggle widget to a MapView. This widget allows you to switch between two basemaps in a single View. The toggled basemap is set inside the view's map object. This tutorial will touch on the three main points stated above.

Prior to completing the following steps, you should be familiar with views and Map. If necessary, complete the following tutorials first:

• Get started with MapView
• Get started with SceneView

1. Create a simple Map and set it in the MapView

First create a simple Map and reference it in a View. Your JavaScript may look something like the code below:

require([
  "esri/Map",
  "esri/views/MapView",
  "dojo/domReady!"
], function(
  Map,
  MapView
) {

  // Create the Map with an initial basemap
  var map = new Map({
    basemap: "topo"
  });

  // Create the MapView and reference the Map in the instance
  var view = new MapView({
    container: "viewDiv",
    map: map,
    center: [-86.049, 38.485],
    zoom: 3
  });

2. Create the BasemapToggle widget and set its properties

Next, create an instance of the BasemapToggle widget and set its view and nextBasemap properties.

The view property can be either a MapView or SceneView. It provides the BasemapToggle widget access to the initial basemap in which you can toggle via the View's map property.

The nextBasemap property sets the basemap for toggling. This property accepts either:

• The string ID of any Esri basemap. For example, some possible values are: 'streets, 'hybrid', 'topo', etc.
• A custom Basemap object. For example, let's say you have a custom tiled service published on your own server (or a third party's server) you wish to use. You can specify this here as well.

For the purpose of this tutorial, we will specify a string ID, hybrid. Setting the properties finalizes the widget's creation.

Your JavaScript code should look similar to what is below:

var view = new MapView({
  container: "viewDiv",
  map: map,
  center: [-86.049, 38.485],
  zoom: 3
});

// 1 - Create the widget
var toggle = new BasemapToggle({
  // 2 - Set properties
  view: view, // view that provides access to the map's 'topo' basemap
  nextBasemap: "hybrid" // allows for toggling to the 'hybrid' basemap
});

3. Position the widget in the View

Lastly, we need to specify where this widget should be positioned within the View's UI property. This property exposes the default widgets available in the view and allows you to toggle them on and off. In addition to this, you can specify where you would like to position these widgets. The UI property inherits off of the DefaultUI. This class provides methods where you can add, move, or remove widgets. In this specific case, we will add the BasemapToggle widget to the top right corner of the view.

Your JavaScript code should look similar to what is below:

// Add widget to the top right corner of the view
view.ui.add(toggle, "top-right");

Now you have a simple map showing how to work with the BasemapToggle widget. We demonstrated the two essential parts of widget creation: instantiation and setting properties. In addition to docking and placement within the View.

Your final JavaScript code should look like the following:

require([
  "esri/Map",
  "esri/views/MapView",
  "dojo/domReady!"
], function(
  Map,
  MapView
) {

  // Create the Map with an initial basemap
  var map = new Map({
    basemap: "topo"
  });

  // Create the MapView and reference the Map in the instance
  var view = new MapView({
    container: "viewDiv",
    map: map,
    center: [-86.049, 38.485],
    zoom: 3
  });

});

// 1 - Create the widget
var toggle = new BasemapToggle({
  // 2 - Set properties
  view: view, // view that provides access to the map's 'topo' basemap
  nextBasemap: "hybrid" // allows for toggling to the 'hybrid' basemap
});

// Add widget to the top right corner of the view
view.ui.add(toggle, "top-right");