Release notes for 4.27

June 2023

Support for editing relationship data has arrived! This release of the JavaScript Maps SDK introduces the ability to edit related data via the Editor widget. The new relationship element provides the functionality needed to configure the relationship within the FormTemplate. These elements must be saved within the form for the Editor to support editing related data. This can be accomplished via the Map Viewer's authoring experience or programmatically using the API.

Once the form is authored, the Editor automatically recognizes if there is a form template set on the editable layer, or the widget's corresponding layerInfo.formTemplate. If the form's template is not set or is not configured to contain relationship elements, the Editor will not display the option to edit the relationship data.

Additional enhancements, including feature-to-feature and table-to-table relationship editing, are planned for future releases. For additional information on editing related records, please refer to the Editor widget documentation.

Editor using related data

3D updates

Scene layer editing

Upload and share 3D content through the web using new scene layer editing capabilities (released in beta). 3D models from various formats can be uploaded and placed using out-of-the-box Editor widget workflows. For example, buildings in a 3D object scene layer can be added, updated, or deleted directly on the web.

Create custom workflows using the Sketch tool and its SketchViewModel – ranging from a simple upload to transforming Mesh geometries before applying edits. SceneLayer.applyEdits was already supported to update attributes in previous releases. This release adds support to update geometry by uploading 3D models. Currently, the following model formats are supported across ArcGIS (see ArcGIS Pro documentation):

  • COLLADA (.dae), Autodesk Filmbox (.fbx), Autodesk Drawing (.dwg), Industry Foundation Classes (.ifc), Universal Scene Description (.usdc, .usdz), Wavefront (.obj), GL Transmission Format (.glTF), and Binary GL Transmission Format (.glb) files.

This capability is powered by automatically converting models for web support. Follow these steps to publish a scene layer with GLB format enabled. Edits to scene layers are applied directly from their associated feature service and support a limited number of edits until you need to rebuild the cache. This concept allows access to individual features with their geometry with SceneLayer.queryFeatures(), while benefiting from optimized display through scene layer caching.

3D topographic basemap

3D Topographic basemap

With our new 3D Topographic basemap (released in beta) we now offer curated 3D context and style for your scenes. The new basemap contains globally available buildings, trees, and labels. The 3D basemap can be selected directly in the BasemapGallery when used with SceneView. You can also load the 3D Topographic basemap portal item programmatically by referencing its item id.

Explore the new 3D Topographic basemap using the updated basemap gallery sample or directly in Scene Viewer.

3D topographic basemap

Labeling improvements

Label priority has been updated to prefer showing labels with larger fonts when they conflict with smaller ones, and to prioritize labels closer to the viewer. Labels are generally crisper on High-DPI displays and vector tile labels are no longer cut at tile borders. Furthermore, SceneView is now consistent with MapView by supporting custom fonts loaded from static resources. These fonts can be used to specify the font family and other attributes, without custom CSS.

Try out some of these improvements in the callout sample using different label sizes to emphasize higher peaks.

Improved labeling

High quality visuals by default

Everyone can now enjoy high quality visuals by default on all devices. We improved the default atmosphere and render scenes with shadows faster while using less memory. Rendering effects are adjusted automatically based on the current activity. When exploring a scene, we render with a similar quality as before to ensure a fluid interaction. When the camera is stationary, higher quality visuals are added to deliver the best quality possible.

Take a look how the realistic water visualization sample improved when setting SceneView.qualityProfile to default.

High quality visuals by default

New low poly vegetation WebStyleSymbols

Bring a playful and engaging look to your scenes with our latest addition to WebStyleSymbols. The new symbols for trees and other vegetation are inspired by low poly art. Check out the new gallery here.

Low poly vegetation

Features widget

The new Features widget (released in beta) allows users to interact with a feature's PopupTemplate content such as attributes, actions, related records, binning and clustering popupTemplates, etc., without having to be tied to the View. This widget looks and behaves similarly to the Popup widget, however unlike Popup, the Features widget can be placed outside of the view. If you want to show a single feature's content without actions, related records, clustering configuration, etc., you can use the Feature widget instead.

Take a look at the Features widget sample to see it in action.


ValuePicker widget

ValuePicker is a widget that allows users to step or play through a list of values. A ValuePicker widget can be configured with an optional collection, label, combobox, or slider control to help users navigate values. Check out the ValuePicker widget sample to see this widget in action.


Support for Places service

Use esri/rest/places (released in beta) to find nearby places within a search distance of a geographic point, and to find more information (name, category, street address, contact information, etc.) about specific places. Places, also known as points of interest (POIs), are businesses and geographic locations that one can discover around the world. With the places service (authentication required) one can build powerful applications to help people discover, locate, and learn more about places around them. Check out the Find nearby places and details sample to learn more.

