Directions | API Reference | ArcGIS Maps SDK for JavaScript 4.30

The Directions widget provides a way to calculate directions, between two or more input locations with a RouteLayer, using ArcGIS Online and custom Network Analysis Route services. Similar to how route works, this widget generates a route finding a least-cost path between multiple points using a specified routing service. The resulting directions are displayed with detailed turn-by-turn instructions.

Directions widget uses Search to locate each stop, either by selecting a point on the map, or by entering a search term into the textbox. The Search widget uses settings defined in Search properties. This includes the locationType, which defines the type of geocoding result that is returned, and defaults to "street".

The Directions widget is required to be used with a user defined RouteLayer. This might be an entirely new RouteLayer, or a RouteLayer derived from a route portal item, but it also must be added to the map in order to visualize the route. To retrieve or change the routeServiceUrl or symbology, please access the relevant properties on the layer, instead of on the Directions widget.

It is important to note that the Directions widget will automatically assign two empty stops if the assigned RouteLayer does not have any stops defined. An empty stop is a stop without a name or location. In the UI, these empty stops will appear as a placeholder for the user to either enter a search term, or digitize a location on the map. This behavior existed in legacy mode (no RouteLayer explicitly passed to the Directions widget constructor) as well, in which the Directions widget would assign a temporary RouteLayer if one was not assigned. Additionally, there is different default symbology created for a Directions widget instantiated with and without a RouteLayer:

Directions with RouteLayer

The routing service defaults to this URL: https://route-api.arcgis.com/arcgis/rest/services/World/Route/NAServer/Route_World. This routing service requires authentication. You can use Directions.apiKey, or a global apiKey to specify an apiKey for authentication. Note that when using a global API key, persistence is not supported (e.g. saving web maps, portal items). This includes saving routes in Directions using save or saveAs. Alternatively, you can or use another authentication method to access the routing service. To geocode locations in the Directions widget UI, the built-in Search widget uses this URL by default: https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer, which also requires authentication.

The resulting directions can be saved as a route portal item using Save or SaveAs buttons. The Save method updates the route portal item associated with the layer (if any). The Save As method is available for all portal users. The Clear route button calls the reset() method, which removes all stops, directions, and the solved route. Any type of customizations made to the underlying functionality of the widget should be handled via its viewModel property.

See also

Examples

// 1. Add empty RouteLayer to Directions widget

// create a new empty RouteLayer
const routeLayer = new RouteLayer();

// new RouteLayer must be added to the map
// for route visualization
const map = new Map({
  basemap: "topo-vector",
  layers: [routeLayer]
});

// new RouteLayer must be added to Directions widget
const directionsWidget = new Directions({
  view: view,
  layer: routeLayer
});

// adds the Directions widget to the
// top right corner of the view
view.ui.add(directionsWidget, {
  position: "top-right"
});

// 2. Add RouteLayer from portal to Directions widget

// create a new RouteLayer from a portal item
const routeLayer = new RouteLayer({
  portalItem: { // autocasts as new PortalItem()
    id: "fd4188722f3e4e14986abca86cad80c6"
  }
});

// new RouteLayer must be added to the map
// for route visualization
const map = new Map({
  basemap: "topo-vector",
  layers: [routeLayer]
});

// new RouteLayer must be added to Directions widget
const directionsWidget = new Directions({
  view: view,
  layer: routeLayer
});

// adds the Directions widget to the
// bottom right corner of the view
view.ui.add(directionsWidget, {
  position: "bottom-right"
});

// 3. Create a Directions widget with 2 pre-set stops

// create a new RouteLayer with 2 stops
const routeLayer = new RouteLayer({
  stops: [
    { name: "Redlands, CA", geometry: { x: -117.1825, y: 34.0547 } },
    { name: "Palm Springs, CA", geometry: { x: -116.5452, y: 33.8302 } }
  ]
});

// new RouteLayer must be added to the map
// for route visualization
const map = new Map({
  basemap: "topo-vector",
  layers: [routeLayer]
});

// new RouteLayer must be added to Directions widget
const directionsWidget = new Directions({
  view: view,
  layer: routeLayer
});

// 4. Update the empty stops that are automatically added by the Directions widget

// create a new empty RouteLayer
const routeLayer = new RouteLayer();

