mapIcons — react-icons → MapLibre raster bridge

Source: src/lib/mapIcons.ts · 93 lines

Purpose

MapLibre symbol layers render in WebGL — React DOM cannot reach into the GL canvas. To use react-icons SVGs (parking, traffic light, stop sign…) on the map we must rasterise them to ImageData and register with map.addImage(id, data).

mapIcons automates the bridge: a id → component registry plus an async batch registrar called once on map load.

Registered icons

id (GeoJSON properties.icon)	react-icons component	Use
icon-parking	FaSquareParking	Parking space P
icon-signal	FaTrafficLight	Traffic signal
icon-barrier	FaRoadBarrier	Barrier gate
icon-stop	BsSignStop	Stop sign
icon-yield	BsSignYieldFill	Yield sign
icon-speed-bump	PiWarningDiamondFill	Speed bump warning

A GeoJSON Feature with properties.icon: 'icon-stop' renders correctly when the maplibre symbol layer uses icon-image: ['get', 'icon'].

Public API

Symbol	Kind	Signature	Summary
MAP_ICON_PX	const	64	Pixel size of every rendered icon
registerMapIcons	fn	async (map) => Promise<void>	Register every icon (idempotent)

MapIconRegistry is internal: Pick<maplibregl.Map, 'hasImage' | 'addImage'>.

Detailed entries

registerMapIcons(map): Promise<void>

export async function registerMapIcons(map: MapIconRegistry): Promise<void> {
  const tasks = Object.entries(REGISTRY).map(async ([id, Icon]) => {
    if (map.hasImage(id)) return;
    try {
      const data = await rasterize(Icon);
      if (!map.hasImage(id)) map.addImage(id, data);
    } catch (err) {
      console.error(`[mapIcons] failed to register ${id}`, err);
    }
  });
  await Promise.all(tasks);
}

Behaviour:

• Skips ids that already exist (idempotent under HMR / multiple loads).
• Per-icon try/catch — one failure does not block the others.
• Parallel rasterisation (~10 ms total versus ~50 ms serial).
• Re-checks hasImage before addImage to handle the race where an HMR cycle registered concurrently.

Call site: MapCanvas.tsx inside map.on('load', () => registerMapIcons(map)) (or 'styledata').

rasterize(Icon): Promise<ImageData> — internal

async function rasterize(Icon: ComponentType<IconProps>): Promise<ImageData> {
  const node: ReactElement = createElement(Icon, { size: ICON_PX, color: ICON_COLOR });
  const inner = renderToStaticMarkup(node);
  const svg = inner.includes('xmlns=')
    ? inner
    : inner.replace('<svg ', '<svg xmlns="http://www.w3.org/2000/svg" ');

  const blob = new Blob([svg], { type: 'image/svg+xml' });
  const url = URL.createObjectURL(blob);
  try {
    const img = await new Promise<HTMLImageElement>((resolve, reject) => {
      const i = new Image(ICON_PX, ICON_PX);
      i.onload = () => resolve(i);
      i.onerror = () => reject(new Error('icon svg load failed'));
      i.src = url;
    });
    const canvas = document.createElement('canvas');
    canvas.width = ICON_PX;
    canvas.height = ICON_PX;
    const ctx = canvas.getContext('2d');
    if (!ctx) throw new Error('2d context unavailable');
    ctx.clearRect(0, 0, ICON_PX, ICON_PX);
    ctx.drawImage(img, 0, 0, ICON_PX, ICON_PX);
    return ctx.getImageData(0, 0, ICON_PX, ICON_PX);
  } finally {
    URL.revokeObjectURL(url);
  }
}

Five steps:

1. createElement(Icon, { size, color }) — React node.
2. renderToStaticMarkup — string-render to SVG markup.
3. Inject xmlns if missing (react-icons output omits it).
4. Blob URL → <img> → <canvas> raster path.
5. getImageData returns RGBA bytes.

Depends on the DOM and Canvas2D, so this must run on the browser main thread — not in a Web Worker.

Constants

const ICON_PX = 64;
const ICON_COLOR = '#ffffff';

64×64 is a sensible default at typical zoom; white is the convention so the paint property icon-color can recolour per feature.

REGISTRY

