arcgis-track | References | ArcGIS Maps SDK for JavaScript

ESM

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

Inheritance:: ArcgisTrack→PublicLitElement

Since: ArcGIS Maps SDK for JavaScript 4.28

The Track component is a button that when activated continuously animates the Map or Scene to the user's location as the user moves. The view rotates based on device heading, and the default heading symbol will display when speed is greater than zero and the browser provides heading information.

This component uses the browser's Geolocation API which is only available in secure contexts, such as HTTPS. Note that localhost is considered "potentially secure" and can be used for easy testing in browsers that support Window.isSecureContext.

Known limitations

The heading symbol is not currently supported within an arcgis-scene.

Demo

Properties

Property	Attribute	Type
`autoDestroyDisabled`	`auto-destroy-disabled`	`boolean`
`error`		`Error \| GeolocationPositionError \| null \| undefined`
`geolocationOptions`		`PositionOptions \| null \| undefined`
`goToLocationDisabled` reflected	`go-to-location-disabled`	`boolean`
`goToOverride`		`GoToOverride \| null \| undefined`
`graphic`		`Graphic`
`icon`	`icon`	`IconName \| undefined`
`label`	`label`	`string \| undefined`
`messageOverrides`		`Record<string, unknown> \| undefined`
`positionFilterFunction`		`PositionFilterFunction \| null \| undefined`
`referenceElement`	`reference-element`	`ArcgisReferenceElement \| string \| undefined`
`rotationDisabled`	`rotation-disabled`	`boolean`
`scale`	`scale`	`number \| null \| undefined`
`state` readonly		`TrackViewModelState`
`tracking` readonly		`boolean`
`view`		`MapViewOrSceneView \| null \| undefined`
`visualScale`	`visual-scale`	`Button["scale"]`

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

error

Property

Type: Error | GeolocationPositionError | null | undefined

Since: ArcGIS Maps SDK for JavaScript 4.29

Error that caused the last track-error event to fire.

Example

if(track.viewModel.state === 'error')
  console.error(track.viewModel.error);

geolocationOptions

Property

Type: PositionOptions | null | undefined

An object used for setting optional position parameters. Refer to the Geolocation API Specification for details on using these parameters.

Example

const track = new Track({
  view: view,
  // Set optional position parameters
  geolocationOptions: {
    maximumAge: 0,
    timeout: 15000,
    enableHighAccuracy: true
  }
});

goToLocationDisabled

reflected Property

Type: boolean

Indicates whether to navigate the view to the position and scale of the geolocated result.

Attribute: go-to-location-disabled
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);
};

graphic

Property

Type: Graphic

The graphic used to show the user's location on the map.

Example

const trackComponent = document.createElement("arcgis-track");
// Overwrite the default symbol used for the
// graphic placed at the location of the user
trackComponent.graphic = new Graphic ({
 symbol: {
   // autocasts as new SimpleMarkerSymbol()
   type: "simple-marker",
   size: "12px",
   color: "blue",
   // autocasts as new SimpleLineSymbol()
   outline: {
     color: "#efefef",
     width: "1.5px"
   }
 }
});

icon

Property

Type: IconName | undefined

Icon displayed in the component's button.

See also

Calcite Icons

Attribute: icon
Default value: "compass-north-circle"

label

Property

Type: string | undefined

The component's default label.

Attribute: label

messageOverrides

Property

Type: Record<string, unknown> | undefined

Replace localized message strings with your own strings.

Note: Individual message keys may change between releases.

positionFilterFunction

Property

Type: PositionFilterFunction | null | undefined

A function that is used as an expression to evaluate geolocation points, and returns a boolean value. If the function returns true, the component will draw a graphic and navigate to the position. The component will ignore false values and not draw a graphic and not navigate to the position.

Example use cases include smoothing out geolocation anomalies and geofencing.

Example

// Exclude locations that full outside an extent.
trackComponent.positionFilterFunction = (value) => {
  const { longitude, latitude } = value.position.coords;
  const myLocation = new Point({ longitude, latitude });
  const geofenceExtent = new Extent({
    // whatever
  });
  return geometryEngine.within(myLocation, geofenceExtent);
};

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

rotationDisabled

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 4.33

Indicates whether the component will automatically rotate to the device heading based on the Geolocation APIs GeolocationCoordinates.heading property. The map will not rotate if the speed is 0, or if the device is unable to provide heading information.

Attribute: rotation-disabled
Default value: false

scale

Property

Type: number | null | undefined

Indicates the scale to set on the view when navigating to the position of the geolocated result, after a location is returned.

By default, the view will navigate to a scale of 2500 for 3D and 4514 for 2D. To override the default in 2D, set the scale property and also set snapToZoom to false. For 2D views the value should be within the effectiveMinScale and effectiveMaxScale.

Attribute: scale

state

readonly Property

Type: TrackViewModelState

The current state of the component.

Default value: "disabled"

tracking

readonly Property

Type: boolean

Indicates whether new positions are being watched.

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-track component will be associated with a map or scene component rather than using the view property.

visualScale

Property

Type: Button["scale"]

Since: ArcGIS Maps SDK for JavaScript 5.0

Specifies the size of the component.

Attribute: visual-scale
Default value: "m"

Methods

Method	Signature
`componentOnReady` inherited	`componentOnReady(): Promise<this>`
`destroy`	`destroy(): Promise<void>`
`start`	`start(): Promise<void>`
`stop`	`stop(): 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 arcgisTrack = document.querySelector("arcgis-track");
document.body.append(arcgisTrack);
await arcgisTrack.componentOnReady();
console.log("arcgis-track is ready to go!");

destroy

Method

Signature: destroy (): Promise<void>

Permanently destroy the component.

Returns: Promise<void>

start

Method

Signature: start (): Promise<void>

Start tracking the user's location. Only start the component on a user gesture such as a click event.

Returns: Promise<void>

stop

Method

Signature: stop (): Promise<void>

Stop tracking the user's location.

Returns: Promise<void>

Events

Name	Type
`arcgisComplete`	CustomEvent<TrackViewModelTrackEvent>
`arcgisError`	CustomEvent<TrackViewModelTrackErrorEvent>
`arcgisPropertyChange`	CustomEvent<{ name: "state"; }>
`arcgisReady`	CustomEvent<void>

arcgisComplete

Event

arcgisComplete: CustomEvent<TrackViewModelTrackEvent>

arcgisError

Event

arcgisError: CustomEvent<TrackViewModelTrackErrorEvent>

arcgisPropertyChange

Event

arcgisPropertyChange: CustomEvent<{ name: "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.