Hide Table of Contents
esri/dijit/util
esri/layer/pixelFilters
esri/process
esri/workers
Class: LocateButton

require(["esri/dijit/LocateButton"], function(LocateButton) { /* code goes here */ });

Description

(Added at v3.7)

LocateButton provides a simple button to locate and zoom to the user's location.

The Locate widget is only supported on secure web pages (https) and localhost.

As of version 3.19, the Locate Button no longer displays on non-secure web apps. At version 3.18 this only applied to Google Chrome. Note that localhost is considered "potentially secure" and can be used for easy testing.

If the spatial reference of the map is not Web Mercator (wkid 3857) or WGS84 (wkid 4326) then you must set a default GeometryService in the default API configurations of esri/config so the user's location can be reprojected to the spatial reference of the map.

esriConfig.defaults.geometryService = new GeometryService("http://yourdomain.com/geometryService");

Samples

Search for samples that use this class.

Constructors

NameSummary
new LocateButton(params, srcNodeRef)Creates a new LocateButton dijit using the given DOM node.

CSS

esri/dijit/LocateButton | Download source

NameDescription
loadingClass put onto the button while extent is loading.
locateContainerContaining class for the widget's node.
trackingClass for styling the tracking icon when the widget is actively tracking. Only applies if useTracking is set to true.
zoomLocateButtonClass for the button.

Properties

NameTypeSummary
centerAtBooleanCenters the map to the location when a new position is returned.
clearOnTrackingStopBooleanRemoves existing graphic when tracking stops.
geolocationOptionsObjectThe HTML5 Geolocation Position options for locating.
graphicsLayerGraphicsLayerLayer in which the highlighted graphic is set to.
highlightLocationBooleanIf true, the users location will be highlighted with a point.
infoTemplateInfoTemplateThe infoTemplate used for the highlight graphic.
loadedBooleanWhether the widget has been loaded.
mapMapMap object that this dijit is associated with.
scaleNumberThe scale to zoom to when a users location has been found.
setScaleBooleanSets the maps scale when a new position is returned.
symbolSymbolThe symbol used on the highlight graphic to highlight the users location on the map.
themeStringClass used for styling the widget.
trackingBooleanShows the current tracking state.
useTrackingBooleanWhen enabled, the button becomes a toggle that creates an event to watch for location changes.
visibleBooleanWhether the widget is visible.

Methods

NameReturn typeSummary
clear()NoneClears the point graphic.
destroy()NoneDestroys the widget.
hide()NoneHides the widget.
locate()PromiseGoes to the users extent.
show()NoneShows the widget.
startup()NoneFinalizes the creation of this dijit.

Events

[ On Style Events | Connect Style Event ]
All On Style event listeners receive a single event object. Additionally, the event object also contains a 'target' property whose value is the object which fired the event.

Events

NameEvent ObjectSummary
loadFires when the widget has been loaded.
locate
{
  error: <Object>,
  graphic: <Graphic>,
  position: <Object>,
  scale: <Number>
}
Fires when the locate method has been called.
Constructor Details

new LocateButton(params, srcNodeRef)

Creates a new LocateButton dijit using the given DOM node.
Parameters:
<Object> params Required Various parameters to configure this dijit. See the list below for details.
<Node | String> srcNodeRef Required Reference or id of a HTML element that this dijit is rendered into.
params properties:
<Boolean> centerAt Optional Centers the map to the location when a new position is returned. Defaults to true.
<Object> geolocationOptions Optional The HTML5 Geolocation Position options for locating. Default value is { maximumAge: 0, timeout: 15000, enableHighAccuracy: true }.
<GraphicsLayer> graphicsLayer Optional If highlightLocation is on and this property is set then a graphic will be added to this layer instead of map.graphics. If you supply a graphicsLayer you can have a renderer set for printing this layer.
<Boolean> highlightLocation Optional If true, the users location will be highlighted with a point. Default value is true.
<InfoTemplate> infoTemplate Optional The infoTemplate used for the highlight graphic. Default value is null.
<Map> map Required Map object that this dijit is associated with. Required.
<Number> scale Optional The scale to zoom to when a users location has been found. By default scale is according to accuracy in meters returned from geolocation.
<Boolean> setScale Optional Sets the maps scale when a new position is returned. Defaults to true.
<Symbol> symbol Optional The symbol used on the highlight graphic to highlight the users location on the map. Default value is PictureMarkerSymbol(require.toUrl("esri/dijit") + '/images/blue-dot.png', 21, 21).
<String> theme Optional Class used for styling the widget. Default value is "LocateButton".
<Boolean> useTracking Optional When enabled, the button becomes a toggle that creates an event to watch for location changes. Defaults to false.
<Boolean> visible Optional Whether the widget is visible by default. Default value is true.
Sample:
var locateButton = new LocateButton({
  map: map
}, "<dom_id>");
Property Details

<Boolean> centerAt

Centers the map to the location when a new position is returned. (Added at v3.8)
Known values: true | false
Default value: true

<Boolean> clearOnTrackingStop

Removes existing graphic when tracking stops. (Added at v3.11)
Known values: true | false
Default value: false

<Object> geolocationOptions

The HTML5 Geolocation Position options for locating. Refer to Geolocation API Specification for details.
Default value: { maximumAge: 0, timeout: 15000, enableHighAccuracy: true}

<GraphicsLayer> graphicsLayer

Layer in which the highlighted graphic is set to. If null, highlighted graphic will be added to map.graphics. (Added at v3.9)

<Boolean> highlightLocation

If true, the users location will be highlighted with a point.
Known values: true | false
Default value: true

<InfoTemplate> infoTemplate

The infoTemplate used for the highlight graphic.

<Boolean> loaded

Whether the widget has been loaded.
Known values: true | false

<Map> map

Map object that this dijit is associated with.

<Number> scale

The scale to zoom to when a users location has been found.
Default value: null 

<Boolean> setScale

Sets the maps scale when a new position is returned. (Added at v3.8)
Known values: true | false
Default value: true

<Symbol> symbol

The symbol used on the highlight graphic to highlight the users location on the map.
Default value: PictureMarkerSymbol(require.toUrl("esri/dijit") + '/images/blue-dot.png', 21, 21)

<String> theme

Class used for styling the widget.
Default value: "LocateButton"

<Boolean> tracking

Shows the current tracking state. If the widget is currently watching for new positions or not. (Added at v3.8)
Known values: true | false

<Boolean> useTracking

When enabled, the button becomes a toggle that creates an event to watch for location changes. (Added at v3.8)
Known values: true | false
Default value: false

<Boolean> visible

Whether the widget is visible.
Known values: true | false
Default value: true
Method Details

clear()

Clears the point graphic.

destroy()

Destroys the widget.

hide()

Hides the widget.

locate()

Goes to the users extent.
Return type: Promise

show()

Shows the widget.

startup()

Finalizes the creation of this dijit. This method should be called after the constructor for this dijit is called and before letting the users interact with it.
Event Details
[ On Style Events | Connect Style Event ]

load

Fires when the widget has been loaded.

locate

Fires when the locate method has been called.
Event Object Properties:
<Object> error An error objection. Returned if an error has occurred.
<Graphic> graphic The graphic used to set current location.
<Object> position Geoposition returned from Geolocation API.
<Number> scale Scale in meters to set the map to. Based on accuracy.