Scene

1
import "@arcgis/map-components/components/arcgis-scene";

ArcGIS Scene component is used to add 3D maps to web applications. For 2D maps, use the ArcGIS Map component.

The Scene component creates a SceneView and loads a WebScene item from either ArcGIS Online or ArcGIS Enterprise portal.

1
<arcgis-scene item-id="e2da7564e4f24eaaa918ffd70378056a"></arcgis-scene>

Alternatively, the Scene component can be initialized without a WebScene item:

1
2
3
4
5
6
7
<arcgis-scene
 basemap="satellite"
 ground="world-elevation"
 camera-position="12.3808, 46.3959, 4400"
 camera-tilt="75"
 camera-heading="300">
</arcgis-scene>

Further components can be added and connected to the Scene component:

1
2
3
<arcgis-scene item-id="e2da7564e4f24eaaa918ffd70378056a">
  <arcgis-layer-list position="bottom-right"></arcgis-layer-list>
</arcgis-scene>

The Scene component can be customized further using any of the core API functionalities of the ArcGIS Maps SDK for JavaScript.

1
2
3
4
5
const arcgisScene = document.querySelector("arcgis-scene");
arcgisScene.addEventListener("arcgisViewReadyChange", () => {
  const layer = new GraphicsLayer({ title: "My layer"});
  arcgisScene.map.add(layer);
});

See also:

Demo

Properties

PropertyAttributeType
alpha-compositing-enabled
boolean
auto-destroy-disabled
boolean
basemap
Basemap | string
camera-fov
number
camera-heading
number
camera-position
Array<number> | Point | string
camera-tilt
number
center
Array<number> | Point | string
SceneViewConstraints
display-filter-disabled
boolean
SceneViewEnvironment
Collection<string>
gamepad
readonly
ground
Ground | string
groundView
readonly
interacting
readonly
boolean
item-id
string
layerViews
readonly
magnifier
readonly
navigating
readonly
boolean
ViewPadding
popup-disabled
boolean
quality-profile
"high" | "low" | "medium"
ready
readonly
boolean
resolution
readonly
number
scale
number
stationary
readonly
boolean
suspended
readonly
suspended
boolean
updating
readonly
updating
boolean
view
readonly
viewing-mode
"global" | "local"
zoom
number

allLayerViews

readonlyProperty
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.

alphaCompositingEnabled

Property
alphaCompositingEnabled: boolean

Allows the view to be partially or fully transparent when composited with the webpage elements behind it.

Read more...

Attribute
alpha-compositing-enabled
Default value
false

analyses

Property

Allows for adding analyses directly to the default analyses in the View.

Read more...

autoDestroyDisabled

Property
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

basemap

Property
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.

Read more

Attribute
basemap

basemapView

Property
basemapView: BasemapView

Represents the view for a single basemap after it has been added to the map.

camera

Property
camera: Camera

The camera allows to set the observation point from which the visible portion (or perspective) of the view is determined. When set in the constructor, this property overrides the center, extent, scale, viewpoint, and zoom properties.

Setting the camera immediately changes the current view. For animating the view, see this component's goTo() method.

cameraFov

Property
cameraFov: number

The diagonal field of view (fov) angle for the camera. The range of angles must be between 1 and 170 degrees.

Setting the camera fov immediately changes the current view. For animating the view, see this component's goTo() method.

Read more

Attribute
camera-fov

cameraHeading

Property
cameraHeading: number

The compass heading of the camera in degrees.

Setting the camera heading immediately changes the current view. For animating the view, see this component's goTo() method.

Read more

Attribute
camera-heading

cameraPosition

Property
cameraPosition: Array<number> | Point | string

The position of the camera defined by a map point. It can be a string with the format "<longitude>, <latitude>, <elevation>" or a Point instance.

Setting the camera position immediately changes the current view. For animating the view, see this component's goTo() method.

Read more

Attribute
camera-position

cameraTilt

Property
cameraTilt: number

The tilt of the camera in degrees with respect to the surface as projected down from the camera position.

Setting the camera tilt immediately changes the current view. For animating the view, see this component's goTo() method.

