turf.isolines

What is turf.isolines?

turf.isolines generates contour lines — also known as isolines — from a rectangular grid of points carrying a numeric property. It returns a FeatureCollection<MultiLineString> where each feature traces the locus of a single break value across the surface.

turf.isolines(pointGrid, breaks, options?) → FeatureCollection<MultiLineString>

Options include:

• zProperty — property name holding z-values (default 'elevation')
• commonProperties — properties added to every isoline
• breaksProperties — array of per-break property objects

Input must be a rectangular point grid (minimum 2×2), typically generated from turf.pointGrid and turf.interpolate.

When would you use turf.isolines?

Use turf.isolines for topographic-style contour overlays — showing elevation at 50 m intervals, pressure systems on a weather map, signal-strength contours, or noise-level outlines. They read well over a basemap because they do not occlude the underlying data.

Lines are cheaper to render than filled bands and are preferred where you need to emphasise the shape of gradients rather than the values between them. Pair with turf.isobands to combine filled regions with labelled contour lines.

1const contours = turf.isolines(elevationGrid, [100, 200, 300, 400, 500], {
2  zProperty: 'elevation',
3  breaksProperties: [
4    { label: '100m' }, { label: '200m' }, { label: '300m' }, { label: '400m' }, { label: '500m' }
5  ]
6});

FAQs

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

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

How does turf.isolines differ from turf.isobands?

isolines emits open contour lines at exact break values. isobands emits filled MultiPolygons between consecutive breaks. Use both together for classic topographic styling — bands for colour, lines for contours.

Why are my contours jagged?

The grid is too coarse for the data variation. Lower the cellSize you pass to turf.pointGrid or turf.interpolate, or smooth your input. Rendering with an anti-aliased line width also helps visual quality.

Can I label the contour lines?

Yes. Pass a breaksProperties array — each isoline carries the corresponding properties, which MapLibre can consume as a data-driven text-field on a symbol layer.