Map-GL-Utils

Map-GL-Utils provides a more concise API for interacting with map layers and sources by applying several abstractions:

• Unified Property Management: You no longer need to distinguish between paint, layout, and other property types. All properties can be passed in a single object.
• CamelCase Support: Property keys can be written in camelCase (e.g., lineWidth) instead of the standard Mapbox/Maplibre kebab-case (line-width).
• Type-Specific Methods: Function names incorporate the source or layer type, such as addGeoJSON(), addCircleLayer(), or setCircleRadius().
• Idempotent Operations: Adding a layer (e.g., addLineLayer()) is idempotent; calling it multiple times will create the layer if it doesn't exist or update it if it does.
• Bulk Operations: Most layer methods (like show(), hide(), or setFilter()) can act on multiple layers simultaneously using strings, arrays, regular expressions, or filter functions.
• Enhanced Interaction: Provides specialized functions for common tasks like hoverPointer(), hoverFeatureState(), hoverPopup(), and clickLayer().

Map-GL-Utils can be used with Mapbox GL JS or Maplibre GL JS. You must initialize the utility on your map instance using U.init(map).

Using via CDN (No build process)

Include the script tag in your HTML:

<script src="https://unpkg.com/map-gl-utils"></script>

Then initialize in your JavaScript:

U.init(map);

Using with Webpack/Bundlers

Install via npm and import the module. If you need the ESM version explicitly, import from the dist path.

Standard ESM Import:

import mapgl from 'maplibre-gl'; // or 'mapbox-gl'
import U from 'map-gl-utils';
const map = new mapgl.Map({ ... });
U.init(map);

Explicit ESM Import:

import U from 'map-gl-utils/dist/index.esm.js';

UMD Bundle (for older environments): If you encounter syntax issues with the default ES2015 module, use the UMD bundle which adds a U property directly to the map instance.

require('map-gl-utils/umd').init(map);

Note on Library Access: Some methods (like hoverPopup) require access to the underlying map library (Mapbox or Maplibre) to instantiate objects. In these cases, pass the library instance to init:

require('map-gl-utils').init(map, mapgl);

Additional utilities for map management:

• Lifecycle: onLoad(callback) fires when the map is loaded. It returns a Promise if no callback is provided.
• Styling: getLayerStyle(id) returns a cleaned-up layer definition. setLayerStyle(id, properties) resets properties to defaults before applying new ones. layerStyle(...) is a flexible constructor for creating layer objects.
• Source Visibility: hideSource(id), showSource(id), and toggleSource(id, bool) manage all layers attached to a source.
• Assets: loadImage(id, url, options) loads an image into the map.
• Fonts: fontsInUse() returns an array of fonts currently used in symbol layers.

// Wait for map load
await map.U.onLoad();

// Get cleaned layer style
const style = map.U.getLayerStyle('mylayer');

// Reset and set layer style
map.U.setLayerStyle('mylayer', { lineWidth: 3 });

// Load an image
map.U.loadImage('marker', '/assets/marker-pin.png').then(() => {
    console.log('Loaded');
});

// Get fonts for symbol layers
const fonts = map.U.fontsInUse();

The library simplifies interactive map events:

• hoverPointer(layers): Changes cursor to a 'finger' when hovering over specified layers.
• hoverFeatureState(layer): Manages feature-state for hover effects (requires features to have an id).
• hoverPopup(layer, callback, options): Shows a popup when hovering. The callback receives (feature, popup) and returns an HTML string. Requires U.init(map, mapboxgl) to be called first.
• clickLayer(layers, callback): Adds a click listener that includes a features array in the event object.
• clickOneLayer(layers, callback, missCallback): Tests multiple layers in order and fires the callback for the first hit. An optional missCallback runs if no layers are hit.

Note: All event handler functions return an 'undo' function that, when called, removes the handler.

// Cursor and Feature State
map.U.hoverPointer(['regions-border', 'regions-fill']);
map.U.hoverFeatureState('mylayer');

// Popups (Requires U.init(map, mapboxgl))
const remove = map.U.hoverPopup('mylayer', f => `<h3>${f.properties.Name}</h3>`, { anchor: 'left' });
remove(); // Removes the hover popup

// Clicking
map.U.clickLayer(['towns', 'town-labels'], e => {
    console.log(e.features[0].id);
});

map.U.clickOneLayer(['town-labels', 'state-boundaries'], e => {
    if (e.layer === 'town-labels') { /* ... */ }
}, e => {
    console.log('Missed everything');
});