maplibre-style-control

A MapLibre GL JS control plugin to switch between different styles.

Live demo

Install

npm install @maptoolkit/maplibre-style-control maplibre-gl

Usage

import * as maplibregl from "maplibre-gl";
import { StyleControl } from "@maptoolkit/maplibre-style-control";
import "@maptoolkit/maplibre-style-control/style.css";

const map = new maplibregl.Map({ container: "map", style, center, zoom });
map.addControl(new StyleControl());

Without a bundler

The package is ESM-only (no UMD/CJS build). Loading it straight from a CDN via a <script> tag works with an import map to resolve the bare maplibre-gl specifier:

<link href="https://unpkg.com/maplibre-gl@^6.0.0/dist/maplibre-gl.css" rel="stylesheet" />
<link href="https://unpkg.com/@maptoolkit/maplibre-style-control@^1.1.0/dist/maplibre-style-control.css" rel="stylesheet" />

<script type="importmap">
  {
    "imports": {
      "maplibre-gl": "https://unpkg.com/maplibre-gl@^6.0.0/dist/maplibre-gl.mjs"
    }
  }
</script>
<script type="module">
  import * as maplibregl from "maplibre-gl";
  import { StyleControl } from "https://unpkg.com/@maptoolkit/maplibre-style-control@^1.1.0/dist/maplibre-style-control.js";

  const map = new maplibregl.Map({ container: "map", style, center, zoom });
  map.addControl(new StyleControl());
</script>

Options

new StyleControl({
  styles: [{ id: "Summer", value: "https://styles.maptoolkit.org/summer.json", image: "..." }],
  active: "Summer",
});

Option	Type	Default	Description
styles	StyleDefSpecification[]	the 7 default maptoolkit styles	Styles shown in the control.
active	string	"Summer"	id of the style selected by default.

StyleDefSpecification:

Field	Type	Description
id	string	Unique id, also used as the i18n key.
value	string | StyleSpecification	Style URL or an inline style spec.
image	string?	Thumbnail shown for the style.

The built-in styles are exported as defaultStyleControlOptions, so you can extend rather than replace them:

import { StyleControl, defaultStyleControlOptions } from "@maptoolkit/maplibre-style-control";

new StyleControl({
  styles: [...defaultStyleControlOptions.styles, { id: "Custom", value: "..." }],
});

Events

The control extends MapLibre's Evented, so you can subscribe like you would on the map itself:

const control = new StyleControl();
control.on("style.set", (e) => console.log(e.style.id));

Event	Payload	Fired when...
style.set	{ style: StyleDefSpecification }	the active style changes.

Methods

const control = new StyleControl();
map.addControl(control);

control.setStyle("Winter");
control.open();
control.close();

Method	Description
setStyle(styleId)	Switches to the style with the given id, same as clicking it in the UI. Fires style.set. Only available once the control has been added to a map via map.addControl() — it's undefined before that.
open()	Opens the style panel.
close()	Closes the style panel.

Styling

Appearance is controlled via CSS custom properties on .maplibre-style-control, defined in style.css. Override them in your own stylesheet to theme the control:

.maplibre-style-control {
  --style-control-radius: 4px;
  --style-control-color-primary: #0074d9;
}

See src/style.css for the full list of --style-control-* variables.

License

maplibre-style-control is open-source under the BSD 3-Clause License.