arcgis-coordinate-conversion | References | ArcGIS Maps SDK for JavaScript

ESM

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
`autoDestroyDisabled`	`auto-destroy-disabled`	`boolean`
`conversions`		`Collection<Conversion>`
`currentLocation`		`Point \| null \| undefined`
`expanded` reflected	`expanded`	`boolean`
`formats`		`Collection<Format>`
`goToOverride`		`GoToOverride \| null \| undefined`
`headingLevel`	`heading-level`	`HeadingLevel`
`hideCaptureButton` reflected	`hide-capture-button`	`boolean`
`hideExpandButton` reflected	`hide-expand-button`	`boolean`
`hideInputButton` reflected	`hide-input-button`	`boolean`
`hideSettingsButton` reflected	`hide-settings-button`	`boolean`
`icon`	`icon`	`IconName`
`label`	`label`	`string \| undefined`
`locationSymbol`		`PictureMarkerSymbol \| SimpleMarkerSymbol \| CIMSymbol \| PointSymbol3D`
`mode` reflected	`mode`	`Mode`
`multipleConversionsDisabled` reflected	`multiple-conversions-disabled`	`boolean`
`orientation` reflected	`orientation`	`Orientation`
`referenceElement`	`reference-element`	`ArcgisReferenceElement \| string \| undefined`
`state` readonly		`CoordinateConversionViewModelState`
`storageDisabled` reflected	`storage-disabled`	`boolean`
`storageType`	`storage-type`	`StorageType`
`view`		`MapViewOrSceneView \| null \| undefined`

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

conversions

Property

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

Property

Type: Point | null | undefined

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

reflected Property

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

Property

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

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

headingLevel

Property

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

reflected Property

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

reflected Property

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

reflected Property

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

reflected Property

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

Property

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"

label

Property

Type: string | undefined

The component's default label.

Attribute: label
Default value: "Coordinate conversion"

locationSymbol

Property

Type: PictureMarkerSymbol | SimpleMarkerSymbol | CIMSymbol | PointSymbol3D

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

reflected Property

Type: Mode

Describes the current mode of the component.

While in live mode, the component will update as the cursor moves.
While in capture mode, 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

reflected Property

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

reflected Property

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

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

state

readonly Property

Type: CoordinateConversionViewModelState

The current state of the component.

Default value: "disabled"

storageDisabled

reflected Property

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

Property

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.

See also

Attribute: storage-type
Default value: "session"

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

Methods

Method	Signature
`componentOnReady` inherited	`componentOnReady(): Promise<this>`
`destroy`	`destroy(): Promise<void>`
`reverseConvert`	`reverseConvert(coordinate: string, format: Format): Promise<Point \| null \| undefined>`

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

destroy

Method

Signature: destroy (): Promise<void>

Permanently destroy the component.

Returns: Promise<void>

reverseConvert

Method

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.

Parameters

Parameter	Type	Description	Required
coordinate	`string`	The coordinate string.
format	`Format`	Specifies the format of the input coordinate.

Returns: Promise<Point | null | undefined>
When resolved, returns a point.

Events

Name	Type
`arcgisConversionChange`	CustomEvent<void>
`arcgisPropertyChange`	CustomEvent<{ name: "currentLocation" \| "state" \| "expanded" \| "mode"; }>
`arcgisReady`	CustomEvent<void>

arcgisConversionChange

Event

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

Event

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

Event

arcgisReady: CustomEvent<void>

Emitted when the component associated with a map or scene view is ready to be interacted with.