MaplibreX.Components.DeckGlLayer (MaplibreX v0.1.0)

Copy Markdown View Source

Renders a deck.gl layer on top of a MapLibre map.

deck.gl is a WebGL visualisation library for large datasets. This component wires deck.gl layers into MapLibre GL JS from Phoenix LiveView.

The deck.gl packages are lazy-loaded the first time a layer mounts, so applications that never use this component pay nothing for it. They are optional peer dependencies — see the installation guide in the README.

Requires maplibre-gl v5

@deck.gl/mapbox reads MapLibre's internal map.transform, which maplibre-gl v6 removed, and every published version still does. Under v6 this component raises with a message naming the constraint. The rest of MaplibreX works on both v5 and v6.

Attributes

  • id (required) - Unique layer identifier
  • map_id (required) - Id of the map to render into
  • layer_type (required) - deck.gl layer type, e.g. "ScatterplotLayer", "ArcLayer"
  • data (required) - List of records to visualise
  • props - Layer-specific properties (default: %{})
  • before_id - Insert the layer before this layer id (default: nil)
  • opacity - Layer opacity, 0-1 (default: 1.0)
  • visible - Layer visibility (default: true)
  • pickable - Whether the layer responds to pointer events (default: false)
  • auto_highlight - Highlight objects on hover (default: false)
  • update_triggers - deck.gl update triggers (default: %{})

Supported layer types

Basic layers

  • ScatterplotLayer - Points with a variable radius
  • ArcLayer - Arcs between point pairs
  • LineLayer - Lines and routes
  • PolygonLayer - 2D polygons
  • PathLayer - Paths
  • ColumnLayer - 3D columns
  • TextLayer - Text labels
  • IconLayer - Icons

Aggregation layers

  • HexagonLayer - Aggregated hexagonal bins
  • GridLayer - Grid cells
  • ScreenGridLayer - Grid in screen coordinates
  • HeatmapLayer - Heatmap
  • ContourLayer - Contour lines

Advanced layers

  • GeoJsonLayer - GeoJSON rendering

Events

This component emits:

  • deckgl:layer_loaded - Layer loaded successfully
  • deckgl:click - An object in the layer was clicked
  • deckgl:hover - The pointer entered an object
  • deckgl:drag_start - Drag started on an object
  • deckgl:drag - Object is being dragged
  • deckgl:drag_end - Drag finished
  • deckgl:error - The layer failed to process

Examples

A basic ScatterplotLayer:

<.deckgl_layer
  id="points"
  map_id="my-map"
  layer_type="ScatterplotLayer"
  data={@points}
  pickable={true}
  props={%{
    "getPosition" => "coordinates",
    "getRadius" => 1000,
    "getFillColor" => [255, 140, 0],
    "radiusMinPixels" => 2
  }}
/>

An ArcLayer visualising connections:

<.deckgl_layer
  id="arcs"
  map_id="my-map"
  layer_type="ArcLayer"
  data={@flights}
  pickable={true}
  auto_highlight={true}
  props={%{
    "getSourcePosition" => "from",
    "getTargetPosition" => "to",
    "getSourceColor" => [255, 140, 0],
    "getTargetColor" => [255, 200, 0],
    "getWidth" => 2
  }}
/>

A HexagonLayer showing density:

<.deckgl_layer
  id="hexagons"
  map_id="my-map"
  layer_type="HexagonLayer"
  data={@events}
  props={%{
    "getPosition" => "location",
    "elevationScale" => 4,
    "radius" => 200,
    "extruded" => true,
    "coverage" => 0.9
  }}
/>

Handling events

def handle_event("deckgl:click", %{"object" => object, "coordinate" => coord}, socket) do
  # `object` holds the clicked feature's data, `coord` is [lng, lat]
  {:noreply, socket}
end

def handle_event("deckgl:hover", %{"object" => object}, socket) do
  {:noreply, assign(socket, :hovered_object, object)}
end

Accessors

Accessors accept several forms:

# A string naming a property
"getPosition" => "coordinates"       # d => d.coordinates

# A MapLibre-style expression
"getPosition" => ["get", "coords"]   # d => d.coords

# A constant value
"getFillColor" => [255, 0, 0]        # always red

Performance

For large datasets (>100k points):

  • Prefer HexagonLayer or GridLayer over ScatterplotLayer
  • Set update_triggers so deck.gl only recomputes what changed
  • Filter data server-side before sending it to the client
  • Reach for aggregation layers wherever they fit

References

Summary

Functions

deckgl_layer(assigns)

Renders a deck.gl layer.

Functions

deckgl_layer(assigns)

Renders a deck.gl layer.

Example

<.deckgl_layer
  id="my-layer"
  map_id="map"
  layer_type="ScatterplotLayer"
  data={@points}
  props={%{"getPosition" => "coords"}}
/>

Attributes

  • id (:string) (required) - Unique layer identifier.
  • map_id (:string) (required) - Id of the map to render into.
  • layer_type (:string) (required) - deck.gl layer type.
  • data (:list) (required) - Records to visualise.
  • props (:map) - Layer-specific properties. Defaults to %{}.
  • before_id (:string) - Insert before this layer id. Defaults to nil.
  • opacity (:float) - Opacity, 0-1. Defaults to 1.0.
  • visible (:boolean) - Layer visibility. Defaults to true.
  • pickable (:boolean) - Whether the layer responds to pointer events. Defaults to false.
  • auto_highlight (:boolean) - Highlight objects on hover. Defaults to false.
  • update_triggers (:map) - deck.gl update triggers. Defaults to %{}.