Overview

You will learn: how to build an app to interactively select and display an ArcGIS Online basemap.

ArcGIS Online provides a wide variety of ready-to-use basemaps that you can use in your applications. These basemaps are hosted and maintained by Esri and are stored as tile layers. The tile layers are grouped together by their format and data source type: Raster tile basemaps and Vector tile basemaps. Although you can always load each tile layer individually as an item, the easiest way to build an application to select more than one is to access the group that contains the raster or vector basemaps, retrieve the basemap details e.g. title and thumbnail, and then create a user interface to select and load each one. In this example we will load the default basemaps in the ArcGIS organization, but if you want to learn how to create your own group (gallery) of basemaps for your organization, please visit the documentation.

In this lab, you will use the ArcGIS API for JavaScript BasemapToggle and BasemapGallery widget to allow users to select and display basemaps hosted in ArcGIS Online.

Steps

Create a starter app

  1. Go to the JavaScript Starter App.

  2. In CodePen, click Fork and save the pen as ArcGIS DevLabs: Select a basemap.

Toggle a basemap

One of the easiest ways to select a new basemap is to use the BasemapToggle widget. This widget gives you the ability to toggle back and forth between two different basemaps. In this step you will configure the widget to toggle between the Topo and Satellite basemap.

  1. In the require statement, add a reference to the BasemapToggle and BasemapGallery module. The second module will be used in a later step.

    require([
      "esri/Map",
      "esri/views/MapView",
      //*** ADD ***//
      "esri/widgets/BasemapToggle",
      "esri/widgets/BasemapGallery",
      "dojo/domReady!"
      //*** ADD ***//
    ], function(Map, MapView, BasemapToggle, BasemapGallery) {
    
  2. In the main function, create a BasemapToggle widget. Set the view and the secondBasemap property to satellite.

      //*** ADD ***//
      var basemapToggle = new BasemapToggle({
        view: view,
        secondMap: "satellite"
      });
    
  3. Add the widget to the bottom right corner of the view by adding it to the view's DefaultUI.

      //*** ADD ***//
      view.ui.add(basemapToggle, "bottom-right"); // Add to the view
    
  4. Run the app and try switching between basemaps.

Select a basemap from an ArcGIS Online group

Another way to select a basemap is to use the BasemapGallery widget. In this step you will use the widget to load basemaps from an ArcGIS Online group so users can select and display them.

  1. In the main function, comment out the BasemapToggle widget code.

  2. In the main function, create a BasemapGallery widget and configure it to load basemaps from ArcGIS Online. Set the view to the active view and set the source to the ArcGIS Online portal. Set the url to http://wwww.esri.com and set useVectorBasemaps to true so it loads the basemaps from the vector tile group. If you set this value to false it will load the raster tile basemap group (see challenge step).

     //*** ADD ***//
     var basemapGallery = new BasemapGallery({
        view: view,
        source: {
          portal: {
            url: "http://www.arcgis.com",
            useVectorBasemaps: true  // Load vector tile basemaps
          }
        }
      });
    
  3. Add the widget to the top right corner of the view by adding it to the view's DefaultUI.

      //*** ADD ***//
      view.ui.add(basemapGallery, "top-right"); // Add to the view
    
  4. Run the app and try switching between the different basemaps.

Congratulations, you're done!

Your app should look something like this.

If you would like to learn how to create your own custom vector basemap style, please see the Style a vector basemap lab.

Challenge

Load raster tile basemaps

Try changing the userVectorBasemaps property to false so that the raster tile basemaps are loaded into the BasemapGallery widget.

  var basemapGallery = new BasemapGallery({
     view: view,
     source: {
       portal: {
         url: "http://www.arcgis.com",
         //*** ADD ***//
         useVectorBasemaps: false  // Load raster tile basemaps
       }
     }
   });