turf.hexGrid
What is turf.hexGrid?
turf.hexGrid tesselates a bounding box with flat-topped hexagons on an odd-q offset lattice and returns the hexagons (or optionally their triangulation) as a FeatureCollection<Polygon>.
turf.hexGrid(bbox, cellSide, options?) → FeatureCollection<Polygon>Options include:
units— units forcellSide(default'kilometers')properties— properties attached to every cellmask— aPolygonorMultiPolygon— cells are kept only if their centre lies inside the masktriangles— iftrue, returns six triangles per hex instead of whole hexes
When would you use turf.hexGrid?
Hex bins are the standard spatial-binning unit because they avoid the distortion of square grids along the diagonal axes. Use turf.hexGrid to aggregate millions of points into a readable choropleth, to produce uniform sampling cells for a study area, or to build the domain of a cellular-automata simulation on a web map.
Paired with turf.collect (one hex at a time) or a manual join using turf.booleanPointInPolygon, hex grids are the fastest way to produce a classic dot-density bin map in the browser.
1const bbox = [-122.6, 37.6, -122.3, 37.9];
2const hexes = turf.hexGrid(bbox, 0.5, { units: 'kilometers' });FAQs
How do I install Turf.js to use this function?
Install npm install @turf/hex-grid and import import { hexGrid } from '@turf/hex-grid', or reach it through the @turf/turf bundle.
How large is cellSide measured?
cellSide is the distance from the centre of a hexagon to one of its vertices, in the chosen units. It does not represent the cell's area — for a target area, compute cellSide = sqrt(2 * area / (3 * sqrt(3))).
Can I mask the grid to a non-rectangular study area?
Yes. Pass options.mask as a Polygon or MultiPolygon and only hexes whose centroids fall inside the mask are returned. This is much faster than generating the full bbox grid and post-filtering.
How does hexGrid compare to squareGrid and triangleGrid?
Hex grids give the most uniform neighbour distance and minimise boundary distortion, making them preferred for spatial binning. Square grids are simpler to align with raster data, and triangle grids are used in scientific viz. All three helpers share the same bbox, cellSide, units, mask, properties API.
