arcgis-directions | References | ArcGIS Maps SDK for JavaScript

ESM

import "@arcgis/map-components/components/arcgis-directions";

Inheritance:: ArcgisDirections→PublicLitElement

Since: ArcGIS Maps SDK for JavaScript 4.28

The Directions component provides a way to calculate directions, between two or more input locations with a RouteLayer, using ArcGIS Online and custom Network Analysis Route services. This component generates a route finding a least-cost path between multiple points using the routing service associated with the assigned RouteLayer. The route is calculated based on the stops and barriers added to the RouteLayer. The component provides a user interface for adding, removing, and reordering stops and barriers. Once the route is solved, the component displays the route on the map and provides turn-by-turn directions in a list format.

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

Directions requires a RouteLayer to be associated with the layer property or using the useDefaultRouteLayer property. A RouteLayer can be programmatically created or derived from an external source like a portal item or webmap. Please note that in order to view or interact with routing inputs and results, the RouteLayer must be added to the map. Routing service and symbology is configured in the layer, specifically the url and defaultSymbols properties respectively.

The ArcGIS Online routing service requires authentication. If an API key is specified at the app level (see Config#apiKey) or component level (see apiKey)) then this key will accompany requests to both the routing service and geocoder/reverse-geocoder. Please refer to the Search component for more information on geocoding.

Locations on the map can be reverse geocoded and used as stops in the route. Click the button with a crosshairs icon to associate a location with a new or existing stop. After clicking the button, click the map once. To cancel this process, press the escape key. The resulting driving directions are automatically collapsed and can be optionally saved to a new or existing portal item. This can be achieved programically with save and saveAs. The Clear button calls the reset() method, which removes all stops, directions, and the solved route.

Selecting the Edit route button allows you to add/move/remove stops, add/move/remove/reshape polyline barriers, and add/move/remove waypoints. To add a new waypoint, first hover the cursor over the route and select the desired point. Then select and drag the point to move and place the waypoint. By default the route will be automatically resolve at the completion of any editing operation. For more complex routes, it may be advantageous to disable auto-solving and solve as and when needed with the dedicated solve button. Currently, this is only supported in 2D MapViews.

Note: Printing in Directions is in beta and considered experimental. The print preview dialog, in some scenarios, may not display as aniticipated.

Demo

Properties

Property	Attribute	Type
`apiKey`	`api-key`	`string \| null \| undefined`
`autoDestroyDisabled`	`auto-destroy-disabled`	`boolean`
`autoSolveOnEditActive`	`auto-solve-on-edit-active`	`boolean`
`goToOverride`		`GoToOverride \| null \| undefined`
`headingLevel`	`heading-level`	`HeadingLevel`
`hideLayerDetails`	`hide-layer-details`	`boolean`
`hidePrintButton`	`hide-print-button`	`boolean`
`hideSaveAsButton`	`hide-save-as-button`	`boolean`
`hideSaveButton`	`hide-save-button`	`boolean`
`icon`	`icon`	`Icon["icon"]`
`label`	`label`	`string`
`lastRoute` readonly		`RouteLayerSolveResult \| null \| undefined`
`layer`		`RouteLayer \| null \| undefined`
`maxStops`	`max-stops`	`number`
`referenceElement`	`reference-element`	`ArcgisReferenceElement \| string \| undefined`
`routeLayerItemId`	`route-layer-item-id`	`string \| undefined`
`searchProperties`		`SearchProperties \| null \| undefined`
`state` readonly		`State`
`unit`	`unit`	`SystemOrLengthUnit`
`useDefaultRouteLayer`	`use-default-route-layer`	`boolean`
`view`		`MapViewOrSceneView \| null \| undefined`

apiKey

Property

Type: string | null | undefined

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

Attribute: api-key

Example

// Add the Directions component to the top right corner of the view component
<arcgis-map>
  <arcgis-directions api-key="YOUR_API_KEY" slot="top-right"></arcgis-directions>
</arcgis-map>

autoDestroyDisabled

Property

Type: boolean

If true, the component will not be destroyed automatically when it is disconnected from the document. This is useful when you want to move the component to a different place on the page, or temporarily hide it. If this is set, make sure to call the destroy() method when you are done to prevent memory leaks.

Attribute: auto-destroy-disabled
Default value: false

autoSolveOnEditActive

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

When true, the route will re-solve continuously as an interactive operation is ongoing (e.g., while dragging a stop or waypoint).

Attribute: auto-solve-on-edit-active
Default value: false

goToOverride

Property

Type: GoToOverride | null | undefined

Since: ArcGIS Maps SDK for JavaScript 4.33

This function provides the ability to override either the arcgis-map.goTo() or arcgis-scene.goTo() methods.

Example

component.goToOverride = function(view, goToParams) {
  goToParams.options = {
    duration: updatedDuration
  };
  return view.goTo(goToParams.target, goToParams.options);
};

headingLevel

Property

Type: HeadingLevel

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 component's placement in your app, you may need to adjust this heading for proper semantics. This is important for meeting accessibility standards.

See also

Heading Elements

Attribute: heading-level
Default value: 2

Example

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

hideLayerDetails

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

Indicates whether to a link to the route layer portal-item (if any) will be displayed

Attribute: hide-layer-details
Default value: false

hidePrintButton

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

Indicates whether to the Print button will be displayed

Attribute: hide-print-button
Default value: false

hideSaveAsButton

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

Indicates whether to the Save As button will be displayed

Attribute: hide-save-as-button
Default value: false

hideSaveButton

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

Indicates whether to the Save button will be displayed

Attribute: hide-save-button
Default value: false

icon

autocast Property

Type: Icon["icon"]

Icon which represents the component. Typically used when the component is controlled by another component (e.g. by the Expand component).

See also

Calcite Icons

Attribute: icon
Default value: "right"

label

Property

Type: string

The component's default label.

Attribute: label

lastRoute

readonly Property

Type: RouteLayerSolveResult | null | undefined

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

See also

RouteLayer#solve()

layer

Property

Type: RouteLayer | null | undefined

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

maxStops

Property

Type: number

The maximum number of stops allowed for routing.

Attribute: max-stops
Default value: 50

referenceElement

Property

Type: ArcgisReferenceElement | string | undefined

By assigning the id attribute of the Map or Scene component to this property, you can position a child component anywhere in the DOM while still maintaining a connection to the Map or Scene.

See also

Associate components with a Map or Scene component

Attribute: reference-element

routeLayerItemId

Property

Type: string | undefined

Attribute: route-layer-item-id

searchProperties

Property

Type: SearchProperties | null | undefined

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

Default value: { popupEnabled: false, resultGraphicEnabled: false }

state

readonly Property

Type: State

The current state of the component.

Default value: "disabled"

unit

Property

Type: SystemOrLengthUnit

Unit system (imperial, metric) or specific unit used for displaying the distance values. If not set, the component 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.

Attribute: unit

Example

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

useDefaultRouteLayer

Property

Type: boolean

If true, a new RouteLayer will be created, added to the map and assigned to the layer property.

Attribute: use-default-route-layer
Default value: false

view

Property

Type: MapViewOrSceneView | null | undefined

The view associated with the component.

Note: The recommended approach is to fully migrate applications to use map and scene components and avoid using MapView and SceneView directly. However, if you are migrating a large application from widgets to components, you might prefer a more gradual transition. To support this use case, the SDK includes this view property which connects a component to a MapView or SceneView. Ultimately, once migration is complete, the arcgis-directions component will be associated with a map or scene component rather than using the view property.

Methods

Method	Signature
`componentOnReady` inherited	`componentOnReady(): Promise<this>`
`destroy`	`destroy(): Promise<void>`
`getDirections`	`getDirections(): Promise<RouteLayerSolveResult>`
`save`	`save(): Promise<PortalItem>`
`saveAs`	`saveAs(portalItem: PortalItem, options: { folder: PortalFolder; }): Promise<PortalItem>`
`startEditing`	`startEditing(): Promise<void>`
`stopEditing`	`stopEditing(): Promise<void>`
`zoomToRoute`	`zoomToRoute(): Promise<void>`

componentOnReady

inherited Method

Signature: componentOnReady (): Promise<this>

Inherited from: PublicLitElement

Creates a promise that resolves once the component is fully loaded.

Returns: Promise<this>

Example

const arcgisDirections = document.querySelector("arcgis-directions");
document.body.append(arcgisDirections);
await arcgisDirections.componentOnReady();
console.log("arcgis-directions is ready to go!");

destroy

Method

Signature: destroy (): Promise<void>

Permanently destroy the component.

Returns: Promise<void>

getDirections

Method

Signature: getDirections (): Promise<RouteLayerSolveResult>

Computes a route and directions. If successfully computed, results will be assigned to the lastRoute property.

Returns: Promise<RouteLayerSolveResult>

save

Method

Signature: save (): Promise<PortalItem>

Saves the currently assigned RouteLayer (see layer) to an existing portal item.

Returns: Promise<PortalItem>

saveAs

Method

Signature: saveAs (portalItem: PortalItem, options: { folder: PortalFolder; }): Promise<PortalItem>

Saves the currently assigned RouteLayer (see layer) to a new portal item.

Parameters

Parameter	Type	Description	Required
portalItem	`PortalItem`
options	`{ folder: PortalFolder; }`

Returns: Promise<PortalItem>

startEditing

Method

Signature: startEditing (): Promise<void>

Starts an edit session for interactive addition, modification, and deletion of stops, barriers, and waypoints.

Returns: Promise<void>

stopEditing

Method

Signature: stopEditing (): Promise<void>

Ends an interactive edit session.

Returns: Promise<void>

zoomToRoute

Method

Signature: zoomToRoute (): Promise<void>

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

Returns: Promise<void>

Events

Name	Type
`arcgisPropertyChange`	CustomEvent<{ name: "lastRoute" \| "state"; }>
`arcgisReady`	CustomEvent<void>

arcgisPropertyChange

Event

arcgisPropertyChange: CustomEvent<{ name: "lastRoute" | "state"; }>

Emitted when the value of a property is changed. Use this to listen to changes to properties.

arcgisReady

Event

arcgisReady: CustomEvent<void>

Emitted when the component associated with a map or scene view is ready to be interacted with.