places service

StreamLayer webmap support

StreamLayer can now be saved to a web map. We also added support for StreamLayer in all appropriate smart mapping statistic and renderer creator methods. In the June update of the Map Viewer, you will be able to easily configure your StreamLayer with styles, labels, feature effects, and more, save it in a web map, and use that map across ArcGIS products.

streamlayer flights

Performance updates

Improved load time from deferred popup loading

In a continuous effort to optimize the performance and load time of the API, the Popup widget is no longer bundled with the MapView and SceneView. The Popup widget has new capabilities implemented often, such as the recent addition of browsing related records. Each new enhancement added to the Popup widget increases the size of the widget and the amount of built code that is sent to the web browser. For example, the Popup module, which was bundled with the MapView, represented around 50% of the size of the bundle.

At this release, the Popup widget loading is deferred until the view is ready and finished updating, and will only be loaded if view.popupEnabled is true, when View.openPopup() is called, or when some widgets need the popup, such as Search. This results in less requests sent out initially, and a faster initial load time.

In most cases, no changes are required in order to take advantage of this improvement — but if you are trying to access view.popup before it has been loaded, you might run into some issues. See the breaking changes section for more information.

Widget updates

Calcite Icon in the Expand widget

We've added support for Calcite icons in the Expand widget through the new expandIcon and collapseIcon properties. This gives you access to over 800 icons that can be used out of the box in the Expand widget, simply by referencing the name of the icon.

calcite icons

We improved the Popup's feature pagination experience with a new icon for the feature menu button, and updated buttons for paging through features. The MediaContent pagination experience was updated providing more horizontal space for charts and images. Popup charts now have new default colors with matching tooltips, an improved interaction experience, and more. See the A fresh new look for pop-ups blog for more details.

Popup design 4.26 Popup design 4.27

ScaleBar enhancements

We made many enhancements to the ScaleBar widget. We added support for additional units (centimeters, millimeters, and inches) at larger scales (more zoomed in), improved intl support, and started using more logical units for enhanced readability and usability (i.e. 300m instead of 0.3km). You can see these changes in action in the ScaleBar widget sample.

Track widget enhancements

In 2D apps, the Track widget now displays a heading graphic when the device has a speed greater than 0 and the browser provides heading information. The new positionFilterFunction() method allows for real-time filtering of the geolocation results. If your function rejects a location, the widget will not draw the graphic showing the users location on the map and will not navigate to that location. This can reduce or eliminate rapid location fluctuations that are often experienced in browser-based geolocation apps.

Track Widget heading indicator


Each release, we continuously work to improve accessibility within our API widgets. This release, we've fixed some accessibility issues within the Bookmarks, Directions, LayerList, Legend, Popup, and Search widgets. We've also upgraded our version of calcite components from 1.0.8 to 1.4.2, which takes advantage of many accessibility improvements. To learn more, check out the bug fixes and enhancements section of the release notes.

Layer updates


We added two new client-side raster functions (released in beta) to ImageryTileLayer. They are Curvature and Table functions. Check out the list of client-side raster functions to see a description and code snippets.

We also added the computeStatisticsHistograms method on ImageryTileLayer which allows you to calculate statistics and histograms on the client-side.

Documentation updates

Symbol Builder

The newly updated Symbol Builder application provides a UI for creating any symbol in the ArcGIS Maps SDK for JavaScript and a snippet you can copy into your code. This application is replacing the now-retired Symbol Playground. Built with Calcite Components, React, and the ArcGIS Maps SDK for JavaScript, the new application streamlines and modernizes the UI and allows for copying ESM code snippets suitable for use in TypeScript applications.

Once you open the symbol builder for a class, the properties for that class and the corresponding inputs are in the left panel. In the center is a graphic with the symbol applied in a MapView or SceneView. On the right, a code snippet can be copied and pasted into your code.

Symbol Builder

New guide pages

We've added a new Symbols guide page and made significant updates to the Labeling guide page. The Symbols guide page summarizes the various symbol classes available in the SDK and the labeling guide was enhanced with more information about common and uncommon labeling workflows.

Utility network

We've added many new capabilities for working with utility networks — including a new trace method to perform a trace on a utility network, a new widget to validate network topology, and some updates to the UtilityNetworkTrace widget.

New UtilityNetworkValidateTopology widget

This release introduces a new widget, UtilityNetworkValidateTopology, which allows a user to validate the network topology of a utility network after there have been edits to features in the utility network. To use this widget, the dirty areas layer must be available on the map. The out-of-date edits in the network topology are marked with dirty areas, signaling that the feature visible on the map does not match what is stored in the network topology. The widget can validate the current extent of the view or the entire utility network.


