Skip to main content
WebGPUpartial

GraphLayer

From v9.0

GraphLayer is a composite Deck.gl layer that renders graph nodes, edges, and optional decorators using the declarative graph stylesheet. It orchestrates the GraphEngine with layout, styling, and interaction state so that graph applications can focus on supplying data and high-level behavior.

Usage​

import {GraphLayer, D3ForceLayout} from '@deck.gl-community/graph-layers';

const layer = new GraphLayer({
  id: 'graph',
  data: graphJson,
  layout: new D3ForceLayout(),
  stylesheet: {
    nodes: [
      {type: 'circle', radius: {attribute: 'degree', fallback: 6}},
      {type: 'label', text: '@id', color: '#172B4D', offset: [0, 16]}
    ],
    edges: {
      stroke: {attribute: 'isCritical', fallback: false, scale: value => (value ? '#F97316' : '#CBD5F5')},
      strokeWidth: {default: 1, hover: 3},
      decorators: [{type: 'arrow', size: 8}]
    }
  },
  enableDragging: true
});

GraphLayer treats the data prop as its single entry point. Provide a GraphEngine, a Graph, or raw graph payloads (arrays of edges or {nodes, edges} objects). When the layer receives new data it rebuilds the internal GraphEngine, re-runs the layout, and updates interactions automatically. Supplying raw data requires a layout so the layer can derive positions for you.

Load a graph URL with loaders.gl​

import {DOTLoaderWithParser} from '@loaders.gl/graphs/dot-loader';

const layer = new GraphLayer({
  id: 'karate-club',
  data: 'https://raw.githubusercontent.com/visgl/deck.gl-community/master/modules/graph-layers/test/data/__fixtures__/dot/karate.dot',
  loaders: [DOTLoaderWithParser],
  layout: new D3ForceLayout()
});

Deck.gl fetches data and parses it with loaders. The default graph conversion accepts the DOT loader's normalized graph data; no graphLoader callback or application-created GraphEngine is needed. JSON URLs with {nodes, edges} data use deck.gl's default JSON loading. Already loaded graphs can be supplied as data: graph with the same layout prop.

The community playground includes Graph from a DOT URL. Its JSON uses "loaders": ["@@#DOTLoader"] and "layout": {"@@function": "D3ForceLayout"}. The example registry supplies the published DOT loader constant and creates a fresh layout for each resolved configuration.

Properties​

GraphLayer inherits all standard Deck.gl layer props and adds the graph-specific options below.

Data sources​

data (async, optional)​

Unified graph input. Accepts:

  • A GraphEngine instance to reuse an existing engine.
  • A Graph instance to have the layer build its own engine.
  • Raw graph payloads—either arrays of edges or {nodes, edges} objects. Strings and promises are resolved via Deck.gl's async prop system.

Provide layout whenever you hand off raw data or a Graph, otherwise the layer cannot position nodes. Set data to null to skip rendering.

graph (Graph, optional, deprecated)​

Legacy entry point for supplying a graph. Prefer the data prop instead. When used, the layer still requires a layout to build the internal engine. Future releases will remove this prop.

graphLoader (function, optional)​

Custom loader that converts raw data into a Graph. The default converter accepts arrays of edges or {nodes, edges} collections and synthesizes missing endpoint nodes for raw JSON. Raw records use id, sourceId, and targetId; missing edge IDs are generated. Custom properties at the top level and in attributes are preserved, with nested attributes taking precedence for custom properties. Graph instances and normalized PlainGraphData/ArrowGraphData bypass graphLoader and are passed directly to the graph factory. Custom loaders only receive raw inputs.

engine (GraphEngine, optional)​

Inject an existing engine to reuse layout state across renders. When omitted the layer constructs a new engine from graph or data.

layout (GraphLayout, optional)​

Layout algorithm used by the engine. Pass one of the bundled layouts such as D3ForceLayout or implement a custom layout that conforms to the interface.

Styling​

stylesheet (GraphLayerStylesheet, optional)​

Declarative description of node and edge appearance. Supply nodes as an array and edges as a single object or array when stacking edge passes. The layer still accepts the legacy nodeStyle/edgeStyle props but they are deprecated and forward to the stylesheet internally.

Interaction​