// new RouteLayer must be added to the map
// for route visualization
const map = new Map({
  basemap: "topo-vector",
  layers: [routeLayer]
});

// new RouteLayer must be added to Directions widget
const directionsWidget = new Directions({
  view: view,
  layer: routeLayer
});

// call the asynchronous function
directionsReady();

// asynchronous function to seed the Directions widget
// with two initials stops (Campton to Plymouth)
// instead of the empty stops
async function directionsReady(){
  await directionsWidget.when();
  directionsWidget.layer.stops.at(0).name = "Campton, NH";
  directionsWidget.layer.stops.at(0).geometry = new Point({ x: -71.64133, y: 43.85191 });
  directionsWidget.layer.stops.at(1).name = "Plymouth, NH";
  directionsWidget.layer.stops.at(1).geometry = new Point({ x: -71.68808, y: 43.75792 });
}

Constructors

Directions Constructor new Directions(properties)

Parameter

properties Object

optional

See the properties for a list of all the properties that may be passed into the constructor.

Property Overview

Any properties can be set, retrieved or listened to. See the Working with Properties topic.

Show inherited properties

Hide inherited properties

Type	Summary	Class
String	An authorization string used to access a resource or service.	Directions
String\|HTMLElement	The ID or node representing the DOM element containing the widget.	Widget
String	The name of the class.	Accessor
GoToOverride	This function provides the ability to override either the MapView goTo() or SceneView goTo() methods.	Directions
Number	Indicates the heading level to use for the origin and destination addresses (i.e.	Directions
String	Icon which represents the widget.	Directions
String	The unique ID assigned to the widget when the widget is created.	Widget
String	The widget's default label.	Directions
RouteLayerSolveResult	The most recent route result.	Directions
RouteLayer	The RouteLayer associated with the Directions widget.	Directions
Number	The maximum number of stops allowed for routing.	Directions
SearchProperties	Controls the default properties used when searching.	Directions
String	Unit system (imperial, metric) or specific unit used for displaying the distance values.	Directions
MapView\|SceneView	The view from which the widget will operate.	Directions
DirectionsViewModel	The view model for this widget.	Directions
Boolean	Indicates whether the widget is visible.	Widget
VisibleElements	The visible elements that are displayed within the widget.	Directions

Property Details

apiKey Property apiKey String Since: ArcGIS Maps SDK for JavaScript 4.19 Directions since 4.6, apiKey added at 4.19.

An authorization string used to access a resource or service. API keys are generated and managed in the portal. An API key is tied explicitly to an ArcGIS account; it is also used to monitor service usage. Setting a fine-grained API key on a specific class overrides the global API key.

By default, the following URLs will be used (unless overwritten in the app, or if using different defaults from a portal):

Geocoding URL: https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer

Routing URL: https://route-api.arcgis.com/arcgis/rest/services/World/Route/NAServer/Route_World

Example

const directionsWidget = new Directions({
  view: view,
  layer: routeLayer,
  apiKey: "YOUR_API_KEY"
});
// Add the Directions widget to the top right corner of the view
view.ui.add(directionsWidget, {
  position: "top-right"
});

container Inherited Property container String |HTMLElement Inherited from Widget

The ID or node representing the DOM element containing the widget. This property can only be set once. The following examples are all valid use case when working with widgets.

Examples

// Create the HTML div element programmatically at runtime and set to the widget's container
const basemapGallery = new BasemapGallery({
  view: view,
  container: document.createElement("div")
});

// Add the widget to the top-right corner of the view
view.ui.add(basemapGallery, {
  position: "top-right"
});

// Specify an already-defined HTML div element in the widget's container

const basemapGallery = new BasemapGallery({
  view: view,
  container: basemapGalleryDiv
});

// Add the widget to the top-right corner of the view
view.ui.add(basemapGallery, {
  position: "top-right"
});

// HTML markup
<body>
  <div id="viewDiv"></div>
  <div id="basemapGalleryDiv"></div>
</body>

// Specify the widget while adding to the view's UI
const basemapGallery = new BasemapGallery({
  view: view
});

// Add the widget to the top-right corner of the view
view.ui.add(basemapGallery, {
  position: "top-right"
});

declaredClass Inherited Property declaredClass Stringreadonly Inherited from Accessor Since: ArcGIS Maps SDK for JavaScript 4.7 Accessor since 4.0, declaredClass added at 4.7.

The name of the class. The declared class name is formatted as esri.folder.className.

goToOverride Property goToOverride GoToOverride Since: ArcGIS Maps SDK for JavaScript 4.8 Directions since 4.6, goToOverride added at 4.8.

This function provides the ability to override either the MapView goTo() or SceneView goTo() methods.

See also

Example

// The following snippet uses the Search widget but can be applied to any
// widgets that support the goToOverride property.
search.goToOverride = function(view, goToParams) {
  goToParams.options = {
    duration: updatedDuration
  };
  return view.goTo(goToParams.target, goToParams.options);
};

headingLevel Property headingLevel Number Since: ArcGIS Maps SDK for JavaScript 4.20 Directions since 4.6, headingLevel added at 4.20.

Indicates the heading level to use for the origin and destination addresses (i.e. "380 New York Street"). By default, this is rendered as a level 2 heading (e.g. <h2>380 New York Street</h2>). Depending on the widget's placement in your app, you may need to adjust this heading for proper semantics. This is important for meeting accessibility standards.

Default Value:2

See also

Heading Elements

Example

// address text will render as an <h3>
directions.headingLevel = 3;

icon Property icon String Since: ArcGIS Maps SDK for JavaScript 4.27 Directions since 4.6, icon added at 4.27.

Icon which represents the widget. It is typically used when the widget is controlled by another one (e.g. in the Expand widget).

Default Value:"right"

See also

Calcite Icon Search

id Inherited Property id String Inherited from Widget

The unique ID assigned to the widget when the widget is created. If not set by the developer, it will default to the container ID, or if that is not present then it will be automatically generated.

label Property label String Since: ArcGIS Maps SDK for JavaScript 4.7 Directions since 4.6, label added at 4.7.

The widget's default label.

lastRoute Property lastRoute RouteLayerSolveResultreadonly

The most recent route result. Returns a RouteLayerSolveResult object containing properties for barriers (if any), stops, and directions.

Properties

directionLines Collection<DirectionLine>

Collection of direction polylines associated with line segments between turns.

directionPoints Collection<DirectionPoint>

Collection of direction items as points with various display information.

pointBarriers Collection<PointBarrier>

Collection of point barriers.

polygonBarriers Collection<PolygonBarrier>

Collection of polygon barriers.

polylineBarriers Collection<PolylineBarrier>

Collection of polyline barriers.

routeInfo RouteInfo

Information about a solved route including the route's geometry and overall distance and time.

stops Collection<Stop>

Collection of stops. Represents the start, end, or midpoint of a route.

Default Value:null

See also

RouteLayer.solve()

layer Property layer RouteLayer Since: ArcGIS Maps SDK for JavaScript 4.24 Directions since 4.6, layer added at 4.24.

The RouteLayer associated with the Directions widget. This property is required. The RouteLayer contains stops and barriers and will be used to display and solve routes.

maxStops Property maxStops Number

The maximum number of stops allowed for routing.

Default Value:50

searchProperties Property searchProperties SearchProperties

Controls the default properties used when searching. Note that the default searchProperties differ slightly from the Search widget.

Default Value:null

unit Property unit String Since: ArcGIS Maps SDK for JavaScript 4.25 Directions since 4.6, unit added at 4.25.

Unit system (imperial, metric) or specific unit used for displaying the distance values. If not set, the widget will attempt to pick "imperial" or "metric" based on the user's portal settings.

This property will affect the summary distance as well as distance for each turn-by-turn maneuver.

Example

// Display distances in nautical miles.
const directions = new Directions({
  unit: "nautical-miles",
  layer: routeLayer,
  view: view
});

view Property view MapView |SceneView

The view from which the widget will operate.

viewModel Property viewModel DirectionsViewModelautocast

The view model for this widget. This is a class that contains all the logic (properties and methods) that controls this widget's behavior. See the DirectionsViewModel class to access all properties and methods on the widget.

visible Inherited Property visible Boolean Inherited from Widget

Indicates whether the widget is visible.

If false, the widget will no longer be rendered in the web document. This may affect the layout of other elements or widgets in the document. For example, if this widget is the first of three widgets associated to the upper right hand corner of the view UI, then the other widgets will reposition when this widget is made invisible. For more information, refer to the css display value of "none".

Default Value:true

Example

// Hides the widget in the view
widget.visible = false;

visibleElements Property visibleElements VisibleElements Since: ArcGIS Maps SDK for JavaScript 4.24 Directions since 4.6, visibleElements added at 4.24.

The visible elements that are displayed within the widget. This property provides the ability to turn individual elements of the widget's display on/off.

Example

// Hide the save button, save-as button and layer details link.
const directions = new Directions({
  view: view,
  layer: routeLayer,
  visibleElements: {
    layerDetailsLink: false,
    saveAsButton: false,
    saveButton: false
  }
});

Method Overview

Show inherited methods

Hide inherited methods

Return Type	Summary	Class
	Adds one or more handles which are to be tied to the lifecycle of the object.	Accessor
String	A utility method used for building the value for a widget's `class` property.	Widget
	Destroys the widget instance.	Widget
Boolean	Emits an event on the instance.	Widget
Promise<RouteLayerSolveResult>	Computes a route and directions.	Directions
Boolean	Indicates whether there is an event listener on the instance that matches the provided event name.	Widget
Boolean	Returns true if a named group of handles exist.	Accessor
Boolean	`isFulfilled()` may be used to verify if creating an instance of the class is fulfilled (either resolved or rejected).	Widget
Boolean	`isRejected()` may be used to verify if creating an instance of the class is rejected.	Widget
Boolean	`isResolved()` may be used to verify if creating an instance of the class is resolved.	Widget
Object	Registers an event handler on the instance.	Widget
	Adds one or more handles which are to be tied to the lifecycle of the widget.	Widget
	Executes after widget is ready for rendering.	Widget
	Removes a group of handles owned by the object.	Accessor
Object	This method is implemented by subclasses for rendering.	Widget
	Renders widget to the DOM immediately.	Widget
Promise<PortalItem>	Saves the RouteLayer associated with the view model.	Directions
Promise<PortalItem>	Saves the RouteLayer associated with the view model as a new portal item.	Directions
	Schedules widget rendering.	Widget
Promise	`when()` may be leveraged once an instance of the class is created.	Widget
	Zoom so that the full route is displayed within the current map extent.	Directions

Method Details

addHandles Inherited Method addHandles(handleOrHandles, groupKey) Inherited from Accessor Since: ArcGIS Maps SDK for JavaScript 4.25 Accessor since 4.0, addHandles added at 4.25.

Adds one or more handles which are to be tied to the lifecycle of the object. The handles will be removed when the object is destroyed.

// Manually manage handles
const handle = reactiveUtils.when(
  () => !view.updating,
  () => {
    wkidSelect.disabled = false;
  },
  { once: true }
);

this.addHandles(handle);

// Destroy the object
this.destroy();

Parameters

handleOrHandles WatchHandle|WatchHandle []

Handles marked for removal once the object is destroyed.

groupKey *

optional

Key identifying the group to which the handles should be added. All the handles in the group can later be removed with Accessor.removeHandles(). If no key is provided the handles are added to a default group.

classes Inherited Method classes(classNames){String} Inherited from Widget Since: ArcGIS Maps SDK for JavaScript 4.7 Widget since 4.2, classes added at 4.7.

A utility method used for building the value for a widget's class property. This aids in simplifying css class setup.

Parameter

classNames String|String []|Object

repeatable

The class names.

Returns

Type	Description
String	The computed class name.

Example

// .tsx syntax showing how to set css classes while rendering the widget

render() {
  const dynamicClasses = {
    [css.flip]: this.flip,
    [css.primary]: this.primary
  };

  return (
    <div class={classes(css.root, css.mixin, dynamicClasses)} />
  );
}

destroy Inherited Method destroy() Inherited from Widget

Destroys the widget instance.

emit Inherited Method emit(type, event){Boolean} Inherited from Widget

Emits an event on the instance. This method should only be used when creating subclasses of this class.

Parameters

type String

The name of the event.

event Object

optional

The event payload.

Returns

Type	Description
Boolean	`true` if a listener was notified

getDirections Method getDirections(){Promise<RouteLayerSolveResult>}

Computes a route and directions. If successfully computed, results will be assigned to lastRoute returned. If a view is assigned, it will zoom to the extent of the route.

Returns

Type	Description
Promise<RouteLayerSolveResult>	When resolved, returns a RouteLayerSolveResult.

hasEventListener Inherited Method hasEventListener(type){Boolean} Inherited from Widget

Indicates whether there is an event listener on the instance that matches the provided event name.

Parameter

type String

The name of the event.

Returns

Type	Description
Boolean	Returns true if the class supports the input event.

hasHandles Inherited Method hasHandles(groupKey){Boolean} Inherited from Accessor Since: ArcGIS Maps SDK for JavaScript 4.25 Accessor since 4.0, hasHandles added at 4.25.

Returns true if a named group of handles exist.

Parameter

groupKey *

optional

A group key.

Returns

Type	Description
Boolean	Returns `true` if a named group of handles exist.

Example

// Remove a named group of handles if they exist.
if (obj.hasHandles("watch-view-updates")) {
  obj.removeHandles("watch-view-updates");
}

isFulfilled Inherited Method isFulfilled(){Boolean} Inherited from Widget Since: ArcGIS Maps SDK for JavaScript 4.19 Widget since 4.2, isFulfilled added at 4.19.

isFulfilled() may be used to verify if creating an instance of the class is fulfilled (either resolved or rejected). If it is fulfilled, true will be returned.

Returns

Type	Description
Boolean	Indicates whether creating an instance of the class has been fulfilled (either resolved or rejected).

isRejected Inherited Method isRejected(){Boolean} Inherited from Widget Since: ArcGIS Maps SDK for JavaScript 4.19 Widget since 4.2, isRejected added at 4.19.

isRejected() may be used to verify if creating an instance of the class is rejected. If it is rejected, true will be returned.

Returns

Type	Description
Boolean	Indicates whether creating an instance of the class has been rejected.

isResolved Inherited Method isResolved(){Boolean} Inherited from Widget Since: ArcGIS Maps SDK for JavaScript 4.19 Widget since 4.2, isResolved added at 4.19.

isResolved() may be used to verify if creating an instance of the class is resolved. If it is resolved, true will be returned.

Returns

Type	Description
Boolean	Indicates whether creating an instance of the class has been resolved.

on Inherited Method on(type, listener){Object} Inherited from Widget

Registers an event handler on the instance. Call this method to hook an event with a listener.

Parameters

type String|String []

An event or an array of events to listen for.

listener Function

The function to call when the event fires.

Returns

Type Description

Object

Returns an event handler with a remove() method that should be called to stop listening for the event(s).

Property	Type	Description
remove	Function	When called, removes the listener from the event.

Example

view.on("click", function(event){
  // event is the event handle returned after the event fires.
  console.log(event.mapPoint);
});

own Inherited Method own(handleOrHandles) Inherited from Widget Since: ArcGIS Maps SDK for JavaScript 4.24 Widget since 4.2, own added at 4.24. Deprecated since 4.28 Use addHandles() instead.

Adds one or more handles which are to be tied to the lifecycle of the widget. The handles will be removed when the widget is destroyed.

const handle = reactiveUtils.when(
  () => !view.updating,
  () => {
    wkidSelect.disabled = false;
  },
  { once: true}
);

this.own(handle); // Handle gets removed when the widget is destroyed.

Parameter

handleOrHandles WatchHandle|WatchHandle []

Handles marked for removal once the widget is destroyed.

postInitialize Inherited Method postInitialize() Inherited from Widget

Executes after widget is ready for rendering.

removeHandles Inherited Method removeHandles(groupKey) Inherited from Accessor Since: ArcGIS Maps SDK for JavaScript 4.25 Accessor since 4.0, removeHandles added at 4.25.

Removes a group of handles owned by the object.

Parameter

groupKey *

optional

A group key or an array or collection of group keys to remove.

Example

obj.removeHandles(); // removes handles from default group

obj.removeHandles("handle-group");
obj.removeHandles("other-handle-group");

render Inherited Method render(){Object} Inherited from Widget

This method is implemented by subclasses for rendering.

Returns

Type	Description
Object	The rendered virtual node.

renderNow Inherited Method renderNow() Inherited from Widget

Renders widget to the DOM immediately.

save Method save(){Promise<PortalItem>} Since: ArcGIS Maps SDK for JavaScript 4.24 Directions since 4.6, save added at 4.24.

Saves the RouteLayer associated with the view model. This method will update the portal-item associated with layer.

Returns

Type	Description
Promise<PortalItem>	When resolved, returns a PortalItem.

See also

saveAs Method saveAs(portalItem, options){Promise<PortalItem>} Since: ArcGIS Maps SDK for JavaScript 4.24 Directions since 4.6, saveAs added at 4.24.

Saves the RouteLayer associated with the view model as a new portal item.

Parameters

portalItem Promise<PortalItem>

The new portal item to which the layer will be saved.

options Object

optional

Save options. Currently, there is only one property that can be set, which is folder.

Specification

folder PortalFolder

optional

The folder in which to save the item.

Returns

Type	Description
Promise<PortalItem>	Saved portal item.

See also

scheduleRender Inherited Method scheduleRender() Inherited from Widget

Schedules widget rendering. This method is useful for changes affecting the UI.

when Inherited Method when(callback, errback){Promise} Inherited from Widget Since: ArcGIS Maps SDK for JavaScript 4.19 Widget since 4.2, when added at 4.19.

when() may be leveraged once an instance of the class is created. This method takes two input parameters: a callback function and an errback function. The callback executes when the instance of the class loads. The errback executes if the instance of the class fails to load.

Parameters

callback Function

optional

The function to call when the promise resolves.

errback Function

optional

The function to execute when the promise fails.

Returns

Type	Description
Promise	Returns a new Promise for the result of `callback`.

Example

// Although this example uses the BasemapGallery widget, any class instance that is a promise may use when() in the same way
let bmGallery = new BasemapGallery();
bmGallery.when(function(){
  // This function will execute once the promise is resolved
}, function(error){
  // This function will execute if the promise is rejected due to an error
});

zoomToRoute Method zoomToRoute()

Zoom so that the full route is displayed within the current map extent.

Type Definitions

SearchProperties Type Definition SearchProperties

Configurable Search properties of the widget.

Properties: activeSourceIndex Number

optional
Number index indicating the current selected source.

allPlaceholder String

optional
String value used as a hint for input text when searching on multiple sources.

autoNavigate Boolean

optional
Default Value:true

Indicates whether to automatically navigate to the selected result once selected.

autoSelect Boolean

optional
Indicates whether to automatically select and zoom to the first geocoded result.

includeDefaultSources Boolean|Function

optional
Indicates whether or not to include defaultSources in the Search UI. This can be a boolean value or a function that returns an array of Search sources.

locationType String

optional
Define the type of location, either "street" or "rooftop". The default value will be "street" for any locator source that does not define a locationType.

maxResults Number

optional
Default Value:6

Indicates the maximum number of search results to return.

maxSuggestions Number

optional
Default Value:6

Indicates the maximum number of suggestions to return for the widget's input.

minSuggestCharacters Number

optional
Default Value:1

Indicates the minimum number of characters required before querying for a suggestion.

popupEnabled Boolean

optional
Default Value:false

Indicates whether to display a Popup when a selected result is clicked.

popupTemplate PopupTemplate

optional
A customized PopupTemplate for the selected feature.

resultGraphicEnabled Boolean

optional
Default Value:false

Indicates whether to show a graphic on the map for the selected source.

searchAllEnabled Boolean

optional
Indicates whether to display the option to search all sources.

searchTerm String

optional
The value of the search box input text string.

sources Collection<(LayerSearchSource|LocatorSearchSource)>

optional
Specifies the sources to search in the view.

suggestionsEnabled Boolean

optional
Default Value:true

Indicates whether to display suggestions as the user enters input text in the widget.

view MapView|SceneView

optional
The view of the widget.

viewModel SearchViewModel

optional
The Search widget's view model.

VisibleElements Type Definition VisibleElements

The visible elements that are displayed within the widget. This provides the ability to turn individual elements of the widget's display on/off.

Properties: layerDetails Boolean

optional
Indicates whether to a link to the route layer portal-item (if any) will be displayed. Default is true.

saveAsButton Boolean

optional
Indicates whether to the Save As button will be displayed. Default is true.

saveButton Boolean

optional
Indicates whether to the Save button will be displayed. Default is true.