Read more

Attribute
camera-tilt

center

Property
center: Array<number> | Point | string

Represents the center point of the view. It can be a string with the format "<longitude>, <latitude>" or a Point instance.

Setting the center immediately changes the current view. For animating the view, see this component's goTo() method.

Read more

Attribute
center

clippingArea

Property
clippingArea: Extent

Represents an optional clipping area used to define the visible extent of a local scene.

Read more

constraints

Property
constraints: SceneViewConstraints

Specifies constraints for the camera's tilt, altitude, and view's clip distance.

Read more

displayFilterDisabled

Property
displayFilterDisabled: boolean

Indicates whether a layer's displayFilter is honored when rendering layers in the view. If false, the display filters are ignored and all features are rendered.

Attribute
display-filter-disabled
Default value
false

environment

Property
environment: SceneViewEnvironment

Specifies various properties of the environment's visualization in the view, like the lighting, background, weather, etc.

Read more

extent

Property
extent: Extent

The extent represents the visible portion of a map within the view as an instance of 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.

Read more

fatalError

Property
fatalError: Error

A rejected view indicates a fatal error making it unable to display.

Read more

floors

Property
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.

gamepad

readonlyProperty

Gamepad input specific configuration settings.

graphics

Property
graphics: Collection<Graphic>

Allows for adding graphics directly to the default graphics in the view. Examples:

1
2
3
4
// Adds a graphic to the View
graphics.add(pointGraphic);
// Removes a graphic from the View
graphics.remove(pointGraphic);

ground

Property
ground: Ground | string

Specifies the surface properties for the map. It can be either a Ground instance or a string with one of the following values:

  • "world-elevation"
  • "world-topobathymetry"

Read more

Attribute
ground

groundView

readonlyProperty
groundView: GroundView

The view for the ground of the map.

Read more...

highlightOptions

deprecatedProperty
highlightOptions: HighlightOptions

As of 4.32, use highlights property instead.

Options for configuring the highlight.

Read more...

highlights

Property

Represents a collection of HighlightOptions objects which can be used to highlight features throughout an application.

Read more...

interacting

readonlyProperty
interacting: boolean

Indication whether the view is being interacted with (for example when panning or by an interactive tool).

Default value
false

itemId

Property
itemId: string

The ID of a WebScene item from either ArcGIS Online or ArcGIS Enterprise portal.

To configure the portal url you must set the config.portalUrl property before the Scene component loads.

Attribute
item-id

layerViews

readonlyProperty
layerViews: Collection<LayerView>

A collection containing a hierarchical list of all the created LayerViews of the operational layers in the map.

magnifier

readonlyProperty
magnifier: Magnifier

The magnifier allows for showing a portion of the view as a magnifier image on top of the view.

map

Property
map: Map

An instance of a Map object to display in the view.

readonlyProperty
navigating: boolean

Indication whether the view is being navigated (for example when panning).

Default value
false
Property
navigation: Navigation

Options to configure the navigation behavior of the view.

Read more

padding

Property
padding: ViewPadding

Use the padding property to make the center, and extent, etc. work off a subsection of the full view.

Read more

Default value
{left: 0, top: 0, right: 0, bottom: 0}

performanceInfo

readonlyProperty
performanceInfo: SceneViewPerformanceInfo

This property contains performance information of the view, e.g. global memory usage and additional details for layers about memory consumption and number of features.

Property
popup: Popup

A Popup object that displays general content or attributes from layers in the map.

Read more...

popupDisabled

Property
popupDisabled: boolean

Controls whether the popup opens when users click on the view.

Attribute
popup-disabled
Default value
false

qualityProfile

Property
qualityProfile: "high" | "low" | "medium"

SceneView can draw scenes in three different quality modes: high, medium and low.

Read more...

Attribute
quality-profile

ready

readonlyProperty
ready: boolean

When true, this property indicates whether the view successfully satisfied all dependencies, signaling that the necessary conditions are met.

Read more

Default value
false

resolution

readonlyProperty
resolution: number

