Atlaslog
Atlaslog / deck.gl / API / Deck
deck.gl · API reference

Deck

Quick answer

Deck is a class that takes deck.gl layer instances and viewport parameters, renders those layers as a transparent overlay, and handles events.

Last verified 2026-11-03 · deck.gl 9.0 · Cite this page
Runnable examplesChinese noteAll API topics

Deck is a class that takes deck.gl layer instances and viewport parameters, renders those layers as a transparent overlay, and handles events.

If you are using React, you should not use this class directly. Instead you should be rendering the DeckGL React component.

Usage​

// Basic standalone use
import {Deck} from '@deck.gl/core';
import {ScatterplotLayer} from '@deck.gl/layers';

const deck = new Deck({
  initialViewState: {
    longitude: -122.45,
    latitude: 37.78,
    zoom: 12
  },
  controller: true,
  layers: [
    new ScatterplotLayer({data})
  ]
});

Constructor​

Creates a new Deck instance.

const deck = new Deck(props);

Parameters:

See the Properties section.

Properties​

Initialization Settings​

The following properties are used to initialize a Deck instance. Any custom value should always be provided to the Deck constructor. Changing them with setProps afterwards will have no effect.

canvas (HTMLCanvasElement | String, optional)​

The canvas to render into. It can be either a HTMLCanvasElement or the element id, and will be auto-created if not supplied.

_canvases ((HTMLCanvasElement | String)[], optional)​

Experimental: presentation canvases for multi-canvas mode. Deck renders into an offscreen default context and presents the result into one PresentationContext per canvas entry. String entries are resolved as DOM element ids. Views without an explicit canvasId render into the first configured canvas.

This is a separate experimental opt-in so the existing single-canvas canvas property's accepted values and behavior remain unchanged. Applications that do not provide _canvases continue to use the existing single-canvas rendering, event handling, and integration paths.

Unlike the other initialization settings in this section, _canvases is maintained when updated with setProps(). Deck diffs the array and creates, reuses, or destroys presentation targets as needed.

Notes:

Use deck.getCanvasContext(viewId) to access the presentation context assigned to a view. Canvas identifiers remain an internal presentation-target detail; Deck APIs that associate resources with a view accept its view id.

device (Device)​

luma.gl Device used to manage the application's connection with the GPU. Will be auto-created if not supplied.

When a Device is supplied, Deck does not destroy it when finalized. While the Deck instance is active, Deck owns the device.props.onResize callback for the active render canvas context; use DeckProps.onResize to observe Deck canvas resizes.

deviceProps (DeviceProps | WebGLDeviceProps)​

Options used for creating a new luma.gl GPU Device.

Note that when using WebGL, props.deviceProps.webgl can be used to specify WebGL context attributes.

gl (WebGLContext)​

WebGL context to use. This prop is deprecated and replaced by device.

id (string)​

ID assigned to the canvas that is created by this Deck instance, to allow style customization in CSS.

parent (HTMLElement)​

The container to append the auto-created canvas to.

debug (boolean)​

Flag to enable GPU debug mode when initializing a device. Also requires an extra luma.gl import:

import '@luma.gl/debug';
import {Deck} from '@deck.gl/core';

new Deck({
  // ...
  debug: true
})

Notes:

_typedArrayManagerProps (object)​

(Experimental) May contain the following fields:

The above default settings make data updates faster, at the price of using more memory. If the app does not anticipate frequent data changes, they may be aggressively reduced:

new Deck({
  // ...
  _typedArrayManagerProps: isMobile ? {overAlloc: 1, poolSize: 0} : null
})

Rendering Configuration​

width (number | string)​

Width of the canvas, a number in pixels or a valid CSS string.

height (number | string)​

Height of the canvas, a number in pixels or a valid CSS string.

style (object)​

Additional CSS styles for the canvas.

useDevicePixels (boolean | number)​

Controls the resolution of drawing buffer used for rendering.

Note:

parameters (object)​

Expects an object with GPU parameters. Before each frame is rendered, this object will be passed to luma.gl's RenderPass to reset the GPU context parameters, e.g. to disable depth testing, change blending modes etc. The default parameters set by Deck on initialization are the following:

{
  blend: true,
  blendColorSrcFactor: 'src-alpha',
  blendColorDstFactor: 'one-minus-src-alpha',  
  blendAlphaSrcFactor: 'one',
  blendAlphaDstFactor: 'one-minus-src-alpha'
  polygonOffsetFill: true,
  depthWriteEnabled: true,
  depthCompare: 'less-equal'
}

Refer to the luma.gl GPU parameters API for documentation on supported parameters and values.

new Deck({
  // ...
  parameters: {
    blendColorSrcFactor: 'one',
    blendColorDstFactor: 'one',
    blendAlphaSrcFactor: 'one',
    blendAlphaDstFactor: 'one'
    depthWriteEnabled: false
  }
});

