LocateViewModel | References | ArcGIS Maps SDK for JavaScript

import LocateViewModel from "@arcgis/core/widgets/Locate/LocateViewModel.js";

Inheritance:: LocateViewModel→GeolocationPositioning→Accessor

Since: ArcGIS Maps SDK for JavaScript 4.0

Provides the logic for the Locate component and Locate widget, which animates the View to the user's current location.

The (geolocation) functionality is not supported on insecure origins. To use it, switch your application to a secure origin, such as HTTPS. Note that localhost is considered "potentially secure" and can be used for easy testing in browsers that supports Window.isSecureContext (currently Chrome and Firefox).

As of version 4.2, the Locate Button no longer displays in non-secure web apps. At version 4.1 this only applied to Google Chrome.

See also

Locate component
Locate widget - Deprecated since 4.32. Use the Locate component instead.
Programming patterns: Widget viewModel pattern

Example

let locateWidget = new Locate({
  viewModel: { // autocasts as new LocateViewModel()
    view: view   // attaches the Locate button to the view
  },
  container: "locateDiv"
});

Constructors

Constructor

Parameters

Parameter	Type	Description	Required
properties	`LocateViewModelProperties`

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

Properties

Any properties can be set, retrieved or listened to. See the Watch for changes topic.

Property	Type	Class
`declaredClass` readonly inherited	`string`	Accessor
`error`	`GeolocationPositionError \| Error \| null \| undefined`
`geolocationOptions` inherited	`PositionOptions \| null \| undefined`	GeolocationPositioning
`goToLocationEnabled` inherited	`boolean`	GeolocationPositioning
`goToOverride` inherited	`GoToOverride \| null \| undefined`	GoTo
`graphic` inherited	`Graphic`	GeolocationPositioning
`popupEnabled`	`boolean`
`scale` inherited	`number \| null \| undefined`	GeolocationPositioning
`state` readonly	`LocateViewModelState`
`view` inherited	`MapViewOrSceneView \| null \| undefined`	GeolocationPositioning

declaredClass

readonlyinherited Property

Type: string

Inherited from: Accessor

Since: ArcGIS Maps SDK for JavaScript 4.7

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

error

Property

Type: GeolocationPositionError | Error | null | undefined

Since: ArcGIS Maps SDK for JavaScript 4.29

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

Example

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

geolocationOptions

inherited Property

Type: PositionOptions | null | undefined

Inherited from: GeolocationPositioning

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
  }
});

goToLocationEnabled

inherited Property

Type: boolean

Inherited from: GeolocationPositioning

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

Default value: true

goToOverride

inherited Property

Type: GoToOverride | null | undefined

Inherited from: GoTo

Since: ArcGIS Maps SDK for JavaScript 4.8

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

See also

Example

// The following snippet uses Search 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);
};

graphic

autocast inherited Property

Type: Graphic

Inherited from: GeolocationPositioning

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

Example

const trackWidget = new Track({
  // Assign the track widget to a view
  view: view,
  // Overwrite the default symbol used for the
  // graphic placed at the location of the user
  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"
     }
   }
 })
});

popupEnabled

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 4.19

Indicates whether to display the Popup of the result graphic from the locate() method.

See also

Search.popupEnabled

Default value: true

scale

inherited Property

Type: number | null | undefined

Inherited from: GeolocationPositioning

Since: ArcGIS Maps SDK for JavaScript 4.7

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.

state

readonly Property

Type: LocateViewModelState

The current state of the widget.

Default value: "disabled"

view

inherited Property

Type: MapViewOrSceneView | null | undefined

Inherited from: GeolocationPositioning

The view associated with the widget.

Methods

Method	Signature	Class
`cancelLocate`	`cancelLocate(): void`
`emit` inherited	`emit<Type extends EventNames<this>>(type: Type, event?: this["@eventTypes"][Type]): boolean`	EventedMixin
`hasEventListener` inherited	`hasEventListener<Type extends EventNames<this>>(type: Type): boolean`	EventedMixin
`locate`	`locate(): Promise<GeolocationPosition \| null>`
`on` inherited	`on<Type extends EventNames<this>>(type: Type, listener: EventedCallback<this["@eventTypes"][Type]>): ResourceHandle`	EventedMixin

cancelLocate

Method

Signature: cancelLocate (): void

Since: ArcGIS Maps SDK for JavaScript 4.9

This function provides the ability to interrupt and cancel the process of programmatically obtaining the location of the user's device.

Returns: void

emit

inherited Method

Signature: emit <Type extends EventNames<this>>(type: Type, event?: this["@eventTypes"][Type]): boolean

Type parameters: <Type extends EventNames<this>>

Inherited from: EventedMixin

Since: ArcGIS Maps SDK for JavaScript 4.5

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

Parameters

Parameter	Type	Description	Required
type	`Type`	The name of the event.
event	`this["@eventTypes"][Type]`	The event payload.

Returns: boolean
true if a listener was notified

hasEventListener

inherited Method

Signature: hasEventListener <Type extends EventNames<this>>(type: Type): boolean

Type parameters: <Type extends EventNames<this>>

Inherited from: EventedMixin

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

Parameters

Parameter	Type	Description	Required
type	`Type`	The name of the event.

Returns: boolean
Returns true if the class supports the input event.

locate

Method

Signature: locate (): Promise<GeolocationPosition | null>

Animates the view to the user's location.

Returns: Promise<GeolocationPosition | null>
Resolves to an object with the same specification as the event object defined in the locate event.

Example

let locateWidget = new Locate({
  viewModel: { // autocasts as new LocateViewModel()
    view: view
  },
  container: "locateDiv"
});

locateWidget.locate().then(function(){
  // Fires after the user's location has been found
});

on

inherited Method

Signature: on <Type extends EventNames<this>>(type: Type, listener: EventedCallback<this["@eventTypes"][Type]>): ResourceHandle

Type parameters: <Type extends EventNames<this>>

Inherited from: EventedMixin

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

Parameters

Parameter	Type	Description	Required
type	`Type`	An event or an array of events to listen for.
listener	`EventedCallback<this["@eventTypes"][Type]>`	The function to call when the event fires.

Returns

ResourceHandle

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);
});

Events

Name	Type
`locate`	CustomEvent<LocateViewModelLocateEvent>
`locate-error`	CustomEvent<LocateViewModelLocateErrorEvent>

locate

Event

locate: CustomEvent<LocateViewModelLocateEvent>

Fires after the locate() method is called and succeeds.

See also

locate()

Example

locateBtn.on("locate", ({ position }) => {
  const { longitude, latitude } = position.coords;
  console.log(`lat: ${latitude.toFixed(4)}, long: ${longitude.toFixed(4)}`);
})

locate-error

Event

locate-error: CustomEvent<LocateViewModelLocateErrorEvent>

Fires after the Locate.locate() method is called and fails.

See also

locate()

Type definitions

LocateViewModelState

Type definition

Type: "disabled" | "ready" | "locating" | "feature-unsupported" | "error"

LocateViewModelLocateEvent

Type definition

position

Property

Type: GeolocationPosition

Position returned from the Geolocation API.

LocateViewModelLocateErrorEvent

Type definition

error

Property

Type: GeolocationPositionError | Error

The Error object that occurred while locating.