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, the easiest way to build an application that allows users to switch between basemaps is to use the basemap widgets.

In this tutorial, you will use the ArcGIS API for JavaScript BasemapToggle and BasemapGallery widgets 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 JavaScript Tutorials: Select a basemap.

Toggle a basemap

One of the easiest ways to enable selection between two basemaps is to use the BasemapToggle widget. In this step you will configure the widget to toggle between the Topographic and Satellite basemaps.

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

        require([
          "esri/Map",
          "esri/views/MapView",
          //*** ADD ***//
          "esri/widgets/BasemapToggle",
          "esri/widgets/BasemapGallery"
        ], function(Map, MapView, BasemapToggle, BasemapGallery) {
    
  2. At the end of the code in the main function, create a BasemapToggle widget. Set the view and the nextBasemap property to satellite.

          var basemapToggle = new BasemapToggle({
            view: view,
            nextBasemap: "satellite"
          });
    
  3. Then add the widget to the bottom right corner of the view by adding it to the view's DefaultUI.

          view.ui.add(basemapToggle, "bottom-right");
    
  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 https://wwww.arcgis.com and set [useVectorBasemaps](../../../latest/api-reference/esri-portal-Portal.html#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).

          var basemapGallery = new BasemapGallery({
            view: view,
            source: {
              portal: {
                url: "https://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.

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

Congratulations, you're done!

Your app should look something like this.

Challenge

Load raster tile basemaps

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

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