UtilityNetworkTrace updates

The following updates were made to the UtilityNetworkTrace widget:

  • Added the ability to perform a trace on SubtypeGroupLayers in a utility network.
  • Added the ability to generate a result area graphic around the trace result elements with an information popup.
  • Added a utilityNetwork property that allows for the utility network that the widget uses to be updated.
  • Added a traceResults property to obtain the trace results after performing a trace.

Fetch components from the View UI

The new getComponents() method on view.ui allows you to fetch all components in the current view, or only those at a specified position in the view.

Use dark colors for code blocksCopy
// returns all widgets and HTML elements in the view UI
const allComponents = view.ui.getComponents();

// returns widgets and HTML elements in the top-right position of the view UI
const someComponents = view.ui.getComponents("top-right");

ES modules console warning improvement

For@arcgis/core ES modules, we improved the console warning message when using locally hosted assets and there is a version mismatch between the assets used by your build process and those used by the application. This will help you avoid unexpected issues or errors. The updated warning includes the @arcgis/core NPM package version used to build the project, as well as the @arcgis/core version of the assets, and the local path to the assets configured in your application. More information is available in the Get started with npm guide topic.

Assets mismatch console warning

Added classes, properties, methods, events

Deprecated classes, properties, methods, events

  • For local builds, Webpack versions prior to 5.84.0 are deprecated at 4.27. This is related to webpack bugs that can cause SDK build errors. Upgrade to 5.84.0 or greater.

  • As of 4.27, when building new custom widgets it is no longer recommended to subclass or extend esri/widgets/Widget. Instead, use DOM elements such as the div element, web components or JavaScript framework components in combination with the Calcite Design System. More information about creating a custom UI is available in the Custom UI basics Guide topic.

