I'm trying to make a map using the Javascript API.

I want to use my own basemap, but I can't find the most simple code to do this.

I always see something like this:

  function init() {
    map = new esri.Map("mapDiv", {
      basemap: "satellite",
      center: [-97.395, 37.537],
      zoom: 11

But I don't want to use the ArcGIS online basemaps.

What is the code to make a map service I am hosting my basemap?

  • 1
    have you created tiles from your own basemap?
    – Mapperz
    Commented Mar 15, 2013 at 1:40

3 Answers 3


The API Reference for the Map Class says the following:

The following are valid options: "streets" , "satellite" , "hybrid", "topo", "gray", "oceans", "national-geographic", "osm". As of version 3.3

You should instead, just define a new ArcGIS Tiled Map Service Layer and use it as follows:

var baseMapLayer = new esri.layers.ArcGISTiledMapServiceLayer("your URL");
  • 1
    @StephenLead setBasemap only accepts string parameter, so it will not work!
    – digz6666
    Commented Oct 25, 2017 at 10:57
  • 2
    @digz6666 oops, I think you're right. I'll delete that comment Commented Oct 25, 2017 at 22:06
  • 2
    @StephenLead I've found a way. I will post as an answer. Oops it requires 10 rep points to answer this, damn :)
    – digz6666
    Commented Oct 27, 2017 at 1:32
  • @digz6666: You should not need 10 Reps to create an answer. See gis.stackexchange.com/help/privileges Commented Oct 27, 2017 at 5:19

For arcgis javascript SDK version 3.x you can use esri/basemaps class to declare and register custom basemaps and use with your map: https://developers.arcgis.com/javascript/3/jsapi/esri.basemaps-amd.html

Declare and register custom basemap:

Basemaps.mybasemap = {
  title: 'My custom basemap',
  thumbnailUrl: 'https://js.arcgis.com/3.22/esri/images/basemap/satellite.jpg',
  //itemId: 'ulas',
  baseMapLayers: [
    { url: "https://services.arcgisonline.com/ArcGIS/rest/services/Specialty/DeLorme_World_Base_Map/MapServer" }

Use custom basemap in map constructor:

var map = new Map("mapDiv", {
  basemap: "mybasemap",
  center: [-122.69, 45.52],
  zoom: 3

Or you can apply your custom basemap to existing map:


Full code example: https://codepen.io/digz6666/pen/wPwPbW

For arcgis javascript SDK version 4.x you can use esri/Basemap.

Declare base map layer and base map:

var baseLayer = new MapImageLayer({
  url: "https://services.arcgisonline.com/ArcGIS/rest/services/Specialty/DeLorme_World_Base_Map/MapServer"
var myBasemap = this.esri.basemap({
  baseLayers: [baseLayer],
  title: 'My custom basemap',
  id: 'my_custom_basemap'

Apply basemap to existing map object:

map.basemap = myBasemap;

You don't have to specify a built-in basemap. Add your custom basemap as a layer like so.

var map;
require(["esri/map", "esri/layers/ArcGISTiledMapServiceLayer", "dojo/domReady!"],
function (Map, ArcGISTiledMapServiceLayer ) {
    map = new Map("map", {                
        center: [-76.756, 40.241],
        zoom: 8
    var customBasemap = new ArcGISTiledMapServiceLayer(

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