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

HexagonLayer

Quick answer

The HexagonLayer aggregates data into a hexagon-based heatmap. The color and height of a hexagon are determined based on the objects it contains.

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

The HexagonLayer aggregates data into a hexagon-based heatmap. The color and height of a hexagon are determined based on the objects it contains.

HexagonLayer is a CompositeLayer.

import {Deck} from '@deck.gl/core';
import {HexagonLayer} from '@deck.gl/aggregation-layers';

const layer = new HexagonLayer({
  id: 'HexagonLayer',
  data: 'https://raw.githubusercontent.com/visgl/deck.gl-data/master/website/sf-bike-parking.json',

  gpuAggregation: true,
  extruded: true,
  getPosition: d => d.COORDINATES,
  getColorWeight: d => d.SPACES,
  getElevationWeight: d => d.SPACES,
  elevationScale: 4,
  radius: 200,
  pickable: true
});

new Deck({
  initialViewState: {
    longitude: -122.4,
    latitude: 37.74,
    zoom: 11
  },
  controller: true,
  getTooltip: ({object}) => object && `Count: ${object.elevationValue}`,
  layers: [layer]
});

Installation​

To install the dependencies from NPM:

npm install deck.gl
# or
npm install @deck.gl/core @deck.gl/layers @deck.gl/aggregation-layers
import {HexagonLayer} from '@deck.gl/aggregation-layers';
import type {HexagonLayerProps, HexagonLayerPickingInfo} from '@deck.gl/aggregation-layers';

new HexagonLayer<DataT>(...props: HexagonLayerProps<DataT>[]);

To use pre-bundled scripts:

<script src="https://unpkg.com/deck.gl@^9.0.0/dist.min.js"></script>
<!-- or -->
<script src="https://unpkg.com/@deck.gl/core@^9.0.0/dist.min.js"></script>
<script src="https://unpkg.com/@deck.gl/layers@^9.0.0/dist.min.js"></script>
<script src="https://unpkg.com/@deck.gl/aggregation-layers@^9.0.0/dist.min.js"></script>
new deck.HexagonLayer({});

Properties​

Inherits from all Base Layer and CompositeLayer properties.

Aggregation Options​

gpuAggregation (boolean, optional)​

When set to true, aggregation is performed on the GPU.

In the right context, enabling GPU aggregation can significantly speed up your application. However, depending on the nature of input data and required application features, there are pros and cons in leveraging this functionality. See CPU vs GPU aggregation for an in-depth discussion.

CPU aggregation is used as fallback in the following cases:

radius (number, optional)​

Radius of hexagon in meters. The hexagons are pointy-topped (rather than flat-topped).

colorAggregation (string, optional)​

Defines the operation used to aggregate all data object weights to calculate a hexagon's color value. Valid values are:

getColorWeight and colorAggregation together determine the color value of each hexagon. If the getColorValue prop is supplied, they will be ignored.

Example: Color by the count of data elements​
Option A: use getColorValue (CPU only)
const layer = new HexagonLayer<BikeRack>({
  //...
  getColorValue: (points: BikeRack[]) => points.length
});
Option B: use getColorWeight and colorAggregation (CPU or GPU)
const layer = new HexagonLayer<BikeRack>({
  // ...
  getColorWeight: 1,
  colorAggregation: 'COUNT'
});
Example: Color by the mean value of 'SPACES' field​
Option A: use getColorValue (CPU only)
const layer = new HexagonLayer<BikeRack>({
  // ...
  getColorValue: (points: BikeRack[]) => {
    // Calculate mean value
    return points.reduce((sum: number, p: BikeRack) => sum += p.SPACES, 0) / points.length;
  }
});
Option B: use getColorWeight and colorAggregation (CPU or GPU)
const layer = new HexagonLayer<BikeRack>({
  // ...
  getColorWeight: (point: BikeRack) => point.SPACES,
  colorAggregation: 'MEAN'
});

If your use case requires aggregating using an operation other than the built-in colorAggregation values, getColorValue should be used to define such custom aggregation function.

elevationAggregation (string, optional)​

Defines the operation used to aggregate all data object weights to calculate a hexagon's elevation value. Valid values are:

getElevationWeight and elevationAggregation together determine the elevation value of each hexagon. If the getElevationValue prop is supplied, they will be ignored.

Example: Elevation by the count of data elements​
Option A: use getElevationValue (CPU only)
const layer = new HexagonLayer<BikeRack>({
  // ...
  getElevationValue: (points: BikeRack[]) => points.length
});
Option B: use getElevationWeight and elevationAggregation (CPU or GPU)
const layer = new HexagonLayer<BikeRack>({
  // ...
  getElevationWeight: 1,
  elevationAggregation: 'COUNT'
});
Example: Elevation by the maximum value of 'SPACES' field​
Option A: use getElevationValue (CPU only)
const layer = new HexagonLayer<BikeRack>({
  // ...
  getElevationValue: (points: BikeRack[]) => {
    // Calculate max value
    return points.reduce((max: number, p: BikeRack) => p.SPACES > max ? p.SPACES : max, -Infinity);
  }
});
Option B: use getElevationWeight and elevationAggregation (CPU or GPU)
const layer = new HexagonLayer<BikeRack>({
  // ...
  getElevationWeight: (point: BikeRack) => point.SPACES,
  elevationAggregation: 'MAX'
});

If your use case requires aggregating using an operation other than the built-in elevationAggregation values, getElevationValue should be used to define such custom aggregation function.

hexagonAggregator (Function, optional)​

A custom function to override how points are grouped into hexagonal bins. If this prop is supplied, GPU aggregation will be disabled regardless of the gpuAggregation setting.

