JSPM

Package Exports

maplibre-gl-html-widget
maplibre-gl-html-widget/src/maplibre-gl-html-widget.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (maplibre-gl-html-widget) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

A flexible plugin for MapLibre GL JS that allows you to add customizable HTML widgets to your map with optional show/hide toggle functionality.

Features

Add any HTML content to your map as a widget
Position widgets in any corner of the map
Optional collapsible/expandable functionality with a toggle button
Customizable styling
Programmatic control over widget visibility
Dynamic content updates
Lightweight and easy to use

Installation

Using npm

npm install maplibre-gl-html-widget

Using a CDN

<link rel="stylesheet" href="path/to/maplibre-gl-html-widget.css">
<script src="path/to/maplibre-gl-html-widget.js"></script>

Usage

Basic Example

import maplibregl from 'maplibre-gl';
import HtmlWidget from 'maplibre-gl-html-widget';
import 'maplibre-gl-html-widget/src/maplibre-gl-html-widget.css';

const map = new maplibregl.Map({
    container: 'map',
    style: 'https://demotiles.maplibre.org/style.json',
    center: [0, 0],
    zoom: 2
});

// Create a simple widget
const widget = new HtmlWidget({
    content: '<h3>My Widget</h3><p>This is a custom HTML widget!</p>',
    position: 'top-right'
});

map.addControl(widget);

const collapsibleWidget = new HtmlWidget({
    content: `
        <h3>Legend</h3>
        <ul>
            <li>🔴 Category A</li>
            <li>🔵 Category B</li>
            <li>🟢 Category C</li>
        </ul>
    `,
    position: 'bottom-right',
    collapsible: true,
    collapsed: false,  // Start expanded
    toggleIcon: '≡'    // Custom toggle icon
});

map.addControl(collapsibleWidget);

Using DOM Elements

// Create a DOM element
const element = document.createElement('div');
element.innerHTML = `
    <h3>Interactive Widget</h3>
    <button id="my-button">Click me!</button>
`;

const widget = new HtmlWidget({
    content: element,
    position: 'top-left',
    maxWidth: 300,
    maxHeight: 200
});

map.addControl(widget);

// Add event listeners
document.getElementById('my-button').addEventListener('click', () => {
    alert('Button clicked!');
});

API Reference

Constructor Options

Option	Type	Default	Description
`content`	`string\|HTMLElement`	required	HTML string or DOM element to display
`position`	`string`	`'top-right'`	Widget position: `'top-left'`, `'top-right'`, `'bottom-left'`, `'bottom-right'`
`collapsible`	`boolean`	`false`	Whether the widget can be collapsed/expanded
`collapsed`	`boolean`	`false`	Initial collapsed state (only if `collapsible` is `true`)
`toggleIcon`	`string`	`'☰'`	Icon/text to show in the toggle button
`className`	`string`	`''`	Additional CSS class name(s) for the widget container
`maxWidth`	`number`	`null`	Maximum width in pixels
`maxHeight`	`number`	`null`	Maximum height in pixels

Methods

`toggle()`

Toggle the widget between collapsed and expanded states.

widget.toggle();

`show()`

Show the widget content (expand if collapsed).

widget.show();

`hide()`

Hide the widget content (collapse).

widget.hide();

`isCollapsed()`

Check if the widget is currently collapsed.

const collapsed = widget.isCollapsed();

`setContent(content)`

Update the widget content dynamically.

widget.setContent('<h3>Updated!</h3><p>New content here.</p>');

`getContainer()`

Get the widget's container DOM element.

const container = widget.getContainer();

`getContentElement()`

Get the widget's content DOM element.

const contentEl = widget.getContentElement();

Styling

The plugin comes with default styles, but you can customize them by targeting these CSS classes:

.maplibregl-ctrl-html-widget - Main container
.maplibregl-ctrl-html-widget-toggle - Toggle button
.maplibregl-ctrl-html-widget-content - Content container
.maplibregl-ctrl-html-widget.collapsed - Collapsed state

Custom Styling Example

.maplibregl-ctrl-html-widget {
    background: #f0f0f0;
    border: 2px solid #333;
}

.maplibregl-ctrl-html-widget-toggle {
    background: #0078d4;
    color: white;
}

.maplibregl-ctrl-html-widget-content {
    padding: 20px;
    font-size: 16px;
}

Examples

Check out the examples/ directory for more complete examples:

Basic widget
Collapsible legend
Interactive controls
Dynamic content updates

Browser Support

This plugin supports all modern browsers that support MapLibre GL JS.

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

maplibre-gl-html-widget