See the interaction reference for signatures and usage notes.

nodeEvents (object, optional)​

Register interaction callbacks for nodes. Supported keys are onMouseLeave, onHover, onMouseEnter, onClick, and onDrag.

edgeEvents (object, optional)​

Interaction callbacks for edges. Supports onClick and onHover.

Layout lifecycle​

onLayoutStart / onLayoutChange / onLayoutDone / onLayoutError (functions, optional)​

Register callbacks that mirror the underlying layout lifecycle. Each handler receives the GraphLayoutEventDetail object emitted by the active engine. GraphLayer wires these callbacks through to the active GraphEngine so they run alongside the layer's internal state updates (e.g. viewport fitting, loading indicators). Supply only the handlers you need—they are all optional.

enableDragging (boolean, optional)​

When true, nodes can be repositioned by dragging. The interaction manager updates the layout and stylesheet state automatically during drags.

layoutUpdateInterval (number, optional)​

Minimum time in milliseconds between intermediate layout snapshots. Defaults to 0, which updates on every layout change. For example, layoutUpdateInterval: 50 coalesces intermediate changes into at most one snapshot every 50 milliseconds. The trailing snapshot uses the latest layout geometry, and every lifecycle callback still runs immediately. Start, completion and error events update immediately and cancel pending work so the final geometry and status are available in the callback.

Changing the interval reschedules pending work. Replacing the graph engine or finalizing the layer cancels it. Nonpositive or nonfinite values disable throttling. The interval controls layout-driven updates; interactions and other deck.gl redraws can still render between snapshots. JSON playground configurations accept finite, nonnegative intervals.

Miscellaneous​

pickable (boolean, optional)​

Inherited from CompositeLayer. Defaults to true so nodes and edges respond to hover and click events. Disable if you only need a static rendering.

rankGrid (boolean | object, optional)​

Draw grid lines that align with ranked layers in the active layout. Pass true to enable the default configuration or supply an object to customize the behavior:

new GraphLayer({
  id: 'dag',
  layout: new D3DagLayout({layering: 'simplex'}),
  rankGrid: {
    enabled: true,
    direction: 'horizontal',
    rankAccessor: 'rank',
    maxLines: 8,
    gridProps: {
      color: [148, 163, 184, 220],
      labelOffset: [8, 0]
    }
  }
});

GraphLayer samples the layout engine for node positions, maps each rank to an averaged Y coordinate, and renders the overlay with the reusable GridLayer. When multiple ranks collapse onto the same coordinate the layer redistributes them across the current viewport bounds so the lines stay readable. The configuration supports:

  • enabled (default true) – toggle the overlay without changing other settings.
  • direction ('horizontal' | 'vertical', default 'horizontal') – orient the grid lines to match the DAG orientation.
  • rankAccessor (string | function) – read the rank field from each node. By default the accessor falls back to the srank property computed by the DAG layout.
  • labelAccessor (string | function) – override the text shown next to each grid line.
  • maxLines (number, default 8) – limit how many ranks are rendered.
  • gridProps – forwarded to the underlying GridLayer so you can adjust line color, width, label offsets, and similar presentation details.

Notes​

  • The layer resolves the stylesheet through the GraphStylesheetEngine (also exported as GraphStyleEngine for backward compatibility), which coalesces attribute bindings, selectors, and triggers before delegating to the underlying Deck.gl sublayers.
  • Reusing the same GraphEngine instance across renders preserves layout state and interaction history. Provide the engine prop to opt into that workflow.

layoutTransitionDuration (number, default: 0)​

Duration in milliseconds for interpolating node, edge, and decorator positions between layout snapshots. Zero, negative, and nonfinite values disable interpolation. Configure layoutUpdateInterval separately to coalesce intermediate snapshots; all lifecycle callbacks still fire.

new GraphLayer({
  data: graphData,
  layout: new D3ForceLayout(),
  layoutUpdateInterval: 100,
  layoutTransitionDuration: 100
});

Entries supplied through deck.gl's transitions prop override the generated position settings. For example, transitions: {getPosition: 0} disables node-position interpolation while retaining the duration for edge endpoints. Path and polygon interpolation uses deck.gl's normal geometry transition behavior, including its rules for topology changes.