Represents the current value of one pixel in the unit of the view's spatialReference. The resolution is calculated by dividing the view's extent width by its width.

scale

Property
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.

Read more

Attribute
scale

spatialReference

Property
spatialReference: SpatialReference

The spatial reference of the view. This indicates the projected or geographic coordinate system used to locate geographic features in the map.

Read more

Default value
null

stationary

readonlyProperty
stationary: boolean

Indication whether the view is animating, being navigated with or resizing.

Default value
false

suspended

readonly
Property
suspended: boolean

Indicates if the view is visible on the page.

Read more

Attribute
suspended
Default value
true

theme

Property
theme: Theme

This property specifies the base colors used by some widgets and components to render graphics and labels. This only affects those elements that would otherwise use the default orange pattern.

Default value
null

timeExtent

Property
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

updating

readonly
Property
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

view

readonlyProperty
view: SceneView

Internal SceneView of the component. Once the Scene component is loaded, it can be accessed as follows:

1
2
3
4
const arcgisScene = document.querySelector("arcgis-scene");
arcgisScene.addEventListener("arcgisViewReadyChange", () => {
  const view = arcgisScene.view;
});

viewingMode

Property
viewingMode: "global" | "local"

The viewing mode sets whether the view renders the earth as a sphere (global mode) or on a flat plane (local mode).

Note that the viewing mode must be set before the Scene component loads. Depending on the viewing mode different supported coordinate systems are available.

Read more

Attribute
viewing-mode
Default value
"global"

viewpoint

Property
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.

Read more

zoom

Property
zoom: number

Represents the level of detail (LOD) at the center of the view.

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.

Read more

Attribute
zoom

Methods

MethodSignature
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.GoToTarget3D, options?: __esri.GoToOptions3D): Promise<unknown>
hitTest(screenPoint: __esri.SceneViewScreenPoint | MouseEvent, options?: __esri.SceneViewHitTestOptions): Promise<__esri.SceneViewHitTestResult>
openPopup(options?: __esri.PopupViewOpenPopupOptions): Promise<void>
takeScreenshot(options?: __esri.SceneViewTakeScreenshotOptions): Promise<__esri.SceneViewScreenshot>
toMap(screenPoint: __esri.SceneViewScreenPoint | MouseEvent, options?: __esri.SceneViewToMapOptions): __esri.Point | nullish
toScreen(point: __esri.Point): __esri.SceneViewScreenPoint
tryFatalErrorRecovery(): Promise<void>
whenAnalysisView(analysis: __esri.AreaMeasurementAnalysis | __esri.DimensionAnalysis | __esri.DirectLineMeasurementAnalysis | __esri.LineOfSightAnalysis | __esri.SliceAnalysis | __esri.ViewshedAnalysis): Promise<__esri.AreaMeasurementAnalysisView3D | __esri.DimensionAnalysisView | __esri.DirectLineMeasurementAnalysisView3D | __esri.LineOfSightAnalysisView3D | __esri.SliceAnalysisView3D | __esri.ViewshedAnalysisView3D>
whenLayerView(layer: __esri.Layer): Promise<__esri.LayerView>

addLayer

Method
addLayer(layer: __esri.Layer | Promise<any>, index?: number): Promise<void>

Adds a layer to the map's layers collection.

Parameters
ParameterTypeOptional?
layer
Layer | Promise<any>
index
number | undefined
Returns
Promise<void>

addLayers

Method
addLayers(layers: __esri.Layer[], index?: number): Promise<void>

Adds a layer or array of layers to the map's layers collection.

Parameters
ParameterTypeOptional?
layers
Array<Layer>
index
number | undefined
Returns
Promise<void>

addTable

Method
addTable(table: __esri.FeatureLayer): Promise<void>

Adds a table to the map's tables collection.

Parameters
ParameterTypeOptional?
table
Returns
Promise<void>

addTables

Method
addTables(tables: __esri.FeatureLayer[], index?: number): Promise<void>

Adds a table or array of tables to the map's tables collection.

Parameters
ParameterTypeOptional?
tables
index
number | undefined
Returns
Promise<void>

