turf.mask

What is turf.mask?

turf.mask returns a Polygon whose exterior ring covers the world (or a provided bbox polygon) and whose interior rings are the input polygons — effectively inverting the fill so everything outside your features is filled, and everything inside is cut out.

turf.mask(polygon, mask?) → Feature<Polygon>

When would you use turf.mask?

Use turf.mask for the classic "spotlight" effect on a MapLibre map — a translucent overlay that dims everything except your selected feature(s). Render the result as a fill layer above your basemap to draw attention to a country, a parcel, or a user-selected region.

In Node.js, masks are also useful as inverse clipping primitives for composition workflows, particularly in static-tile generation where you want to hide base content outside a region of interest.

undefined

FAQs

What does the outer ring cover by default?

The world extent [-180, -90, 180, 90]. Pass an explicit mask polygon as the second argument to restrict the outer ring.

How do I install just mask?

npm install @turf/mask. It depends on @turf/helpers and @turf/invariant.

Does it handle multiple input polygons?

Yes — a FeatureCollection with multiple polygons produces a single Polygon feature with one exterior ring and one interior ring per input polygon.

What about polygons with existing holes?

Holes in the input are combined into the mask's hole set. The result is still a valid single polygon with all specified interior rings.