turf.difference

What is turf.difference?

turf.difference subtracts one polygon from another. Given a first polygon A and a second polygon B, it returns the part of A not covered by B. The output is a Polygon, MultiPolygon, or null if the difference is empty.

turf.difference(featureCollection) → Feature<Polygon | MultiPolygon> | null

In current versions, pass a FeatureCollection of two polygons; legacy versions accepted two feature arguments. Check your installed version.

When would you use turf.difference?

Use turf.difference to cut holes, carve out protected zones, or compute "A minus B" spatial queries. Typical uses: remove a restricted area from a search polygon, compute the land outside a park boundary, or subtract a tile extent you have already processed from a larger region of interest.

In Node.js, turf.difference is the primitive operation behind any "remove X from Y" workflow — ideal for rolling your own spatial pipeline without PostGIS.

undefined

FAQs

What does it return when B covers A completely?

null. Handle this case defensively — cleanup code that dereferences the returned feature will throw otherwise.

Do I pass two features or a FeatureCollection?

It depends on the Turf version. Recent major versions expect a FeatureCollection<Polygon> with exactly two features. Earlier versions used two arguments. Check your @turf/difference package README for the signature.

How do I install just difference?

npm install @turf/difference. It depends on @turf/helpers and polygon-clipping (the Martinez-Rueda implementation).

Can the polygons have holes?

Yes — holes are respected. The Martinez-Rueda algorithm handles polygons with holes and MultiPolygon inputs correctly, producing a topologically valid result.