Maplibre-gl Mask Plugin

Add a mask around a geojson feature in Maplibre GL JS.

This plugin is inspired by this QGis Mask plugin

Demo

👉 Live Demo

Installation

Install maplibre-gl-mask-plugin with npm

npm install maplibre-gl-mask-plugin

Or use it from CDN

<script type="module" src="https://unpkg.com/maplibre-gl-mask-plugin/dist/index.js"></script>

Usage

import maplibregl from 'maplibre-gl';
import { createMask } from 'maplibre-gl-mask-plugin';
import geojsonFeature from './feature.geojson';

const map = new maplibregl.Map({
  container: 'map',
  style: 'https://tiles.openfreemap.org/styles/bright'
});

createMask(map, 'mask', geojsonFeature);

API Reference

createMask

import { createMask } from 'maplibre-gl-mask-plugin';
createMask(map, name, feature, options);

| Parameter | Type | Description | |-----------|------------------------------------|-------------------------------------------| | map | maplibregl.Map | Maplibre map instance | | name | string | Unique mask name | | feature | Feature<Polygon \| MultiPolygon> | Geojson feature (polygon or multipolygon) | | options | Partial<MaskOptions> | Mask options (see below) |

removeMask

import { removeMask } from 'maplibre-gl-mask-plugin';
removeMask(map, name);

| Parameter | Type | Description | |-----------|------------------------------------|-----------------------| | map | maplibregl.Map | Maplibre map instance | | name | string | Created mask name |

MaskOptions

| Option | Type | Default | |----------------|--------------------------|---------| | simplify | @turf/simplify options | - |

If the feature polygon need to be simplified, pass @turf/simplify options here. See turf/simplify documentation. Polygons with more than 1000 coordinates will have poor performance.

| Option | Type | Default | |-------------------|----------|---------| | backgroundColor | string | #FFF |

Mask background color (ex: "#FFF", or "yellow")

| Option | Type | Default | |---------------------|----------|---------| | backgroundOpacity | number | 0.7 |

Mask background opacity (between 0 and 1). Use 0 if no background is needed

| Option | Type | Default | |-------------------|----------|---------| | gradientColor | string | #AAA |

Mask gradient color (ex: "#AAA", or "black")

| Option | Type | Default | |--------------------|----------|---------| | gradientLayers | number | 30 |

Gradient layers number. More layers is smoother but slower to compute. Use 0 if no gradient is needed. Gradient is computed incrementally by increasing layers. For example with 30 layers, it will display progressively 2 -> 3 -> 5 -> 6 -> 10 -> 15 -> 30 layers once they are fully computed. Using a prime number or a number with less factors will disable or decrease incremental computation.

| Option | Type | Default | |----------------------|----------------------|---------------------| | gradientLayerWidth | number \| function | 40960 / 2^zoom |

Gradient layers width. Total gradient width is the number of layers * this width. Default layer width will vary with map zoom, which gives the following results:

• z6: 640m
• z10: 40m
• z14: 2.5m

If a number is given, it will be a factor of the default width function. Use 0 if no gradient is needed.

A custom function can also be provided. It should be of type (zoom: number) => number. Result will be in meters.

| Option | Type | Default | |----------------|-----------|-----------| | hideLabels | boolean | true |

Determines if symbols and labels outside feature polygon should be hidden.

The behaviour when enabling this option is to hide all symbol layers in the current style, and clone them adding geographic filter matching the feature given.

Peer Dependencies

This library requires the following peer dependencies to be installed in your project:

• maplibre-gl-js >= v5.16.0

License

MIT