arcgis-locate | References | ArcGIS Maps SDK for JavaScript

ESM

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

Inheritance:: ArcgisLocate→PublicLitElement

Since: ArcGIS Maps SDK for JavaScript 4.28

The Locate component animates the Map or Scene to the user's current location.

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.

Demo

Properties

Property	Attribute	Type
`autoDestroyDisabled`	`auto-destroy-disabled`	`boolean`
`geolocationOptions`		`PositionOptions \| undefined`
`goToLocationDisabled` reflected	`go-to-location-disabled`	`boolean`
`goToOverride`		`GoToOverride \| undefined`
`graphic`		`Graphic`
`icon`	`icon`	`IconName \| undefined`
`label`	`label`	`string \| undefined`
`messageOverrides`		`Record<string, unknown> \| undefined`
`popupDisabled`	`popup-disabled`	`boolean`
`referenceElement`	`reference-element`	`ArcgisReferenceElement \| string \| undefined`
`scale`	`scale`	`number \| undefined`
`state` readonly		`State`
`view`		`MapView \| SceneView \| 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

geolocationOptions

Property

Type: PositionOptions | undefined

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 | 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.

icon

Property

Type: IconName | undefined

Icon displayed in the component's button.

See also

Calcite Icons

Attribute: icon
Default value: "gps-off"

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.

popupDisabled

Property

Type: boolean

Attribute: popup-disabled
Default value: false

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

scale

Property

Type: number | undefined

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

Attribute: scale
Default value: null

state

readonly Property

Type: State

The current state of the component.

view

Property

Type: MapView | SceneView | 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-locate 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
`cancelLocate`	`cancelLocate(): Promise<void>`
`componentOnReady` inherited	`componentOnReady(): Promise<this>`
`destroy`	`destroy(): Promise<void>`
`locate`	`locate(): Promise<GeolocationPosition \| null>`

cancelLocate

Method

Signature: cancelLocate (): Promise<void>

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

Returns: 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 arcgisLocate = document.querySelector("arcgis-locate");
document.body.append(arcgisLocate);
await arcgisLocate.componentOnReady();
console.log("arcgis-locate is ready to go!");

destroy

Method

Signature: destroy (): Promise<void>

Permanently destroy the component.

Returns: Promise<void>

locate

Method

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

Returns: Promise<GeolocationPosition | null>

Events

Name	Type
`arcgisError`	CustomEvent<{ error: GeolocationPositionError; }>
`arcgisPropertyChange`	CustomEvent<{ name: "state"; }>
`arcgisReady`	CustomEvent<void>
`arcgisSuccess`	CustomEvent<{ position: GeolocationPosition; }>

arcgisError

Event

arcgisError: CustomEvent<{ error: GeolocationPositionError; }>

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.

arcgisSuccess

Event

arcgisSuccess: CustomEvent<{ position: GeolocationPosition; }>