Start Scripting with deck.gl

deck.gl is designed to make WebGL-based visualization simple. It powers many web applications at Uber that visualize large data sets with high performance.

Check out our gallery of examples

Up until now, most of the deck.gl examples were dependent on React. React is a great framework for making complex web applications, but an overkill for prototyping. There are times we just want to quickly check the shape of some data, play with ideas, and share the result without having to deal with npm dependencies, a JavaScript compiler, bundler or a dev server.

As we release deck.gl v5.2.0, we are also adding a standalone bundled version of the library. It offers a native JavaScript scripting interface like that of d3.js. You can now use deck.gl in prototype environments such as Codepen, JSFiddle and Observable. We hope that this effort makes it easier for designers, creative coders and data scientists everywhere to leverage WebGL for interactive visualizations.

My First deck.gl App

A webpage may now include a single-file version of deck.gl using the script tag: https://unpkg.com/deck.gl@~5.2.0/deckgl.min.js. This adds an object deck to the global scope.

Copy the following code into a text editor, save as index.html, and double click to open in a browser:

Try this example on Codepen | Observable notebook

In the following sections I will walk through the basic usage of the deck.gl scripting API.

DeckGL Scripting API

To start visualizing data with WebGL, you need to initialize a DeckGL instance:

const deckgl = new deck.DeckGL(props);

You can find the full documentation of the DeckGL class here. The scripting API extends the core Deck class with some additional features such as Mapbox integration.

As a start, you may want to tweak these props to your own scenario:

• container
  The container in which deck.gl should append its canvas. Can be either a HTMLDivElement or the element id. Default to document.body. The deck.gl canvas is resized to fill the container.
• longitude
  latitude
  zoom
  pitch
  bearing
  The initial view states of a geospatial visualization.
• controller
  By default, the Deck canvas is fully interactive — you can zoom, rotate and pan around. Set controller to false to disable interaction.
• map
  mapStyle
  mapboxApiAccessToken
  The scripting API offers out-of-the-box integration with Mapbox. To add a base map to your visualization, you need to include the Mapbox library and stylesheet. To disable the base map, simply exclude the mapbox script or set map to false.
  Specify your map style and access token as props when initiating the Deck object. See Mapbox GL JS documentation for how to use Mapbox.

Layers

Layers are pre-packaged WebGL visualizers for your data. You can quickly get impressive visual results through composition of multiple layers. Leveraging the GPU, deck.gl is able to render millions of data points in the browser smoothly. Suppose we have an array of objects {coordinates, count, address} describing geolocations where users checkin to a service. Here is a layer that renders a scatterplot from the data, each circle sized to reflect the prominence of the location:

Here is an example of updating a layer based on user-provided parameters:

Play with this example on Codepen | Observable

The best way to explore the extensive deck.gl layer collection is the interactive documentation in our layer catalog.

Interactions

deck.gl makes it easy to interact with objects rendered in the 3d scene. To make a layer interactive, turn on the pickable prop:

Aside from per-layer interaction, you may also listen to user events on the entire DeckGL canvas. Some useful DeckGL callback props are:

• onLayerClick
  called when any layer is clicked
• onLayerHover
  called when any layer is hovered
• onViewportChange
  called when the viewport is manipulated

An example of showing tooltips on hover:

Play with this example on Codepen | Observable

Not A Maps Person?

No problem, we got you covered.

By default, Deck layers use the LNGLAT coordinate system and renders into a single MapView.

If you explicitly set the views prop of your DeckGL instance, you can easily work with non-geospatial data. For example, the OrbitView is great for interactive 3d visualizations. The OrthographicView is usually used for 2d visualizations looking from top down.

Play with this example on Codepen | Observable

Our codepen showcase and observable profile has all sorts of examples to get you started. Welcome to deck.gl!