Hide Table of Contents
What's New archive
Default API Configurations

The ArcGIS JavaScript API has default options that can be overridden. The defaults for all configuration options are stored in the esri/config module. To modify a default, load that module, alias it as esriConfig and update the property on that object to the desired value.

require(["esri/config"], function(esriConfig) {
  // update esriConfig properties here to override defaults
});

One common change is to modify the symbol used for the map's zoom box. In the code below, a new symbol is created, converted to a JSON object and then set as the map's default zoom symbol.

// AMD
require([
  "esri/config",
  "esri/symbols/SimpleFillSymbol", "esri/symbols/SimpleLineSymbol", "dojo/_base/Color"
], function(
  esriConfig,
  SimpleFillSymbol, SimpleLineSymbol, Color
) {
  var lineColor = new Color([0,0,255]);
  var fillColor = new Color([255,255,0,0.5]);
  var zoomSymbol = new SimpleFillSymbol(
    SimpleFillSymbol.STYLE_SOLID,
    new SimpleLineSymbol(SimpleLineSymbol.STYLE_DASHDOT, lineColor, 2),
    fillColor
  );
  esriConfig.defaults.map.zoomSymbol = zoomSymbol.toJson();
});

// legacy
var zoomSymbol = new esri.symbol.SimpleFillSymbol(
  esri.symbol.SimpleFillSymbol.STYLE_SOLID,
  new esri.symbol.SimpleLineSymbol(
    esri.symbol.SimpleLineSymbol.STYLE_DASHDOT,
    new dojo.Color([0,0,255]),
    2
  ),
  new dojo.Color([255,255,0,0.5]));
esri.config.defaults.map.zoomSymbol = zoomSymbol.toJson();

Below are the configuration property names and default values for the JavaScript API:

esriConfig.defaults.geometryService

Specify the default geometry service used by widgets and operations. (As of 2.2)

esriConfig.defaults.geometryService = new GeometryService("http://yourdomain.com/geometryService");

esriConfig.defaults.io.alwaysUseProxy

Whether or not to always use the proxy for communication to a REST endpoint.

esriConfig.defaults.io.alwaysUseProxy = true;
Default: false

esriConfig.defaults.io.corsDetection

Whether or not to detect support for cross-origin resource sharing (CORS). Setting this to false will stop the API from sending requests that result in "XMLHttpRequest cannot load http://some.url.com/ArcGIS/rest/info?f=json. Origin http://yourapp.com is not allowed by Access-Control-Allow-Origin." messages in browser developer tools but it will also prevent the API from discovering that a resource supports CORS if it is not explicitly added to esriConfig.defaults.io.corsEnabledServers.

Default: true

esriConfig.defaults.io.corsDetectionTimeout

Number of seconds to wait for response from the ArcGIS Server during CORS detection. If the detection is not complete before this time expires, then it is assumed that the server does not support CORS. Applicable when corsDetection is true.

Default: 15

esriConfig.defaults.io.corsEnabledServers

Add URLs for servers with cross-origin resource sharing enabled to this array. Cross-Origin Resource Sharing (CORS) allows web applications to bypass the browser's same origin policy file and access resources or services on different servers/domains. Starting with version 3.25, all arcgis.com domains, (i.e. *.arcgis.com), are automatically added to the list. It is no longer necessary to specify individual ArcGIS.com domains. Also, when both the web server and browser support CORS, esri.request will not use a proxy to perform cross-domain requests. The API includes some Esri servers by default so it's important to push items on to this array rather than overwriting it.

require(["esri/config"], function(esriConfig) {
  esriConfig.defaults.io.corsEnabledServers.push("servicesbeta.esri.com");
  esriConfig.defaults.io.corsEnabledServers.push("server.organization.com");
});

At version 3.14, support was added for sending AJAX requests with credentials. corsEnabledServers can now contain objects with host and withCredentials properties.

require(["esri/config"], function(esriConfig) {
esriConfig.defaults.io.corsEnabledServers.push({
  host: "server.organization.com",
  withCredentials: true
})
});

At version 2.8, the list contains the following servers by default:

"www.arcgis.com",
"tiles.arcgis.com",
"services.arcgis.com"

At version 3.1 the following domains were added to the list:

"static.arcgis.com",
"utility.arcgisonline.com",
"geocode.arcgis.com"

At version 3.3 the following domains were added to the list:

"services1.arcgis.com",
"services2.arcgis.com",
"services3.arcgis.com"

At version 3.6 the following domain were added to the list:

"geoenrich.arcgis.com"

At version 3.15 the following domain were added to the list:

"basemaps.arcgis.com"

At version 3.21 the following domain were added to the list:

"utility.arcgis.com"

