arcgis-home | References | ArcGIS Maps SDK for JavaScript

ESM

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

Inheritance: ArcgisHome→PublicLitElement

Since: ArcGIS Maps SDK for JavaScript 4.28

The Home component is a button that navigates back to the initial Viewpoint or a previously defined viewpoint.

Demo

Example

// Create viewpoint centered on extent of a polygon geometry

let vp = new Viewpoint({
  targetGeometry: geom.extent
});

// Sets the Home's viewpoint to that Viewpoint
home.viewpoint = vp;

Properties

Property	Attribute	Type
autoDestroyDisabled	auto-destroy-disabled	boolean
goToOverride		GoToOverride \| undefined
icon	icon	IconName \| undefined
label	label	string \| undefined
messageOverrides		Record<string, unknown> \| undefined
referenceElement	reference-element	ArcgisReferenceElement \| string \| undefined
state readonly		"disabled" \| "going-home" \| "ready"
view		MapView \| SceneView \| undefined
viewpoint		null \| undefined \| Viewpoint
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

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

icon

Property

Type: IconName | undefined

Icon displayed in the component's button.

See also

Calcite Icons

Attribute: icon
Default value: "home"

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.

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: "disabled" | "going-home" | "ready"

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

viewpoint

Property

Type: null | undefined | Viewpoint

The Viewpoint to go to when going "home". The initial value is determined in a few different ways:

If no referenceElement is provided, the value is null. Once the referenceElement is ready, the initial viewpoint value is the user-defined Viewpoint.

Example

// Create viewpoint centered on extent of a polygon geometry

let viewpoint = new Viewpoint({
  targetGeometry: geom.extent
});

// Sets the Home's viewpoint to that Viewpoint
home.viewpoint = viewpoint;

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
cancelGo	cancelGo(): Promise<void>
componentOnReady inherited	componentOnReady(): Promise<this>
destroy	destroy(): Promise<void>
go	go(): Promise<void>

cancelGo

Method

Signature: cancelGo (): Promise<void>

This function provides the ability to interrupt and cancel the process of navigating back to the initial extent.

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

destroy

Method

Signature: destroy (): Promise<void>

Permanently destroy the component.

Returns: Promise<void>

go

Method

Signature: go (): Promise<void>

Animates the map or scene to its initial Viewpoint or the value of viewpoint.

Returns: Promise<void>

Events

Name	Type
arcgisGo	CustomEvent<void>
arcgisPropertyChange	CustomEvent<{ name: "state" \| "viewpoint"; }>
arcgisReady	CustomEvent<void>

arcgisGo

Event

arcgisGo: CustomEvent<void>

Fires when the go() method is called.

Example

home.addEventListener("arcgisGo", (event) => {
  console.log("updating viewpoint");
});

arcgisPropertyChange

Event

arcgisPropertyChange: CustomEvent<{ name: "state" | "viewpoint"; }>

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.