maplibre-layer-factory

MapLibre Layer Factory is a plugin to customise layers in MapLibre GL JS, in a simple but flexible way.

The style is based on squared buttons that can be selected/deselected to show/hide layers, only one at the time.

Features

• Orientation of layers buttons (horizontal, vertical)
• Placeholder support for layers buttons
• Custom styling for panel and layer buttons
• Label and caption for layer metadata
• Possibility to ignore a layer
• Support for overlay layers (multi-select checkboxes rendered separately from base layers)
• Grouping of overlays under collapsible accordion sections
• Custom styling for overlay panels, checkbox rows, labels, and group headers
• layerchange map event fired on base/overlay toggle

Installation

npm install maplibre-layer-factory

Api

Layer Factory Options

Option	Type	Default	Description	Mandatory
orientation	"horizontal" | "vertical"	"vertical"	Orientation of layers buttons	No
panelStyle	CSSStyleDeclaration	{}	Custom styling for panel	No
layerButtonStyle.default	CSSStyleDeclaration	{}	Custom styling for layer buttons in default state	No
layerButtonStyle.selected	CSSStyleDeclaration	{}	Custom styling for layer buttons in selected state	No
labelStyle.element	CSSStyleDeclaration	{}	Custom styling for label element	No
labelStyle.tag	CSSStyleDeclaration	{}	Custom styling for label tag	No
labelStyle.text	CSSStyleDeclaration	{}	Custom styling for label text	No
labelStyle.caption	CSSStyleDeclaration	{}	Custom styling for label caption	No
withLabel	boolean	false	Show label	No
overlayStyle.panel	CSSStyleDeclaration	{}	Custom styling for the overlay panel wrapping container	No
overlayStyle.row	CSSStyleDeclaration	{}	Custom styling for each overlay row	No
overlayStyle.label	CSSStyleDeclaration	{}	Custom styling for each overlay label text	No
overlayStyle.groupHeader	CSSStyleDeclaration	{}	Custom styling for overlay accordion summary header	No

Layer Configuration Object

Property	Type	Default	Description	Mandatory
metadata.placeholder	string	undefined	URL to placeholder image for layer button	No
metadata.name	string	undefined	Name of the layer	No
metadata.caption	string	undefined	Caption of the layer	No
metadata.ignore	boolean	false	Ignore layer	No
metadata.overlay	boolean	false	Mark layer as overlay (displays as checklist/accordion instead of radio selector)	No
metadata.group	string	undefined	Optional group name for bundling overlays under an accordion	No

Events

The control fires a layerchange event on map when base layer selected or overlay toggled.

Property	Type	Description
kind	"base" | "overlay"	Which layer type changed
id	string	Layer id
visible	boolean	Overlay visibility (only for kind: "overlay")

map.on('layerchange', (e) => {
    console.log(e.kind, e.id, e.visible);
});

Plugin Html Structure

• container
  • toggle
  • panel
    • panel layers
    • panel label
    • panel overlays

Example

The example below shows how to use the MapLibre Layer Factory to create a control with all available options.

import { MapLibreLayerFactory } from "maplibre-layer-factory";
import "maplibre-layer-factory/style.css";

const layerFactory = new MapLibreLayerFactory({
    orientation: "vertical",
    panelStyle: {
        backgroundColor: "red"
    },
    layerButtonStyle: {
        default: {
            backgroundColor: "green",
            border: "none",
            color: "green"
        },
        selected: {
            backgroundColor: "blue",
            border: "2px solid blue",
            color: "blue"
        }
    },
    labelStyle: {
        element: {
            backgroundColor: "blue"
        },
        tag: {
            backgroundColor: "grey"
        },
        text: {
            color: "white"
        },
        caption: {
            color: "white"
        }
    },
    withLabel: true,
    overlayStyle: {
        panel: {
            gap: "6px"
        },
        row: {
            padding: "6px 12px"
        },
        label: {
            fontWeight: "bold"
        },
        groupHeader: {
            fontSize: "14px"
        }
    }
});
map.addControl(layerFactory, 'top-left');

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Alessandro Rabitti 💻 ️️️️♿️ 📖

Vincent Kranendonk 🎨 🤔

This project follows the all-contributors specification. Contributions of any kind welcome!