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

GridLayer

Quick answer

The GridLayer aggregates data into a grid-based heatmap. The color and height of a grid cell 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 GridLayer aggregates data into a grid-based heatmap. The color and height of a grid cell are determined based on the objects it contains.

GridLayer is a CompositeLayer.

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

const layer = new GridLayer({
  id: 'GridLayer',
  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,
  cellSize: 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 {GridLayer} from '@deck.gl/aggregation-layers';
import type {GridLayerProps, GridLayerPickingInfo} from '@deck.gl/aggregation-layers';

new GridLayer<DataT>(...props: GridLayerProps<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.GridLayer({});

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:

cellSize (number, optional)​

Size of each cell in meters.

colorAggregation (string, optional)​

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

getColorWeight and colorAggregation together determine the color value of each cell. 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 cell's elevation value. Valid values are:

getElevationWeight and elevationAggregation together determine the elevation value of each cell. 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.

gridAggregator (Function, optional)​

A custom function to override how points are grouped into grid cells. 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 cell ID. Points that resolve to the same cell ID are grouped together.

Render Options​

coverage (number, optional) ​

Cell size multiplier, clamped between 0 - 1. The displayed size of cell is calculated by coverage * cellSize. Note: coverage does not affect how objects are binned.

extruded (boolean, optional)​

Whether to enable cell elevation.If set to false, all cell will be flat.

colorScaleType (string, optional)​

The color scale converts from a continuous numeric stretch (colorDomain) into a list of colors (colorRange). Cells with value of colorDomain[0] will be rendered with the color of colorRange[0], and cells 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 cells 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). Cells with value of elevationDomain[0] will be rendered with the elevation of elevationRange[0], and cells 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 cells 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) ​

Cell elevation multiplier. This is a handy property to scale all cells without updating the data.

upperPercentile (number, optional) ​

Filter cells and re-calculate color by upperPercentile. Cells 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 cells and re-calculate color by lowerPercentile. Cells 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 cells and re-calculate elevation by elevationUpperPercentile. Cells 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 cells and re-calculate elevation by elevationLowerPercentile. Cells 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 cell.

getColorValue (Function, optional) ​

After data objects are aggregated into cells, this accessor is called on each cell to get the value that its color is based on. If supplied, this will override the effect of getColorWeight and colorAggregation props. Note that supplying this prop disables GPU aggregation.

Arguments:

getElevationWeight (Accessor<number>, optional) ​

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

getElevationValue (Function, optional) ​

After data objects are aggregated into cells, this accessor is called on each cell 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 cell color domain has been calculated.

onSetElevationDomain (Function, optional)​

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

Picking​

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

Sub Layers​

The GridLayer renders the following sublayers:

Source​

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

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