const REGISTRY: Record<string, ComponentType<IconProps>> = {
  'icon-parking': FaSquareParking,
  'icon-signal': FaTrafficLight,
  'icon-barrier': FaRoadBarrier,
  'icon-stop': BsSignStop,
  'icon-yield': BsSignYieldFill,
  'icon-speed-bump': PiWarningDiamondFill,
};

Adding an icon is a one-line change here — registerMapIcons picks it up.

Side effects

• URL.createObjectURL / revokeObjectURL per call.
• Creates throwaway <canvas> elements (GC-friendly).
• Calls map.addImage.
• console.error on per-icon failure.

Test coverage

src/lib/__tests__/mapIcons.test.ts (jsdom Canvas mock):

• All six icons get registered.
• Existing image ids are skipped (no duplicate addImage).
• A single failure does not block siblings.

Consumers

• src/components/map/MapCanvas.tsx — map.once('styledata', () => registerMapIcons(map))

Design notes

Why not pre-rasterise at build time? Switching icon library or recolouring would require regenerating every PNG. Runtime rasterisation is cheap (~10 ms for six icons) and lets the UI control colour and size centrally.

Why not SDF? SDF stays sharp at any zoom but the generation pipeline is heavier and react-icons' fill-path output rarely converts cleanly. 64 px works at all current zoom levels.

Source map

Lines	Content
17–22	imports
24–25	ICON_PX / ICON_COLOR
29–37	REGISTRY
38	MAP_ICON_PX export
39	MapIconRegistry type
46–74	rasterize
80–92	registerMapIcons

Caller pattern (MapCanvas)

useEffect(() => {
  if (!map) return;
  void registerMapIcons(map);
}, [map]);

Edge case: addImage calls before the style loads are silently dropped. Safer:

useEffect(() => {
  if (!map) return;
  if (map.isStyleLoaded()) {
    void registerMapIcons(map);
  } else {
    map.once('styledata', () => void registerMapIcons(map));
  }
}, [map]);

registerMapIcons is idempotent thanks to the hasImage guard, so a second call is safe.

maplibre symbol-layer example

How to consume the registered ids:

map.addLayer({
  id: 'cold-symbols',
  type: 'symbol',
  source: 'cold',
  filter: ['has', 'icon'],
  layout: {
    'icon-image': ['get', 'icon'], // 'icon-parking' / 'icon-stop' / ...
    'icon-size': ['interpolate', ['linear'], ['zoom'], 14, 0.3, 18, 0.6],
    'icon-allow-overlap': true,
    'icon-ignore-placement': true,
  },
  paint: {
    'icon-color': '#fff', // works alongside ICON_COLOR for paint-property override
    'icon-halo-color': '#000',
    'icon-halo-width': 1,
  },
});

icon-color is a paint-time recolour — it requires monochrome (white) source pixels, which is why ICON_COLOR = '#ffffff'.

Error recovery

A failed icon logs:

console.error('[mapIcons] failed to register icon-stop', err);

Subsequent GeoJSON Features referencing icon-stop cause maplibre to emit styleimagemissing — which we could monitor and downgrade to a text label. Not implemented in v1; the error log suffices.

Perf benchmark

On an M1 Mac, Chrome 120, six 64×64 icons:

• Serial: ~50 ms
• Parallel (current): ~10 ms
• One-shot, startup only — < 0.1 % impact on first paint

Source map (extended)

Lines	Content
17–22	imports (react / react-dom/server / react-icons)
24–27	ICON_PX / ICON_COLOR
29–37	REGISTRY (6 entries)
38	MAP_ICON_PX export
39	MapIconRegistry type
46	rasterize async
47	createElement(Icon, ...)
48	renderToStaticMarkup
51–54	xmlns injection
56–57	Blob URL
58–63	<img> load
64–69	<canvas> raster
70	getImageData
72–73	revokeObjectURL (finally)
80–92	registerMapIcons

See also

• src/components/map/MapCanvas.tsx — caller / map style configuration
• core/elements/derive — sets properties.icon per entity
• maplibre-gl addImage documentation
• react-icons (fa6 / bs / pi)

Contributors

kent

Changelog

Last edited 4 minutes ago

View full history

8d55547-test(e2e): run the full playwright suite