This function will be called with the following arguments:

It is expected to return an array of 2 integers that represent a hexagon ID. Points that resolve to the same hexagon ID are grouped together.

By default, the HexagonLayer uses d3-hexbin as hexagonAggregator, see modules/aggregation-layers/src/hexagon-layer/hexbin.ts

Render Options​

coverage (number, optional) ​

Hexagon radius multiplier, clamped between 0 - 1. The displayed radius of hexagon is calculated by coverage * radius. Note: coverage does not affect how objects are binned.

extruded (boolean, optional)​

Whether to render the hexagons as 3D columns. If set to false, all hexagons will be flat.

colorScaleType (string, optional)​

The color scale converts from a continuous numeric stretch (colorDomain) into a list of colors (colorRange). Hexagons with value of colorDomain[0] will be rendered with the color of colorRange[0], and hexagons with value of colorDomain[1] will be rendered with the color of colorRange[colorRange.length - 1].

colorScaleType determines how a numeric value in domain is mapped to a color in range. Supported values are:

Note that using "quantile" or "ordinal" scale with GPU aggregation will incur a one-time cost of reading aggregated values from the GPU to the CPU. This overhead may be undesirable if the source data updates frequently.

colorDomain (number[2], optional)​

If not provided, the layer will set colorDomain to the actual min, max values from all hexagons at run time.

By providing a colorDomain, you can control how a value is represented by color. This is useful when you want to render different data input with the same color mapping for comparison.

colorRange (Color[], optional)​

Specified as an array of colors [color1, color2, ...]. Each color is an array of 3 or 4 values [R, G, B] or [R, G, B, A], representing intensities of Red, Green, Blue and Alpha channels. Each intensity is a value between 0 and 255. When Alpha is omitted a value of 255 is used.

elevationScaleType (string, optional)​

The elevation scale converts from a continuous numeric stretch (elevationDomain) into another continuous numeric stretch (elevationRange). Hexagons with value of elevationDomain[0] will be rendered with the elevation of elevationRange[0], and hexagons with value of elevationDomain[1] will be rendered with the elevation of elevationRange[1].

elevationScaleType determines how a numeric value in domain is mapped to a elevation in range. Supported values are:

elevationDomain (number[2], optional)​

If not provided, the layer will set elevationDomain to the actual min, max values from all hexagons at run time.

By providing a elevationDomain, you can control how a value is represented by elevation. This is useful when you want to render different data input with the same elevation mapping for comparison.

elevationRange (number[2], optional) ​

Elevation scale output range

elevationScale (number, optional) ​

Hexagon elevation multiplier. This is a handy property to scale all hexagons without updating the data.

upperPercentile (number, optional) ​

Filter hexagons and re-calculate color by upperPercentile. Hexagons with value larger than the upperPercentile will be hidden.

Note that using this prop with GPU aggregation will incur a one-time cost of reading aggregated values from the GPU to the CPU. This overhead may be undesirable if the source data updates frequently.

lowerPercentile (number, optional) ​

Filter hexagons and re-calculate color by lowerPercentile. Hexagons with value smaller than the lowerPercentile will be hidden.

Note that using this prop with GPU aggregation will incur a one-time cost of reading aggregated values from the GPU to the CPU. This overhead may be undesirable if the source data updates frequently.

elevationUpperPercentile (number, optional) ​

Filter hexagons and re-calculate elevation by elevationUpperPercentile. Hexagons with elevation value larger than the elevationUpperPercentile will be hidden.

Note that using this prop with GPU aggregation will incur a one-time cost of reading aggregated values from the GPU to the CPU. This overhead may be undesirable if the source data updates frequently.

elevationLowerPercentile (number, optional) ​

Filter bns and re-calculate elevation by elevationLowerPercentile. Hexagons with elevation value smaller than the elevationLowerPercentile will be hidden.

Note that using this prop with GPU aggregation will incur a one-time cost of reading aggregated values from the GPU to the CPU. This overhead may be undesirable if the source data updates frequently.

material (Material, optional)​

This is an object that contains material props for lighting effect applied on extruded polygons. Check the lighting guide for configurable settings.

Data Accessors​

getPosition (Accessor<Position>, optional)​

Method called to retrieve the position of each object.

getColorWeight (Accessor<number>, optional) ​

The weight of a data object used to calculate the color value for a hexagon.

getColorValue (Function, optional) ​

After data objects are sorted into hexagonal bins, this accessor is called on each hexagon to get the value that its color is based on. If supplied, this will override the effect of getColorWeight and colorAggregation props.

Arguments:

getElevationWeight (Accessor<number>, optional) ​

The weight of a data object used to calculate the elevation value for a hexagon.

getElevationValue (Function, optional) ​

After data objects are sorted into hexagonal bins, this accessor is called on each hexagon to get the value that its elevation is based on. If supplied, this will override the effect of getElevationWeight and elevationAggregation props.

Arguments:

Callbacks​

onSetColorDomain (Function, optional)​

This callback will be called when hexagon color domain has been calculated.

onSetElevationDomain (Function, optional)​

This callback will be called when hexagon elevation domain has been calculated.

Picking​

The PickingInfo.object field returned by hover/click events of this layer represents an aggregated hexagon. The object contains the following fields:

Sub Layers​

The HexagonLayer renders the following sublayers:

Source​

modules/aggregation-layers/src/hexagon-layer

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/aggregation-layers/hexagon-layer · Chinese note: /deckgl/api/hexagon-layer.html
Cite this page

Atlaslog (2026). HexagonLayer. https://www.jingweizhi.com/en/deckgl/api/hexagon-layer.html (accessed 2026-11-03).