Notes:

layers (LayersList)​

The array of Layer instances to be rendered.

Nested arrays are accepted, as well as falsy values (null, false, undefined). This allows applications to do something like:

new Deck({
  // ...
  layers: dataSource.map((item, index) => item && [
    new ScatterplotLayer({id: `scatterplot-${index}`, ...}),
    new PolygonLayer({id: `polygon-${index}`, ...})
  ])
});
// layers is in the shape of [[<layer>, <layer>], null, [<layer>, <layer>], ...]

layerFilter (Function)​

If supplied, will be called before a layer is drawn to determine whether it should be rendered. This gives the application an opportunity to filter out layers from the layer list during either rendering or picking. Filtering can be done per viewport or per layer or both. This enables techniques like adding helper layers that work as masks during picking but do not show up during rendering.

new Deck({
  // ...
  layerFilter: ({layer, viewport}) => {
    if (viewport.id !== 'minimap' && layer.id === 'geofence') {
      // only display geofence in the minimap
      return false;
    }
    return true;
  }
}

Receives arguments:

Returns:

true if the layer should be drawn.

Notes:

views (View | View[])​

A single View instance, or an array of View instances.

Views represent the "camera(s)" (essentially viewport dimensions and projection matrices) that you look at your data with. deck.gl offers multiple view types for both geospatial and non-geospatial use cases. Read the Views and Projections guide for the concept and examples.

viewState (object)​

An object that describes the view state for each view in the views prop. For example, the default view's view state is described here:

new Deck({
  // ...
  viewState: {
    longitude: -122.45,
    latitude: 37.78,
    zoom: 12,
    pitch: 30,
    bearing: 0
  }
})

When using multiple views, the viewState is a map from each view id to its respective view state object. See example.

Transitions between two viewState objects can also be achieved by providing set of fields to viewState prop, for more details check ViewState Transitions).

Notes:

initialViewState (object)​

If initialViewState is provided, the Deck component will track view state changes from any attached controller using internal state, with initialViewState as its initial view state. This is the easiest way to control the camera.

If the initialViewState prop changes, the internally tracked view state will be updated to match the new "initial" view state.

Notes:

effects (Effect[])​

The array of effects to be rendered. A lighting effect will be added if an empty array is supplied. Refer to effect's documentation to see details:

_framebuffer (object)​

(Experimental) Render to a custom frame buffer other than to screen.

_animate (boolean)​

(Experimental) Forces deck.gl to redraw layers every animation frame. Normally deck.gl layers are only redrawn if any change is detected.

Interaction Settings​

controller (Function | Boolean | Object)​

Options for viewport interactivity, e.g. pan, rotate and zoom with mouse, touch and keyboard. This is a shorthand for defining interaction with the views prop if you are using the default view (i.e. a single MapView).

new Deck({
  // ...
  views: [
    new MapView({
      controller: {touchRotate: true, doubleClickZoom: false}
    })
  ]
})

is equivalent to:

new Deck({
  // ...
  // views: undefined
  controller: {touchRotate: true, doubleClickZoom: false}
})

controller can be one of the following types:

getCursor (Function)​

A custom callback to retrieve the cursor type.

Receives arguments:

Returns:

A valid CSS cursor string.

Remarks:

getTooltip (Function)​

Callback that takes a hovered-over point and renders a tooltip. If the prop is not specified, the tooltip is always hidden.

Receives arguments:

Returns one of the following:

By default, the tooltip has the following CSS style:

z-index: 1;
position: absolute;
color: #a0a7b4;
background-color: #29323c;
padding: 10px;

pickingRadius (number)​

Extra pixels around the pointer to include while picking. This is helpful when rendered objects are difficult to target, for example irregularly shaped icons, small moving circles or interaction by touch. Default 0.

touchAction (string)​

Allow browser default touch actions. See hammer.js documentation.

By default, the deck canvas captures all touch interactions. This prop is useful for mobile applications to unblock default scrolling behavior. For example, use the combination controller: {dragPan: false} and touchAction: 'pan-y' to allow vertical page scroll when dragging over the canvas.

eventRecognizerOptions (object)​

Set options for gesture recognition. May contain the following fields:

For example, the following setting makes panning less sensitive and clicking easier on mobile:

new Deck({
  // ...
  eventRecognizerOptions: isMobile ? {
    pan: {threshold: 10},
    tap: {threshold: 5}
  } : {}
})

_pickable (boolean)​

(Experimental) If set to false, force disables all picking features, disregarding the pickable prop set in any layer.

Event Callbacks​

onDeviceInitialized (Function)​

Called once the Device context has been initiated.

Receives arguments:

onViewStateChange (Function)​

Called when the user has interacted with the deck.gl canvas, e.g. using mouse, touch or keyboard.

onViewStateChange({viewState, interactionState, oldViewState})