closePopup

Method
closePopup(): Promise<void>

Closes the popup.

Returns
Promise<void>

componentOnReady

Method
componentOnReady(): Promise<void>

Create a promise that resolves once component is fully loaded.

Returns
Promise<void>

destroy

Method
destroy(): Promise<void>

Destroys the Scene component, and any associated resources, including its map, popup, and removes components or other UI DOM elements added to it.

Returns
Promise<void>

goTo

Method
goTo(target: __esri.GoToTarget3D, options?: __esri.GoToOptions3D): Promise<unknown>

Sets the view to a given target.

Read more

Parameters
ParameterTypeOptional?
target
any
options
GoToOptions3D | undefined
Returns
Promise<unknown>

hitTest

Method
hitTest(screenPoint: __esri.SceneViewScreenPoint | MouseEvent, options?: __esri.SceneViewHitTestOptions): Promise<__esri.SceneViewHitTestResult>

Returns hit test results from each layer that intersects the specified screen coordinates.

1
2
3
4
5
6
7
8
9
10
11
arcgisScene.addEventListener("arcgisViewClick", (event) => {
  arcgisScene.hitTest(event.detail).then((response) => {
     const result = response.results[0];
     if (result?.type === "graphic") {
        const { longitude, latitude } = result.mapPoint;
        console.log("Hit graphic at (" + longitude + ", " + latitude + ")", result.graphic);
     } else {
        console.log("Did not hit any graphic");
     }
  });
});

Read more

Parameters
ParameterTypeOptional?
screenPoint
options
SceneViewHitTestOptions | undefined
Returns
Promise<SceneViewHitTestResult>

openPopup

Method
openPopup(options?: __esri.PopupViewOpenPopupOptions): Promise<void>

Opens the popup based on input options.

Read more

Parameters
ParameterTypeOptional?
options
PopupViewOpenPopupOptions | undefined
Returns
Promise<void>

takeScreenshot

Method
takeScreenshot(options?: __esri.SceneViewTakeScreenshotOptions): Promise<__esri.SceneViewScreenshot>

Creates a screenshot of the current view.

Read more

Parameters
ParameterTypeOptional?
options
SceneViewTakeScreenshotOptions | undefined
Returns
Promise<SceneViewScreenshot>

toMap

Method
toMap(screenPoint: __esri.SceneViewScreenPoint | MouseEvent, options?: __esri.SceneViewToMapOptions): __esri.Point | nullish

Converts the given screen point to a map point.

Parameters
ParameterTypeOptional?
screenPoint
options
SceneViewToMapOptions | undefined
Returns
Point | null | undefined

toScreen

Method
toScreen(point: __esri.Point): __esri.SceneViewScreenPoint

Converts the given map point to a screen point.

Parameters
ParameterTypeOptional?
point
Returns
SceneViewScreenPoint

tryFatalErrorRecovery

Method
tryFatalErrorRecovery(): Promise<void>

Call this method to clear any fatal errors resulting from a lost WebGL context.

Returns
Promise<void>

whenAnalysisView

Method
whenAnalysisView(analysis: __esri.AreaMeasurementAnalysis | __esri.DimensionAnalysis | __esri.DirectLineMeasurementAnalysis | __esri.LineOfSightAnalysis | __esri.SliceAnalysis | __esri.ViewshedAnalysis): Promise<__esri.AreaMeasurementAnalysisView3D | __esri.DimensionAnalysisView | __esri.DirectLineMeasurementAnalysisView3D | __esri.LineOfSightAnalysisView3D | __esri.SliceAnalysisView3D | __esri.ViewshedAnalysisView3D>

Gets the analysis view created for the given analysis object.

Read more

Parameters
Returns
Promise<AreaMeasurementAnalysisView3D | DimensionAnalysisView | DirectLineMeasurementAnalysisView3D | LineOfSightAnalysisView3D | SliceAnalysisView3D | ViewshedAnalysisView3D>

whenLayerView

Method
whenLayerView(layer: __esri.Layer): Promise<__esri.LayerView>