Breaking changes

  • The Popup widget loading is deferred until the view is ready and finished updating, and will only be loaded if View.popupEnabled is set to true (which is the default), when View.openPopup() is called, or when some widgets need the popup, such as Search. In most cases, applications will not need to be updated and will continue to work. However, if attempting to access the view.popup property before it is instantiated, some issues may occur. See Loading the Popup for details on how to update your apps to take advantage of these performance improvements. Alternatively, you can simply create a new instance of the Popup when instantiating the View, as shown in the code snippet below. Note: this will not take advantage of the deferred loading.
    Use dark colors for code blocksCopy
    // Create a new MapView
    const view = new MapView({
      // set the popup property to a new instance of Popup
      popup: new Popup(...)
  • Compatibility with implementations that don't support async/await at runtime, within AMD modules, has been removed at 4.27. For example, some SDK applications using Angular with esri-loader may experience runtime errors, and will need to migrate from AMD modules to using @arcgis/core ES modules.
  • The old workflow of creating a Directions widget without a RouteLayer was deprecated at version 4.24 and is removed at 4.27. Directions widget must be created with a RouteLayer, like in the Directions widget sample.
  • Properties SunLighting.ambientOcclusionEnabled and SunLighting.waterReflectionEnabled have been deprecated with version 4.27 and have no effect. Ambient occlusion and reflections are now automatically controlled by the new adaptive rendering behavior.

The following classes, methods, properties and events have been deprecated for at least 2 releases and have now been removed from the API:

Class/Property/Method/EventAlternate optionVersion deprecated
Directions.routeServiceUrlurl from Directions.layer4.24
Directions.routeSymboldirectionLines from Directions.layer4.24
Directions.stopSymbolsRouteStopSymbols from Directions.layer4.24
DirectionsViewModel.routeServiceUrlurl from DirectionsViewModel.layer4.24
DirectionsViewModel.routeSymboldirectionLines from DirectionsViewModel.layer4.24
DirectionsViewModel.stopsstops from DirectionsViewModel.layer4.24
DirectionsViewModel.stopSymbolsRouteStopSymbols from DirectionsViewModel.layer4.24

Please refer to the Breaking changes guide topic for a complete list of breaking changes across all releases of the 4.x API.

Bug fixes and enhancements

  • BUG-000140665: Fixed an issue in the Bookmarks widget where the bookmark's thumbnail would display in editing mode, even if visibleElements.thumbnail was false.
  • BUG-000148460: Fixed an issue where FeatureForm text input did not allow for vertical expansion.
  • BUG-000154383: Fixed an issue where WMSLayer would not be included in the legendOptions when printed with the Print widget.
  • BUG-000154464: Fixed an issue where the typings for ConversionInfo were incorrect.
  • BUG-000155003: Fixed an issue where WMTSLayer.fetchTile() was not able to be overridden.
  • BUG-000155351: Fixed an issue in the LayerList widget where the loading indicator would blink continuously when a view's container was changed.
  • BUG-000156270: Fixed an issue where the BaseTileLayer was referencing old tiles after refresh is called.
  • BUG-000156346: Fixed an issue where date and time did not format properly in the FeatureForm title.
  • BUG-000157174: Fixed an issue in the VoxelLayer popup where non-ASCII characters were not displayed correctly.
  • BUG-000157217: Fixed an issue when editing data of non-hosted feature services resulted in a console error: "Combination of parameters rollbackOnFailure = false & returnServiceEditsOption = originalAndCurrentFeatures for applyEdits operation is not supported". The error should no longer occur and edits should apply as expected.
  • BUG-000157248: Fixed an issue where hiding the saveAsButon and saveButton of the Directions widget caused a blank area to appear.
  • BUG-000157741: Improved the quality of images returned by ImageryTileLayer to match the quality of images returned by TileLayer.
  • BUG-000157898: Fixed an issue where WMSSublayer.layer was not defined on children of a sublayer.
  • BUG-000158205: Fixed an issue where WMSLayer would not support URLs containing parameter names written in mixed case.
  • Esri Community - 1269135: Fixed an issue where the backgroundColor of a TextSymbol was always slightly transparent.
  • Esri Community - 1272209: Fixed an issue where some CIM symbols with a CIMHatchFill symbol layer were misaligned at tile boundaries at large scales.
  • Esri Community - 1275187: Fixed an issue where CIM symbols using icon fonts were not rendering properly in 3D.
  • Esri Community - 1277457: Improved the behavior of BaseTileLayer to release the tiles that are no longer displayed.
  • Esri Community - 1278156: Fixed an issue where the SimpleLineSymbol is drawn despite setting the style to none.
  • Esri Community - 1282644: Fixed an issue where the background and halo of a TextSymbol or CIMSymbol would not render in the symbol preview returned from symbolUtils.renderPreviewHTML().
  • Calcite - 5713: Placeholder string is not centered horizontally in input search/combobox in Safari/FF.
  • Fixed an accessibility issue where the BasemapLayerList widget did not have the correct aria-checked status.
  • Fixed an accessibility issue where the Bookmarks widget's drag/reorder tooltip was not displayed when in focus for keyboard-only users.
  • Fixed an accessibility issue where the Directions widget had incorrect Aria group roles.
  • Fixed an accessibility issue where the first list item would not be in focus when tabbing through the related records list in RelationshipContent.
  • Fixed an accessibility issue where the LayerList widget did not have the correct aria-checked status.
  • Fixed an accessibility issue where the Legend widget did not have the correct alternative text for some SVG images.
  • Fixed an accessibility issue where the Search widget did not properly change live regions for dynamic content for screen readers.
  • Fixed an issue where focus style didn't display if map width and/or height was 100%.
  • Fixed an issue where MapImageLayers were not showing popups for features that do not have a renderer.
  • Fixed an issue where some color primitive overrides on a CIMSymbol would not render in a WebMap published from ArcGIS Pro.
  • Fixed an issue where the ImageMediaInfo's refreshInterval property was not sending requests to refresh the image displayed in the Feature and Popup widgets.
  • Fixed an issue with the BasemapLayerList widget where the panel button action was left active when a layer was not visible.
  • Fixed an issue with the LayerList widget where the panel button action was left active when a layer was not visible.
  • Fixed an issue with the Print widget where CustomTextElements would not display.
  • ENH-000105370: Enhanced the ScaleBar by using more logical scale values to improve readability and usability.
  • ENH-000148333: Users now can zoom outside of the minLOD and maxLOD range when the layer is used as a basemap.
  • ENH-000156323: Improved the quality of images returned by ImageryTileLayer to match the quality of images returned by TileLayer.
  • Added a returnGeometryEnabled property to the FeatureTable widget. Setting this to true fetches geometries for the features displayed in the table.
  • Added support for an asynchronous filterFunction on PortalBasemapsSource.
  • Changed the stream layer connectionStatus icon in the LayerList from a calcite check-circle icon to a calcite beacon icon.
  • Enhanced the API's performance so that point features symbolized with simple markers and some CIM markers are now rendered faster, especially on low-end devices and/or when you have a large number of features.
  • Enhanced the query property in RequestOptions to accept a URLSearchParams object.
  • Enhanced the url parameter on the request.esriRequest method to accept a URL object.
  • MediaLayer is out of beta.

Additional packages

Version 4.27 of the ArcGIS Maps SDK for JavaScript uses ArcGIS Arcade 1.23 (since 4.27).

Version 4.27 of the ArcGIS Maps SDK for JavaScript uses Calcite Design System, version 1.4.2.

How to access the SDK

  • The API library is available on both CDN and npm, Read more at Get started.
  • For supported versions, 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.