I'm trying to upgrade my app from version 3.3 to version 3.7 of the ArcGIS JavaScript API and am switching out the basemap gallery for the new BasemapToggle widget.

I have two custom basemaps that I want to use in my app using BasemapToggle.

Is this possible?

The API homepage suggests it is but I haven't seen a sample or any documentation on how to do it properly.

Can anybody point me towards a solution or example of how to use my own basemaps with this widget?

I'm trying to do this with two basemaps, loading one of them as the initial basemap and then being able to toggle between them. My attempt at Derek's answer is HERE

  • Adding a comment here so you can check out my edited answer below showing how to use a custom basemap with the basemap toggle. Oct 16, 2013 at 16:57
  • @DerekSwingley thanks again. I've been trying it out so that it uses 2 custom basemaps and loads one of them from the start as well. No luck yet but I'm sure I'll get there.
    – Craig
    Oct 16, 2013 at 17:00
  • edit your question to include your code or the URLs for the services you want to use? Maybe I can sort it out for you. Oct 16, 2013 at 17:43
  • @DerekSwingley Please see my edit above. Thanks for the help.
    – Craig
    Oct 16, 2013 at 18:05
  • try this: jsbin.com/iFakeLa/5 Oct 16, 2013 at 19:30

2 Answers 2


The BasemapToggle can only use basemaps from arcgis.com. I'll get the text on the page you referenced updated, it shouldn't say you can use your own custom basemaps. I apologize for the mistake.

It is possible to use custom maps with the basemap toggle, but it takes a little work. First, load the default API config object and put info for your basemaps on esriConfig.defaults.map.basemaps:

], function(
  Map, BasemapToggle, esriConfig
)  {
  esriConfig.defaults.map.basemaps.delorme = {
    baseMapLayers: [
      { url: "http://services.arcgisonline.com/ArcGIS/rest/services/Specialty/DeLorme_World_Base_Map/MapServer" }
    title: "Delorme"

Then specify both basemap and basemaps when you create the toggle:

toggle = new BasemapToggle({
  map: map,
  basemap: "delorme",
  basemaps: {
    delorme: {
      label: "delorme",
      url: "http://www.delorme.com/images/homepage/dbm_icon.jpg"
    }, topo: {
      label: "topo",
      url: "http://js.arcgis.com/3.7/js/esri/dijit/images/basemaps/topo.jpg"
}, "BasemapToggle");

Working page on jsbin: http://jsbin.com/iFakeLa/1

  • 1
    Sounds like a prime item for a enhancement; we were looking at that ourselves...
    – D.E.Wright
    Oct 11, 2013 at 22:56
  • Thanks Derek. Perhaps this could get worked into the next update.
    – Craig
    Oct 12, 2013 at 14:06
  • 2
    @D.E.Wright updated to show an example of how to customize the widget to use custom maps Oct 14, 2013 at 20:50
  • see my answer below for an update for newer versions of the JS API Jun 8, 2016 at 2:02

It appears that Derek's answer above no longer works at version 3.16 of the JS API.

An update came from Kelly Hutchins at Esri, and is to add the custom basemap to esri/basemaps as shown at https://developers.arcgis.com/javascript/3/jsapi/esri.basemaps-amd.html

  ], function (esriBasemaps, Map){
    esriBasemaps.delorme = {
      baseMapLayers: [{url: "https://services.arcgisonline.com/ArcGIS/rest/services/Specialty/DeLorme_World_Base_Map/MapServer"}],
      thumbnailUrl: "https://www.example.com/images/thumbnail_2014-11-25_61051.png",
      title: "Delorme"

    var map = new Map("ui-map", {
      basemap: "delorme",
      center: [-111.879655861, 40.571338776], // long, lat
      zoom: 13,
      sliderStyle: "small"

Once the custom basemap has been added to esri/basemaps it can be used in the basemapToggle in the same manner as a default basemap:

    var toggle = new BasemapToggle({
      map: map,
      basemap: "satellite",

    }, "BasemapToggle");

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.