The Basemap Gallery widget presents a gallery of basemaps and allows you to select one from the gallery as the basemap for your app. The basemap can be user defined or from your organization or portal. However, all basemaps added to the Basemap Gallery widget must have the same spatial reference. In addition, you have the option to synchronize the app at run time with the Basemap Gallery setting in your organization or portal.
In general, basemaps with tiling schemes that are different than those of the current basemap are excluded from the widget. If the default basemap is a dynamic layer, you can switch to either dynamic layers or ArcGIS tiled map service layers. If the default basemap is a tile layer, you can switch to either tile layers with the same tiling scheme or dynamic layers. For the best performance, it is recommended that all basemaps added to the gallery be cached (tiled) layers.
See the following list of supported and unsupported basemaps in the Basemap Gallery widget:
- Unsupported basemaps
- Different spatial reference
- Tiled basemaps with different tiling schemes
- Switch from a dynamic basemap to Bing, OSM, or WMTS
- Switch from a dynamic basemap to a tiled image service basemap
- WMS services
- Supported basemaps
- Switch between tiled basemaps
- Switch between dynamic basemaps
- Switch from a dynamic basemap to a tiled map service basemap
- Switch from a tiled basemap to a dynamic basemap
Configure the Basemap Gallery widget
This widget can be set to open automatically when
an app starts. Hover over the widget and click the Do not open this widget when
the app starts button 
to change the setting to Open this widget automatically when the app starts. (For widgets that you need to add to the app first, you can turn on this option after configuring the widget.)
- Hover over the widget and click the Configure this widget button
to open the configuration window.Note:
If you need to add the widget to the app first, click a widget placeholder on the Widget tab. In the Choose Widget window that opens, select the widget and click OK.
- Optionally, click the Change widget icon button to replace the default icon for this widget.
A File Explorer window appears, allowing you to browse to a local image file to use as the widget icon.
- If you want the app to be consistent with the Basemap Gallery setting in your organization or portal at run time, keep the default option, Always synchronize with the Basemap Gallery setting of the organization.
- Alternatively, select Configure custom basemaps, which allows you to import the basemap from a group or create a basemap.
- Click Import. When the Import Basemaps window appears, choose a group from the drop-down menu and click the maps you want to add to the widget. Click OK to close the window. Repeat this step to add more basemaps from different groups.
- (This option has been deprecated.) Click Create New. When the Create New window appears, provide a title and the URL of your map service, and click the thumbnail image to replace it with your own image file. Click Add URL to add an additional URL of a map service to the basemap if needed. Click OK to close the window. Repeat this step to create additional basemaps.
The basemaps you configured are listed with the selected thumbnails.
Caution:
Although a single basemap can contain multiple layers or services, the layers must have the same spatial reference.
- Click OK to close the window.
Caution:
Basemaps added to the Basemap Gallery widget must have the same spatial reference.
The basemaps from your organization or portal display on the configuration dialog box with the default Always synchronize with the Basemap Gallery setting of the organization option.
Caution:
Although the basemaps from your organization or portal Basemap Gallery can have different spatial references, the configuration window only displays basemaps with the same spatial reference as the web map currently loaded in ArcGIS Web AppBuilder. This is a known limitation.
Use the Basemap Gallery widget
Clicking the Basemap Gallery widget displays all the basemaps configured for this widget. Clicking a basemap thumbnail sets it as the active basemap for the app. Click the x in the upper right corner of the Basemap Gallery window to close it.
Note:
If the basemap used in the web map is not included during the configuration, it will be added automatically when the widget opens.