import "@arcgis/map-components/components/arcgis-coordinate-conversion";- Inheritance
- ArcgisCoordinateConversion→
PublicLitElement
The Coordinate Conversion component provides a way to display user cursor position either as map coordinates or as any of several popular coordinate notations. Additionally, the component provides a way to convert user input coordinates into a point.
Several common formats are included by default:
- XY - Longitude, Latitude (WGS84)
- MGRS - Military Grid Reference System
- UTM - Universal Transverse Mercator
- DD - Decimal Degrees
- DDM - Degrees Decimal Minutes
- DMS - Degrees Minutes Seconds
- Basemap - X, Y in the coordinate system used by the current basemap in the units used by the basemap. Web Mercator is the standard for Esri-provided basemaps.
Additional formats can be created by a developer and made available through the component
Demo
- Example
- <arcgis-map item-id="45b3b2fb35e94ab09381d0caa0da5946"><arcgis-coordinate-conversion slot="bottom-left"></arcgis-coordinate-conversion></arcgis-map>
Properties
| Property | Attribute | Type |
|---|---|---|
| auto-destroy-disabled | ||
| | ||
| | ||
| reflected | expanded | |
| | ||
| | ||
| heading-level | ||
| reflected | hide-capture-button | |
| reflected | hide-expand-button | |
| reflected | hide-input-button | |
| reflected | hide-settings-button | |
| icon | ||
| label | ||
| | ||
| reflected | mode | |
| reflected | multiple-conversions-disabled | |
| reflected | orientation | |
| reference-element | ||
| readonly | | |
| reflected | storage-disabled | |
| storage-type | ||
| |
autoDestroyDisabled
- 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
conversions
- Type
- Collection<Conversion>
- Since
- ArcGIS Maps SDK for JavaScript 4.7
A collection of conversions that the component is currently displaying. Each row in the component displaying a coordinate is a conversion.
- Example
Conversions can be set with an array of strings where each string is a format's name.
coordinateConversionComponent.conversions = ["mgrs"];
currentLocation
- Since
- ArcGIS Maps SDK for JavaScript 4.7
Describes the location of the coordinates currently displayed by the component as a Point. Setting this property will update all conversions.
- Example
Set the current location.
coordinateConversionComponent.currentLocation = { x: 77.0369, y: 38.9072, spatialReference: { wkid: 4326 } };
expanded
- Type
- boolean
Describes whether the component is expanded or not. If true, the component is expanded and all conversions are visible.
- Attribute
- expanded
- Default value
- false
- Example
Expand the component.
coordinateConversionComponent.expanded = true;
formats
- Type
- Collection<Format>
A collection containing every coordinate format that the component is capable of displaying.
The default formats are basemap, dd, ddm, dms, mgrs, usng, utm, and xy.
- Examples
Only show the "xy" format.
const coordinateConversionComponent = document.getElementsByTagName("arcgis-coordinate-conversion")[0];const toRemove = coordinateConversionComponent.formats.filter(format => format.name !== "xy");coordinateConversionComponent.formats.removeMany(toRemove);Show every format except "xy".
const coordinateConversionComponent = document.getElementsByTagName("arcgis-coordinate-conversion")[0];const toRemove = coordinateConversionComponent.formats.filter(format => format.name === "xy");coordinateConversionComponent.formats.removeMany(toRemove);
goToOverride
- 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
- Type
- HeadingLevel
Indicates the heading level to use for the coordinate input and coordinate settings headings. By default,
these headings are rendered as level 4 headings (e.g. <h4>Input coordinate</h4>). Depending on the coordinate conversion component's
placement in your app, you may need to adjust this heading for proper semantics. This is important for meeting
accessibility standards.
- Attribute
- heading-level
- Default value
- 4
hideCaptureButton
- Type
- boolean
Determines whether the capture button will be shown in the component. If true, the capture button will be hidden.
- Attribute
- hide-capture-button
- Default value
- false
- Example
Hide the capture button.
<arcgis-map item-id="45b3b2fb35e94ab09381d0caa0da5946"><arcgis-coordinate-conversion hide-capture-button slot="bottom-left"></arcgis-coordinate-conversion></arcgis-map>
hideExpandButton
- Type
- boolean
Determines whether the expand button will be shown in the component. If true, the expand button will be hidden.
- Attribute
- hide-expand-button
- Default value
- false
- Example
Hide the expand button.
<arcgis-map item-id="45b3b2fb35e94ab09381d0caa0da5946"><arcgis-coordinate-conversion hide-expand-button slot="bottom-left"></arcgis-coordinate-conversion></arcgis-map>
hideInputButton
- Type
- boolean
Determines whether the input coordinate button will be shown in the component. If true, the input button will be hidden.
- Attribute
- hide-input-button
- Default value
- false
- Example
Hide the input button.
<arcgis-map item-id="45b3b2fb35e94ab09381d0caa0da5946"><arcgis-coordinate-conversion hide-input-button slot="bottom-left"></arcgis-coordinate-conversion></arcgis-map>
hideSettingsButton
- Type
- boolean
Determines whether the settings button will be shown in the component. If true, the settings button will be hidden.
- Attribute
- hide-settings-button
- Default value
- false
- Example
Hide the settings button.
<arcgis-map item-id="45b3b2fb35e94ab09381d0caa0da5946"><arcgis-coordinate-conversion hide-settings-button slot="bottom-left"></arcgis-coordinate-conversion></arcgis-map>
icon
- Type
- IconName
Icon which represents the component. Typically used when the component is controlled by another component (e.g. by the Expand component). Search Calcite Icons for possible values.
- Attribute
- icon
- Default value
- "coordinate-system"
locationSymbol
This symbol is used to visualize the location currently described by the component when capture mode
is active.
This property should be set to a point symbol, typically a Simple Marker Symbol.
- Example
Set the location symbol to be an 'x'.
const coordinateConversionComponent = document.getElementsByTagName("arcgis-coordinate-conversion")[0];coordinateConversionComponent.locationSymbol = { type: "simple-marker", style: "x" };
mode
- Type
- Mode
Describes the current mode of the component.
- While in
livemode, the component will update as the cursor moves. - While in
capturemode, the component will update on mouse click and display a graphic marking the current location.
- Attribute
- mode
- Default value
- "live"
- Example
Programmatically set the component to capture mode.
const coordinateConversionComponent = document.getElementsByTagName("arcgis-coordinate-conversion")[0];coordinateConversionComponent.mode = "capture";
multipleConversionsDisabled
- Type
- boolean
If this property is set to true, multiple conversions will be disabled, and only a single conversion will be displayed. Otherwise, multiple conversions will be shown.
- Attribute
- multiple-conversions-disabled
- Default value
- false
orientation
- Type
- Orientation
Determines whether the component should expand up or down. If set to auto,
the component will be oriented based on its position in the view.
- Attribute
- orientation
- Default value
- "auto"
referenceElement
- 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.
- Attribute
- reference-element
storageDisabled
- Type
- boolean
If this property is set to true, sessionStorage or localStorage (depending on storageType)
will not be used to hydrate and persist the component's state.
- Attribute
- storage-disabled
- Default value
- false
storageType
- Type
- StorageType
- Since
- ArcGIS Maps SDK for JavaScript 4.23
This property determines whether sessionStorage or localStorage will be used to store component's state.
- Attribute
- storage-type
- Default value
- "session"
view
- 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
viewproperty which connects a component to a MapView or SceneView. Ultimately, once migration is complete, the arcgis-coordinate-conversion component will be associated with a map or scene component rather than using theviewproperty.
Methods
| Method | Signature |
|---|---|
| inherited | componentOnReady(): Promise<this> |
| destroy(): Promise<void> | |
| reverseConvert(coordinate: string, format: Format): Promise<Point | null | undefined> |
componentOnReady
- Signature
-
componentOnReady (): Promise<this>
Creates a promise that resolves once the component is fully loaded.
- Returns
- Promise<this>
- Example
- const arcgisCoordinateConversion = document.querySelector("arcgis-coordinate-conversion");document.body.append(arcgisCoordinateConversion);await arcgisCoordinateConversion.componentOnReady();console.log("arcgis-coordinate-conversion is ready to go!");
reverseConvert
- Signature
-
reverseConvert (coordinate: string, format: Format): Promise<Point | null | undefined>
Attempt to convert a string into a point. The format of the string must be specified. A collection of available formats can be obtained from the formats property.
Events
| Name | Type |
|---|---|
| CustomEvent<{ name: "currentLocation" | "state" | "expanded" | "mode"; }> | |
arcgisConversionChange
arcgisConversionChange: CustomEvent<void> - Since
- ArcGIS Maps SDK for JavaScript 4.34
Emitted when a conversion is added or removed, or when the order of conversions changes.
arcgisPropertyChange
arcgisPropertyChange: CustomEvent<{ name: "currentLocation" | "state" | "expanded" | "mode"; }> Emitted when the value of a property is changed. Use this to listen to changes to properties.
arcgisReady
arcgisReady: CustomEvent<void> Emitted when the component associated with a map or scene view is ready to be interacted with.