turf.isobands

What is turf.isobands?

turf.isobands builds filled contour regions from a regular point grid carrying a numeric z-property. Given an array of break values, it returns a FeatureCollection<MultiPolygon> where each MultiPolygon fills the area whose z-values fall between two consecutive breaks.

turf.isobands(pointGrid, breaks, options?) → FeatureCollection<MultiPolygon>

Options include:

• zProperty — property name holding z-values (default 'elevation')
• commonProperties — properties applied to every output band
• breaksProperties — array of per-band property objects

The input must be a rectangular grid of points (minimum 2×2) — typically the output of turf.pointGrid plus an interpolate/sample step.

When would you use turf.isobands?

Use turf.isobands for filled-contour choropleths — showing elevation bands, heat zones, pollution plumes, or signal coverage as coloured polygons that can be styled directly in MapLibre or Mapbox without a raster tile service.

Because the output is vector, it scales cleanly at any zoom and interacts well with picking and tooltips. Pair it with turf.interpolate to go from scattered measurements to styled bands in a single client-side pipeline.

1const breaks = [0, 10, 25, 50, 100];
2const bands = turf.isobands(gridWithPm25, breaks, {
3  zProperty: 'pm25',
4  breaksProperties: [
5    { label: 'Good' }, { label: 'Moderate' }, { label: 'Unhealthy' }, { label: 'Hazardous' }
6  ]
7});

FAQs

How do I install Turf.js to use this function?

Install npm install @turf/isobands and import import { isobands } from '@turf/isobands', or use turf.isobands from the umbrella @turf/turf bundle.

Why does the function throw "gridded points are required"?

turf.isobands only works on a rectangular grid with constant spacing. If you pass raw sensor stations, you must first interpolate them onto a grid — turf.interpolate(..., { gridType: 'point' }) produces suitable input.

How many break values should I supply?

Four to seven breaks work well for most visual palettes. Too many produces slivered polygons at band edges; too few hides structure. Your breaksProperties array should have one entry per interval between consecutive breaks.

When should I use isolines instead?

Use turf.isolines when you want contour lines (outlines) rather than filled bands — useful for topographic maps or overlaying contours on a basemap. isobands is the choice when you want coloured regions.