Select a basemap

Overview

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

Applications can access and display raster and vector tile basemaps hosted onArcGIS OnlineorArcGIS Enterprise. Applications can also display basemap layers that you design with theArcGIS Online. To build an application that can switch between basemaps, you can use the BasemapToggle or the BasemapGallery widget. The BasemapToggle widget allows you to switch between two basemaps that you define while the BasemapGallery widget allows you to select from a number of basemaps that belong to an ArcGIS Online group. You can use a group of basemaps hosted by Esri or a group that you have composed specifically for your application. To learn more about designing and styling your own basemaps, visit the Style a vector basemap tutorial.

In this tutorial, you will use the BasemapToggle and the BasemapGallery widget to select and display basemaps hosted in ArcGIS Online.

Click the widget below to change basemaps.

Steps

Create a starter app

1. Open the JavaScript Starter App on CodePen.

2. In CodePen, click Fork and save the pen as ArcGIS API for 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 modules.

       require([
         "esri/Map",
         "esri/views/MapView",
         "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 fromArcGIS 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 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

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