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.