import "@arcgis/map-components/components/arcgis-map";
The ArcGIS Map Component is used to add 2D maps to web applications. For 3D maps, use the ArcGIS Scene component.
The Map component creates a MapView and loads a WebMap from either ArcGIS Online or ArcGIS Enterprise portal.
<arcgis-map item-id="05e015c5f0314db9a487a9b46cb37eca"></arcgis-map>
Alternatively, the Map component can be initialized without a WebMap item.
<arcgis-map basemap="satellite" center="-154.88, 19.46" zoom="15"></arcgis-map>
Other components can be added and connected to the Map component.
<arcgis-map item-id="05e015c5f0314db9a487a9b46cb37eca">
<arcgis-zoom position="top-left"></arcgis-zoom>
<arcgis-legend position="bottom-left"></arcgis-legend>
</arcgis-map>
The Map component can be customized further using any of the core API functionalities of the ArcGIS Maps SDK for JavaScript.
const arcgisMap = document.querySelector("arcgis-map");
arcgisMap.addEventListener("arcgisViewReadyChange", () => {
const layer = new GraphicsLayer({ title: "My Layer" });
arcgisMap.map.add(layer);
});
See also:
Demo
Properties
Property | Attribute | Type |
---|---|---|
allLayerViews readonly |
| |
auto-destroy-disabled | boolean | |
| ||
basemap | Basemap | string | |
| ||
center | Array<number> | Point | string | |
| View2DConstraints | |
display-filter-disabled | boolean | |
| ||
| ||
| Collection<string> | |
gamepad readonly |
| |
| ||
ground | Ground | string | |
highlightOptions deprecated |
| |
| ||
interacting readonly |
| boolean |
| ||
item-id | string | |
layerViews readonly |
| |
magnifier readonly |
| |
| ||
navigating readonly |
| boolean |
| ||
| ViewPadding | |
| ||
popup-disabled | boolean | |
ready readonly |
| boolean |
resize-align | "bottom" | "bottom-left" | "bottom-right" | "center" | "left" | "right" | "top" | "top-left" | "top-right" | |
resolution readonly |
| number |
rotation | number | |
scale | number | |
| ||
stationary readonly |
| boolean |
suspended readonly | suspended | boolean |
| ||
| ||
time-zone | string | |
updating readonly | updating | boolean |
view readonly |
| |
| ||
zoom | number |
allLayerViews
allLayerViews: Collection<LayerView>
Collection containing a flat list of all the created LayerViews related to the basemap, operational layers, and group layers in this view.
autoDestroyDisabled
autoDestroyDisabled: 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
background
background: ColorBackground
The background color of the MapView. If the view's map changes, the view's background
is reset to the map's background,
even if the user set it previously.
- Default value
- null
basemap
basemap: Basemap | string
Specifies a basemap for the map. The basemap is a set of layers that give geographic context to the view and the other operational layers in the map. It can either be set using a basemap ID string (see values), Basemap or BasemapStyle.
- Attribute
- basemap
basemapView
basemapView: BasemapView
Represents the view for a single basemap after it has been added to the map.
center
center: Array<number> | Point | string
Represents the view's center point; when setting the center, you may pass a
esri/geometry/Point instance or a string representing
a longitude/latitude pair ("-100.4593, 36.9014"
).
Setting the center immediately changes the current view.
For animating the view, see this component's goTo() method.
- Attribute
- center
constraints
constraints: View2DConstraints
Specifies constraints to scale, zoom, and rotation that may be applied to the MapView.
displayFilterDisabled
displayFilterDisabled: boolean
Indicates whether layer's displayFilter are honored when rendering layers in the view.
If false
, display filters are ignored and all features are rendered.
- Attribute
- display-filter-disabled
- Default value
- false
extent
extent: Extent
The extent represents the visible portion of a map within the view as an instance of esri/geometry/Extent. Setting the extent immediately changes the view without animation. To animate the view, see this component's goTo() method. When the view is rotated, the extent does not update to include the newly visible portions of the map.
fatalError
fatalError: Error
A rejected view indicates a fatal error making it unable to display.
floors
floors: Collection<string>
Applies a display filter on the view for a specific set of floor levels. It can filter the map display on floor-aware layers by zero or more level IDs.
graphics
graphics: Collection<Graphic>
Allows for adding graphics directly to the default graphics in the View. Example:
// Adds a graphic to the View
graphics.add(pointGraphic);
Example:
// Removes a graphic from the View
graphics.remove(pointGraphic);
highlightOptions
highlightOptions: HighlightOptions
Options for configuring the highlight. Use the highlight method on the
appropriate esri/views/layers/LayerView to highlight a feature.
The layerView's highlightOptions
will take precedence over the MapView's highlightOptions
if both properties are set.
Options for configuring the highlight.
highlights
highlights: Collection<HighlightOptions>
The highlights property is a collection of HighlightGroup objects that allow you to visually emphasize specific features on the map.
interacting
interacting: boolean
Indication whether the view is being interacted with (for example when panning or by an interactive tool).
- Default value
- false
itemId
itemId: string
The ID of a WebMap from ArcGIS Online or ArcGIS Enterprise portal.
To configure the portal url you must set the portalUrl
property on config
before the arcgis-map
component loads.
- Attribute
- item-id
layerViews
layerViews: Collection<LayerView>
A collection containing a hierarchical list of all the created esri/views/layers/LayerView LayerViews of the esri/Map#layers operational layers in the map.
magnifier
magnifier: Magnifier
The magnifier allows for showing a portion of the view as a magnifier image on top of the view.
navigating
navigating: boolean
Indication whether the view is being navigated (for example when panning).
- Default value
- false
padding
padding: ViewPadding
Use the padding property to make the center, and extent, etc.
- Default value
- {left: 0, top: 0, right: 0, bottom: 0}
popup
popup: Popup
A Popup object that displays general content or attributes from layers in the map.
popupDisabled
popupDisabled: boolean
Controls whether the popup opens when users click on the view.
- Attribute
- popup-disabled
- Default value
- false
ready
ready: boolean
When true
, this property indicates whether the view successfully satisfied all dependencies,
signaling that the following conditions are met.
- Default value
- false
resizeAlign
resizeAlign: "bottom" | "bottom-left" | "bottom-right" | "center" | "left" | "right" | "top" | "top-left" | "top-right"
Defines which anchor stays still while resizing the browser window. The default, center
,
ensures the view's center point remains constantly visible as the window size changes. The other
options allow the respective portion of the view to remain visible when the window's size is changed.
- Attribute
- resize-align
- Default value
- "center"
resolution
resolution: number
Represents the current value of one pixel in the unit of the view's spatialReference. The value of resolution is calculated by dividing the view's extent width by its width.
rotation
rotation: number
The clockwise rotation of due north in relation to the top of the view in degrees.
The view may be rotated by directly setting
the rotation or by using the following mouse event: Right-click + Drag
.
Map rotation may be disabled by setting the rotationEnabled
property
in constraints to false
. See the code snippet below for
an example of this.
- Attribute
- rotation
- Default value
- 0
scale
scale: number
Represents the map scale at the center of the view. Setting the scale immediately changes the view. For animating the view, see this component's goTo() method.
- Attribute
- scale
spatialReference
spatialReference: SpatialReference
The spatial reference of the view. This indicates the projected or geographic coordinate system used to locate geographic features in the map.
- Default value
- null
stationary
stationary: boolean
Indication whether the view is animating, being navigated with or resizing.
- Default value
- false
suspended
suspended: boolean
Indicates if the view is visible on the page.
- Attribute
- suspended
- Default value
- true
theme
theme: Theme
This property specifies the base colors used by some widgets and components to render graphics and labels.
- Default value
- null
timeExtent
timeExtent: TimeExtent
The view's time extent. Time-aware layers display their temporal data that falls within the view's time extent. Setting the view's time extent is similar to setting the spatial extent because once the time extent is set, the view updates automatically to conform to the change.
- Default value
- null
timeZone
timeZone: string
Defines the time zone of the view. The time zone property determines how dates and times are represented to the user, but the underlying data is unchanged.
- Attribute
- time-zone
- Default value
- "system"
updating
updating: boolean
Indicates whether the view is being updated by additional data requests to the network, or by processing received data.
- Attribute
- updating
- Default value
- false
viewpoint
viewpoint: Viewpoint
Represents the current view as a Viewpoint or point of observation on the view. Setting the viewpoint immediately changes the current view. For animating the view, see this component's goTo() method.
zoom
zoom: number
Represents the level of detail (LOD) at the center of the view. A zoom level (or scale) is a number that defines how large or small the contents of a map appear in a map view. Zoom level is a number usually between 0 (global view) and 23 (very detailed view) and is used as a shorthand for predetermined scale values. A value of -1 means the view has no LODs. When setting the zoom value, the MapView converts it to the corresponding scale, or interpolates it if the zoom is a fractional number. MapView can display maps with different projections at a full range of scales, and so use the scale property on this component rather than zoom level.
Setting the zoom immediately changes the current view. For animating the view, see this component's goTo() method.
Setting this property in conjunction with center
is a convenient way to set the initial extent of the view.
- Attribute
- zoom
Methods
Method | Signature |
---|---|
addLayer(layer: __esri.Layer | Promise<any>, index?: number): Promise<void> | |
addLayers(layers: __esri.Layer[], index?: number): Promise<void> | |
addTable(table: __esri.FeatureLayer): Promise<void> | |
addTables(tables: __esri.FeatureLayer[], index?: number): Promise<void> | |
closePopup(): Promise<void> | |
componentOnReady(): Promise<void> | |
destroy(): Promise<void> | |
goTo(target: __esri.GoToTarget2D, options?: __esri.GoToOptions2D): Promise<unknown> | |
hitTest(screenPoint: __esri.MapViewScreenPoint | MouseEvent, options?: __esri.MapViewHitTestOptions): Promise<__esri.HitTestResult> | |
openPopup(options?: __esri.PopupViewOpenPopupOptions): Promise<void> | |
takeScreenshot(options?: __esri.MapViewTakeScreenshotOptions): Promise<__esri.Screenshot> | |
toMap(screenPoint: __esri.MapViewScreenPoint | MouseEvent): __esri.Point | |
toScreen(point: __esri.Point, options?: __esri.ToScreenOptions2D): __esri.MapViewScreenPoint | nullish | |
tryFatalErrorRecovery(): Promise<void> | |
whenLayerView(layer: __esri.Layer): Promise<__esri.LayerView> |
addLayer
addLayer(layer: __esri.Layer | Promise<any>, index?: number): Promise<void>
Adds a layer to the map layers collection.
Parameters
Parameter | Type | Optional? |
---|---|---|
layer | Layer | Promise<any> | |
index | number | undefined |
- Returns
- Promise<void>
addLayers
addLayers(layers: __esri.Layer[], index?: number): Promise<void>
Adds a layer or array of layers to the map layers collection.
Parameters
Parameter | Type | Optional? |
---|---|---|
layers | Array<Layer> | |
index | number | undefined |
- Returns
- Promise<void>
addTable
addTable(table: __esri.FeatureLayer): Promise<void>
Adds a table to the map tables collection.
Parameters
Parameter | Type | Optional? |
---|---|---|
table |
- Returns
- Promise<void>
addTables
addTables(tables: __esri.FeatureLayer[], index?: number): Promise<void>
Adds a table or array of tables to the map tables collection.
Parameters
Parameter | Type | Optional? |
---|---|---|
tables | Array<FeatureLayer> | |
index | number | undefined |
- Returns
- Promise<void>
componentOnReady
componentOnReady(): Promise<void>
Create a promise that resolves once component is fully loaded.
- Returns
- Promise<void>
destroy
destroy(): Promise<void>
Destroys the view, and any associated resources, including its map, popup, and UI elements.
- Returns
- Promise<void>
goTo
goTo(target: __esri.GoToTarget2D, options?: __esri.GoToOptions2D): Promise<unknown>
Sets the view to a given target.
Parameters
Parameter | Type | Optional? |
---|---|---|
target | any | |
options | GoToOptions2D | undefined |
- Returns
- Promise<unknown>
hitTest
hitTest(screenPoint: __esri.MapViewScreenPoint | MouseEvent, options?: __esri.MapViewHitTestOptions): Promise<__esri.HitTestResult>
Returns hit test results from each layer that intersects the specified screen coordinates.
Parameters
Parameter | Type | Optional? |
---|---|---|
screenPoint | MapViewScreenPoint | MouseEvent | |
options | MapViewHitTestOptions | undefined |
- Returns
- Promise<HitTestResult>
openPopup
openPopup(options?: __esri.PopupViewOpenPopupOptions): Promise<void>
Opens the popup at the given location with content defined either explicitly with content or driven from the PopupTemplate of input features.
Parameters
Parameter | Type | Optional? |
---|---|---|
options | PopupViewOpenPopupOptions | undefined |
- Returns
- Promise<void>
takeScreenshot
takeScreenshot(options?: __esri.MapViewTakeScreenshotOptions): Promise<__esri.Screenshot>
Create a screenshot of the current view.
Parameters
Parameter | Type | Optional? |
---|---|---|
options | MapViewTakeScreenshotOptions | undefined |
- Returns
- Promise<Screenshot>
toMap
toMap(screenPoint: __esri.MapViewScreenPoint | MouseEvent): __esri.Point
Parameters
Parameter | Type | Optional? |
---|---|---|
screenPoint | MapViewScreenPoint | MouseEvent |
- Returns
- Point
toScreen
toScreen(point: __esri.Point, options?: __esri.ToScreenOptions2D): __esri.MapViewScreenPoint | nullish
Parameters
Parameter | Type | Optional? |
---|---|---|
point | ||
options | ToScreenOptions2D | undefined |
- Returns
- MapViewScreenPoint | null | undefined
tryFatalErrorRecovery
tryFatalErrorRecovery(): Promise<void>
Call this method to clear any fatal errors resulting from a lost WebGL context.
- Returns
- Promise<void>
whenLayerView
whenLayerView(layer: __esri.Layer): Promise<__esri.LayerView>
Gets the LayerView created on the view for the given layer.
Parameters
Parameter | Type | Optional? |
---|---|---|
layer |
- Returns
- Promise<LayerView>
Events
Event | Type |
---|---|
void | |
ViewLayerviewCreateEvent | |
ViewLayerviewCreateErrorEvent | |
ViewLayerviewDestroyEvent | |
void |
arcgisViewChange
arcgisViewChange: void
This event is for view related property changes: zoom, scale, center, rotation, extent, camera, viewpoint. This event will also emit if stationary toggles from true to false.
arcgisViewClick
arcgisViewClick: ViewClickEvent
Fires after a user clicks on the view.
arcgisViewDoubleClick
arcgisViewDoubleClick: ViewDoubleClickEvent
Fires after double-clicking on the view.
arcgisViewDrag
arcgisViewDrag: ViewDragEvent
Fires during a pointer drag on the view.
arcgisViewHold
arcgisViewHold: ViewHoldEvent
Fires during a pointer drag on the view.
arcgisViewImmediateClick
arcgisViewImmediateClick: ViewImmediateClickEvent
Fires right after a user clicks on the view.
arcgisViewImmediateDoubleClick
arcgisViewImmediateDoubleClick: ViewImmediateDoubleClickEvent
Is emitted after two consecutive immediate-click events.
arcgisViewKeyDown
arcgisViewKeyDown: ViewKeyDownEvent
Fires after a keyboard key is pressed.
arcgisViewKeyUp
arcgisViewKeyUp: ViewKeyUpEvent
Fires after a keyboard key is pressed.
arcgisViewLayerviewCreate
arcgisViewLayerviewCreate: ViewLayerviewCreateEvent
Fires after each layer in the map has a corresponding LayerView created and rendered in the view.
arcgisViewLayerviewCreateError
arcgisViewLayerviewCreateError: ViewLayerviewCreateErrorEvent
Fires when an error emits during the creation of a LayerView after a layer has been added to the map.
arcgisViewLayerviewDestroy
arcgisViewLayerviewDestroy: ViewLayerviewDestroyEvent
Fires after a LayerView is destroyed and is no longer rendered in the view.
arcgisViewMouseWheel
arcgisViewMouseWheel: ViewMouseWheelEvent
Fires when a wheel button of a pointing device (typically a mouse) is scrolled on the view.
arcgisViewPointerDown
arcgisViewPointerDown: ViewPointerDownEvent
Fires after a mouse button is pressed, or a finger touches the display.
arcgisViewPointerEnter
arcgisViewPointerEnter: ViewPointerEnterEvent
Fires after a mouse cursor enters the view, or a display touch begins.
arcgisViewPointerLeave
arcgisViewPointerLeave: ViewPointerLeaveEvent
Fires after a mouse cursor leaves the view, or a display touch ends.
arcgisViewPointerMove
arcgisViewPointerMove: ViewPointerMoveEvent
Fires after the mouse or a finger on the display moves.
arcgisViewPointerUp
arcgisViewPointerUp: ViewPointerUpEvent
Fires after a mouse button is released, or a display touch ends.