The specified web servers must be pre-configured to support CORS. Visit enable-cors.org for details on how to enable this for popular web servers.

esriConfig.defaults.io.httpsDomains

List of domain suffixes known to support https. This will automatically upgrade requests made to such domains to use https instead of http when the application is not running on http. Note that port numbers should not be included in the domain suffix to be matched.

Since version 3.19, the list includes the following domain suffixes by default:

"arcgis.com",
"arcgisonline.com"

esriConfig.defaults.io.proxyRules

A proxy rule defines a proxy for set of resources with identical URL prefix. When using esri/request, if a target URL matches a rule, then the request will be sent to the specified proxy. Rather than populating this array directly, use the API's addProxyRule method. Rule objects have the following properties:

  • proxyUrl: URL for the proxy.
  • urlPrefix: URL prefix for resources that need to be accessed through a specific proxy.

esriConfig.defaults.io.proxyUrl

The location of the proxy url that should be used when posting large payloads to an endpoint. This must reside on the same domain as the HTML application.

esriConfig.defaults.io.proxyUrl = "/arcgisserver/apis/javascript/proxy/proxy.ashx";
Default: null

esriConfig.defaults.io.timeout

Each request through esri.request is allowed up to 60000 milliseconds (i.e., 60 seconds) to respond. If no response is returned or a server-side error is returned, the esri.Error and error back handlers are called, in that order. (As of 1.3)

Default: 60000 milliseconds

esriConfig.defaults.io.useCors

Whether or not requests made via esri/request should try to use CORS. If true, make direct AJAX requests to servers that support CORS. If using "with-credentials", set withCredentials flag where applicable. Lastly, if false, do not make direct requests. A proxy will be used if available.

Default: "with-credentials"

esriConfig.defaults.kmlService

This is used by the KMLLayer. The URL of the kml utility service other than the one hosted by ArcGIS.com. (Requires Portal for ArcGIS)

esriConfig.defaults.kmlService = "http://servername.domain.suffix/arcgis/sharing/kml";
Default: null

esriConfig.defaults.geoRSSService

This is used by the GeoRSSLayer. The URL of the geoRSS utility service other than the one hosted by ArcGIS.com. (Requires Portal for ArcGIS)

esriConfig.defaults.geoRSSService = "http://servername.domain.suffix/arcgis/sharing/rss";
Default: null

esriConfig.defaults.map.basemaps

This object was removed in v3.12 of the API. Use esri/basemaps instead.

esriConfig.defaults.map.panDuration

The length of time in milliseconds that the map will take to pan from one extent to another.

Default: 350

esriConfig.defaults.map.panRate

The length of time in milliseconds that the map will refresh as it pans to the next extent.

Default: 25

esriConfig.defaults.map.slider

The parameters that define the location, size, and orientation of the slider.

As of version 3.3, the recommended approach is to use a combination of CSS and map constructor options to customize a map's slider or zoom buttons.

Default: {left:"30px",top:"30px",width:null,height:"200px"}

esriConfig.defaults.map.sliderLabel

The parameters that define the slider tick and accompanying tick label. If this is null then the slider will not show tick marks.

As of version 3.3, the recommended approach is to use a combination of CSS and map constructor options to customize a map's slider or zoom buttons.

Default: {tick:5,labels:null,style:"width:2em; font-family:Verdana; font-size:75%;"}

esriConfig.defaults.map.zoomAnimationThrottled

Indicates whether to disable throttling during zoom animations. Setting this to false may be needed on slow/throttled networks to avoid any display issues while zooming.

Default: true

esriConfig.defaults.map.zoomDuration

The length of time in milliseconds that the map will take to zoom from one extent to another.

Default: 500

esriConfig.defaults.map.zoomRate

The length of time in milliseconds that the map will refresh as it zooms to the next extent.

Default: 25

esriConfig.defaults.map.zoomSymbol

The SimpleFillSymbol to use to represent the color, fill, and outline properties of the RubberBand zoom. This is the JSON representation of the SimpleFillSymbol.

Default: {color:[0,0,0,64],outline:{color:[255,0,0,255],width:1.5,style:"esriSLSSolid"},style:"esriSFSSolid"}

esriConfig.defaults.workers.loaderConfig

Modify the configuration to specify locations of packages to be loaded with the workers or to define feature detections. (As of 3.20)

esriConfig.defaults.workers.loaderConfig = {
  paths: {
    dojo: "https://ajax.googleapis.com/ajax/libs/dojo/1.11.2/dojo/"
  },
  packages: [{
    name: "primes",
    location: window.location.href.replace(/\/[^/]+$/, "/lib"),
    main: "primes"
  }],
  has: {
    "dojo-debug-messages": true
  }
};
Show Modal