Receives arguments:

Returns:

A view state object that is used to update Deck's internally tracked view state (see initialViewState). This can be used to intercept and modify the view state before the camera updates, see add constraints to view state example.

If no value is returned, it's equivalent to (viewState) => viewState.

onInteractionStateChange (Function)​

Called when the user has interacted with the deck.gl canvas, e.g. using mouse, touch or keyboard.

onInteractionStateChange(interactionState)

Receives arguments:

Note:

onHover (Function)​

Called when the pointer moves over the canvas.

Receives arguments:

onClick (Function)​

Called when clicking on the canvas.

Receives arguments:

onDragStart (Function)​

Called when the user starts dragging on the canvas.

Receives arguments:

onDrag (Function)​

Called when dragging the canvas.

Receives arguments:

onDragEnd (Function)​

Called when the user releases from dragging the canvas.

Receives arguments:

onLoad (Function)​

Called once after gl context and Deck components (ViewManager, LayerManager, etc) are created. It is safe to trigger viewport transitions after this event.

onResize (Function)​

Called when the canvas resizes.

Receives arguments:

onBeforeRender (Function)​

Called just before the canvas rerenders.

Receives arguments:

onAfterRender (Function)​

Called right after the canvas rerenders.

Receives arguments:

onError (Function)​

Called if deck.gl encounters an error. By default, deck logs the error to console and attempt to continue rendering the rest of the scene. If this callback is set to null, errors are silently ignored.

Receives arguments:

_onMetrics (Function)​

(Experimental) Called once every second with performance metrics.

Receives arguments:

Methods​

finalize​

Frees all resources associated with this Deck instance.

deck.finalize()

getCanvas​

Get the canvas element attached to this Deck instance.

deck.getCanvas()

Returns:

Notes:

getCanvasContext​

Get the canvas context associated with a view, or the default Deck canvas when no view id is supplied.

deck.getCanvasContext(viewId)

Parameters:

Returns:

In multi-canvas mode, the context is resolved from the view's canvasId. This lets view-bound components use a view id without depending on presentation-target identifiers.

getViews​

Get all views currently rendered by this Deck instance.

deck.getViews()

Returns:

getView​

Get a specific view by id.

deck.getView(viewId)

Parameters:

Returns:

getViewports​

Get all viewports currently rendered by this Deck instance.

deck.getViewports(rect)

Parameters:

Returns:

setProps​

Updates (partial) properties.

deck.setProps({...});

Parameters:

redraw​

Attempt to draw immediately, rather than waiting for the next draw cycle. By default, deck flushes all changes to the canvas on each animation frame. This behavior might cause the deck canvas to fall out of sync with other components if synchronous updates are required.

Redrawing frequently outside of rAF may cause performance problems. Only use this method if the render cycle must be managed manually.

deck.redraw(true);

Parameters:

pickObjectAsync​

Get the closest pickable and visible object at the given screen coordinate.

await deck.pickObjectAsync({x, y, canvasId, radius, layerIds, unproject3D})

Parameters:

Returns:

pickObjectsAsync​

Get all pickable and visible objects within a bounding box.

await deck.pickObjectsAsync({x, y, width, height, canvasId, layerIds, maxObjects})

Parameters:

Returns:

Notes:

pickObject​

Get the closest pickable and visible object at the given screen coordinate.

deck.pickObject({x, y, canvasId, radius, layerIds, unproject3D})

Parameters:

Returns:

pickMultipleObjects​

Performs deep picking. Finds all close pickable and visible object at the given screen coordinate, even if those objects are occluded by other objects.

deck.pickMultipleObjects({x, y, canvasId, radius, layerIds, depth, unproject3D})

Parameters:

Returns:

Notes:

pickObjects​

Get all pickable and visible objects within a bounding box.

deck.pickObjects({x, y, width, height, canvasId, layerIds, maxObjects})

Parameters:

Returns:

Notes:

Member Variables​

isInitialized​

Flag indicating that the Deck instance has initialized its resources. It is safe to call public methods when isInitialized is true.

metrics​

A map of various performance statistics for the last 60 frames of rendering. Metrics gathered in deck.gl are the following:

Note that gpuTime and gpuTimePerFrame metrics are disabled by default for performance reasons. To enable the readings, set deviceProps.debugGPUTime: true in Deck's constructor:

new Deck({
  deviceProps: {debugGPUTime: true}
})

Source​

modules/core/src/lib/deck.ts

Edit this page
TutorialsAPI index
English reference text adapted from the official deck.gl documentation, © vis.gl contributors, licensed under MIT.
Original page: https://deck.gl/docs/api-reference/core/deck · Chinese note: /deckgl/api/deck.html
Cite this page

Atlaslog (2026). Deck. https://www.jingweizhi.com/en/deckgl/api/deck.html (accessed 2026-11-03).