Gets the layer view created on the view for the given layer.

Read more

Parameters
ParameterTypeOptional?
layer
Returns
Promise<LayerView>

Events

arcgisViewChange

Event
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

Event
arcgisViewClick: ViewClickEvent

Fires after a user clicks on the view.

1
2
3
4
5
6
arcgisScene.addEventListener("arcgisViewClick", (event) => {
  arcgisScene.hitTest(event.detail).then((response) => {
     const result = response.results[0];
     // ....
  });
});

Read more

arcgisViewDoubleClick

Event
arcgisViewDoubleClick: ViewDoubleClickEvent

Fires after double-clicking on the view.

Read more

arcgisViewDrag

Event
arcgisViewDrag: ViewDragEvent

Fires during a pointer drag on the view.

Read more

arcgisViewHold

Event
arcgisViewHold: ViewHoldEvent

Fires after holding either a mouse button or a single finger on the view for a short amount of time.

Read more

arcgisViewImmediateClick

Event
arcgisViewImmediateClick: ViewImmediateClickEvent

Fires right after a user clicks on the view.

Read more

arcgisViewImmediateDoubleClick

Event
arcgisViewImmediateDoubleClick: ViewImmediateDoubleClickEvent

Is emitted after two consecutive immediate-click events.

Read more

arcgisViewKeyDown

Event
arcgisViewKeyDown: ViewKeyDownEvent

Fires after a keyboard key is pressed.

Read more

arcgisViewKeyUp

Event
arcgisViewKeyUp: ViewKeyUpEvent

Fires after a keyboard key is released.

Read more

arcgisViewLayerviewCreate

Event
arcgisViewLayerviewCreate: ViewLayerviewCreateEvent

Fires after each layer in the map has a corresponding LayerView created and rendered in the view.

Read more

arcgisViewLayerviewCreateError

Event
arcgisViewLayerviewCreateError: ViewLayerviewCreateErrorEvent

Fires when an error emits during the creation of a LayerView after a layer has been added to the map.

Read more

arcgisViewLayerviewDestroy

Event
arcgisViewLayerviewDestroy: ViewLayerviewDestroyEvent

Fires after a LayerView is destroyed and is no longer rendered in the view.

Read more

arcgisViewMouseWheel

Event
arcgisViewMouseWheel: ViewMouseWheelEvent

Fires when a wheel button of a pointing device (typically a mouse) is scrolled on the view.

Read more

arcgisViewPointerDown

Event
arcgisViewPointerDown: ViewPointerDownEvent

Fires after a mouse button is pressed, or a finger touches the display.

Read more

arcgisViewPointerEnter

Event
arcgisViewPointerEnter: ViewPointerEnterEvent

Fires after a mouse cursor enters the view, or a display touch begins.

Read more

arcgisViewPointerLeave

Event
arcgisViewPointerLeave: ViewPointerLeaveEvent

Fires after a mouse cursor leaves the view, or a display touch ends.

Read more

arcgisViewPointerMove

Event
arcgisViewPointerMove: ViewPointerMoveEvent

Fires after the mouse or a finger on the display moves.

Read more

arcgisViewPointerUp

Event
arcgisViewPointerUp: ViewPointerUpEvent

Fires after a mouse button is released, or a display touch ends.

Read more

arcgisViewReadyChange

Event
arcgisViewReadyChange: void

This event is for the ready property and will be emitted when the view is ready. This event will also emit if the map property is changed.

1
2
3
4
arcgisScene.addEventListener("arcgisViewReadyChange", () => {
   const layer = new GraphicsLayer({ title: "My layer"});
   arcgisScene.map.add(layer);
});

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.

You can no longer sign into this site. Go to your ArcGIS portal or the ArcGIS Location Platform dashboard to perform management tasks.

Your ArcGIS portal

Create, manage, and access API keys and OAuth 2.0 developer credentials, hosted layers, and data services.

Your ArcGIS Location Platform dashboard

Manage billing, monitor service usage, and access additional resources.

Learn more about these changes in the What's new in Esri Developers June 2024 blog post.

Close