MapLibre GL HTML Widget

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);

Collapsible 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.