Release notes for 4.6

December 2017

Directions widget (Beta release)

Routing is now made simpler with the help of the Directions widget. This widget calculates directions between two or more locations and makes it easy to add turn-by-turn directions to a page as well as a route to a map. The widget takes care of encapsulating routing functionality into an easy-to-use widget with an already defined default user interface. The widget defaults to the ArcGIS Online route service but can be configured to use any ArcGIS Server Network Analyst routing service. To explore further, see the Directions sample.


Currently, the widget is still in its beta version. It does not yet have full parity to the functionality provided in the 3.x Directions widget. Additional functionality is scheduled in a future release.

DirectLineMeasurement3D widget

Measuring the vertical, horizontal, and direct distance between two points is now possible with the DirectLineMeasurement3D widget. When the widget is active, a horizontal "laser" line is drawn which indicates the height at the current mouse position. This line can help in analyzing the heights of objects relative to each other and the terrain.


The Direct line measurement in 3D sample shows how to use this widget.

Fullscreen widget

Fullscreen widget can be used to present the View or a user-defined HTMLElement using the entire screen. To see this widget in action, please refer to the Animate opacity visual variable and Animate color visual variable samples.

Improved compatibility with JavaScript promises

Numerous classes in the API resolve to promises. This is the case for WebMap and WebScene, MapView and SceneView, Basemap, Ground, layers and layerviews.

Prior to 4.6, you needed to call the then() method on classes to ensure a view or layer was ready prior to executing specific code.

At 4.6, then() is deprecated in favor of when(). The then() method will still be honored at 4.6, but will throw warning messages in the browser developer console, to ease the process of updating apps to using when(). We made this change to allow the use of native ES6 promises within the context of the ArcGIS Maps SDK for JavaScript.

Read more about this change on the dedicated blog post.

In a future 4.x version, in 2018, then() will be removed from all applicable classes, making this a breaking change.

4.0 - 4.5AvailableNot available
4.6Deprecated (warning messages)Available
Future 4.x versionNot availableAvailable

Prior to 4.6, then() was used with resolved promises.

Use dark colors for code blocksCopy
view.then(function() {
  // do something with loaded view properties here

At 4.6, then() is deprecated in favor of when().

Use dark colors for code blocksCopy
view.when(function() {
  // do something with loaded view properties here

While when() should be used at 4.6 on all applicable classes, you must specify the following has flag prior to loading the ArcGIS Maps SDK for JavaScript for your app to be compatible with native promises. This flag will also prevent the warning messages from appearing in the console if still using then():

Use dark colors for code blocksCopy
  var dojoConfig = {
    has: {
      "esri-promise-compatibility": 1

Additionally this change will allow you to take advantage of async/await alongside the ArcGIS Maps SDK for JavaScript to write asynchronous code that looks synchronous:

Use dark colors for code blocksCopy
var map = new WebMap({
  portalItem: {
    id: "someid"

await map.load();
// the code waits for map to load

var view = new MapView({
  container: "viewDiv",
  map: map

await view.when();
// do something with the view

Layer refreshing

Most layers now can be refreshed in 2D MapViews by setting refreshInterval property or by calling refresh() method on it.

Smart Mapping updates

At 4.6, the following capabilities are now available as a part of the Smart Mapping modules:

Generate class breaks

KMLLayer updates

  • KMLLayer now supports viewing KML data in any view projection.
  • Added the KMLLayerView class and moved the allVisibleMapImages, allVisiblePoints, allVisiblePolygons, and allVisiblePolylines from KMLLayer to KMLLayerView.
  • Removed mapImages, points, polygons, and polylines from KMLSubLayer.

MapImage is only supported when the MapView's spatial reference is WGS84 (wkid: 4326).

2D WebGL-rendered FeatureLayer progress

FeatureLayers are now rendered with WebGL by default as of version 4.9.

We're continuing to improve the user experience for the 2D WebGL-rendered version of FeatureLayer, which is still in beta. In 4.6, some of the processing in the layer has moved to workers using the API's workers framework. We'll continue improving the performance of FeatureLayer with the intention of making WebGL the default method of rendering features in a future release.

3DObject SceneLayers and IntegratedMesh layer updates

Scene layer performance has significantly improved in this release. Buildings and integrated mesh scene layers now load up to 50% faster and follow the correct front-to-back displaying order. To help you get started with scene layers, there is a new guide topic on Working with scene layers.

Updated vector basemaps

The named vector basemaps have been updated to use the new v2 vector tile basemaps from Esri. This affects dark-gray-vector, gray-vector, streets-vector, streets-night-vector, streets-relief-vector, streets-navigation-vector and topo-vector.

Support for Slovenian locale

Version 4.6 adds support for the Slovenian (sl) locale. See Localization topic for more information about using different locales.

Draw updates

TypeScript declaration file improvements

The TypeScript declaration file for the ArcGIS Maps SDK for JavaScript describes the shape of the API to TypeScript. Learn more about how to install this file from the dedicated guide page or on GitHub.

Version 4.6 introduces several improvements:

  • JSDoc definitions for classes, methods and properties
  • Read-only properties marked with readonly modifier
  • Autocasting enhancement for constructor parameters
  • Typing improvements to take advantage of discriminated unions

Read more about those improvements on the dedicated blog post

API updates and enhancements

Breaking changes

Bug fixes and enhancements

  • BUG-000106859 - Certain WMTS services that were unable to display properly now display as expected.
  • BUG-000107311 - Fixed an issue where the browser would become unresponsive and crash after adding a VectorTileLayer or a TileLayer with an incorrect URL.
  • BUG-000107639 - Updated the API install guide to be more clear.
  • BUG-000107686 - Fixed an issue where graphics were not printing correctly using the Print or the PrintTask.
  • BUG-000107690 - The Print widget now correctly reflects visibility changes of sublayers in the LayerList widget.
  • BUG-000107903 - Fixed an issue when manually zooming into a MapView would zoom further than specified.
  • BUG-000108125 - Fixed an issue where multiple errors were thrown in IE 11 while zoomed into a webmap.
  • BUG-000108242 - The Print widget no longer only creates PDF files when used with IE 11.
  • BUG-000108495 - Fixed a issue where the map would not rotate properly if left or bottom padding was set on the MapView.
  • BUG-000109264 - Fixed an issue where some secured VectorTileLayers would not load properly if handled via a proxy file.
  • BUG-000108875 - Fixed an issue where the default zoom action in the Popup widget would not work if the feature was z-enabled.
  • Fixed a bug where spatialReference was not set after loading a StreamLayer.
  • ENH-000101275 - Made improvements to how SceneLayers renders.
  • ENH-000107506 - Added ability to transition smoothly around a circular view of a 3D Scene.
  • ENH-000108717 - Updated documentation to clarify that planar distances are used in the offset() method for both geometryEngine and geometryEngineAsync.
  • ENH-000108930 - Added a warning message when a browser attempts to load a VectorTileLayer that does not support WebGL.
  • ENH-000108944 - Added the ability to add and remove basemaps and automatically refresh the contents of the BasemapGallery widget.

Website enhancements

  • Adds Keyboard Accessibility support to Home, Guide, API Reference, Sample Code, and Sandbox. Use Shift ? to display the help menu on each page.

Additional packages

Version 4.6 of the ArcGIS Maps SDK for JavaScript uses Dojo 1.13.0 (since 4.6), dgrid version 1.2.1 (since 4.5), and dstore version 1.1.2 (since 4.5).

How to access the SDK

  • The API is available on both CDN and npm, Read more at Install and set up.
  • You can also download both the documentation and the API library. These downloads are typically available 3-4 weeks after release.

Previous releases

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.