MapMetrics Atlas API Docs

Appearance

Add an Icon to the Map ​

Load an image from a URL and display it as an icon on the map using a symbol layer.

Load an Image with loadImage ​

javascript
map.on('load', () => {
  map.loadImage('https://example.com/icon.png', (error, image) => {
    if (error) throw error;

    // Register the image with a name
    map.addImage('my-icon', image);

    // Use it in a symbol layer
    map.addLayer({
      id: 'icon-layer',
      type: 'symbol',
      source: 'my-source',
      layout: {
        'icon-image': 'my-icon',
        'icon-size': 1.0,
        'icon-allow-overlap': true,
      }
    });
  });
});

Symbol Layer Icon Properties ​

javascript
map.addLayer({
  id: 'icons',
  type: 'symbol',
  source: 'points',
  layout: {
    'icon-image': 'my-icon',       // name registered with addImage()
    'icon-size': 0.5,              // scale factor (1.0 = original size)
    'icon-anchor': 'center',       // 'center', 'top', 'bottom', 'left', 'right'
    'icon-allow-overlap': true,    // show icon even if it overlaps others
    'icon-ignore-placement': true, // don't block other features
    'icon-offset': [0, -10],       // [x, y] pixel offset
  }
});

Complete Example ​

html
<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <link href="https://cdn.mapmetrics-atlas.net/versions/latest/mapmetrics-gl.css" rel="stylesheet" />
    <script src="https://cdn.mapmetrics-atlas.net/versions/latest/mapmetrics-gl.js"></script>
    <style>#map { height: 500px; width: 100%; }</style>
  </head>
  <body>
    <div id="map"></div>
    <script>
      const map = new mapmetricsgl.Map({
        container: 'map',
        style: '<StyleFile_URL_with_Token>',
        center: [0, 20],
        zoom: 1.5
      });

      map.on('load', () => {
        map.loadImage('https://example.com/icon.png', (error, image) => {
          if (error) throw error;
          map.addImage('my-icon', image);

          map.addSource('points', {
            type: 'geojson',
            data: {
              type: 'FeatureCollection',
              features: [
                { type: 'Feature', geometry: { type: 'Point', coordinates: [-74.0, 40.7] }, properties: {} },
                { type: 'Feature', geometry: { type: 'Point', coordinates: [2.35, 48.85] }, properties: {} },
              ]
            }
          });

          map.addLayer({
            id: 'icon-layer',
            type: 'symbol',
            source: 'points',
            layout: {
              'icon-image': 'my-icon',
              'icon-size': 0.5,
              'icon-allow-overlap': true,
            }
          });
        });
      });
    </script>
  </body>
</html>
jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';

const pointsData = {
  type: 'FeatureCollection',
  features: [
    { type: 'Feature', geometry: { type: 'Point', coordinates: [-74.0, 40.7] }, properties: {} },
    { type: 'Feature', geometry: { type: 'Point', coordinates: [2.35, 48.85] }, properties: {} },
    { type: 'Feature', geometry: { type: 'Point', coordinates: [139.7, 35.7] }, properties: {} },
  ]
};

const AddIconToMap = () => {
  const mapContainer = useRef(null);
  const map = useRef(null);

  useEffect(() => {
    if (map.current) return;
    map.current = new mapmetricsgl.Map({
      container: mapContainer.current,
      style: '<StyleFile_URL_with_Token>',
      center: [0, 20],
      zoom: 1.5
    });

    map.current.on('load', () => {
      map.current.loadImage('https://example.com/icon.png', (error, image) => {
        if (error) throw error;
        map.current.addImage('my-icon', image);

        map.current.addSource('points', { type: 'geojson', data: pointsData });

        map.current.addLayer({
          id: 'icon-layer',
          type: 'symbol',
          source: 'points',
          layout: {
            'icon-image': 'my-icon',
            'icon-size': 0.5,
            'icon-allow-overlap': true,
          }
        });
      });
    });

    return () => { map.current?.remove(); map.current = null; };
  }, []);

  return <div ref={mapContainer} style={{ height: '500px', width: '100%' }} />;
};

export default AddIconToMap;

For more information, visit the MapMetrics GitHub repository.