MapMetrics Atlas API Docs

Appearance

Display Map Navigation Controls ​

Add built-in UI controls to your map: zoom buttons, compass, scale bar, fullscreen toggle, and geolocation.

The map includes: zoom +/− buttons (top-right), compass, scale bar (bottom-left), and fullscreen button.

Available Controls ​

ControlClassDescription
Zoom & CompassNavigationControl+/− zoom buttons and compass rose
FullscreenFullscreenControlToggle fullscreen mode
GeolocationGeolocateControlLocate the user on the map
Scale barScaleControlDistance scale indicator

Adding Controls ​

javascript
// Zoom + Compass (most common)
map.addControl(new mapmetricsgl.NavigationControl(), 'top-right');

// Fullscreen button
map.addControl(new mapmetricsgl.FullscreenControl(), 'top-right');

// Scale bar
map.addControl(new mapmetricsgl.ScaleControl({ unit: 'metric' }), 'bottom-left');

// Geolocation button
map.addControl(new mapmetricsgl.GeolocateControl({
  positionOptions: { enableHighAccuracy: true },
  trackUserLocation: true
}), 'top-right');

Control Positions ​

Controls can be placed in any of 4 corners:

javascript
map.addControl(control, 'top-left');
map.addControl(control, 'top-right');     // default
map.addControl(control, 'bottom-left');
map.addControl(control, 'bottom-right');
javascript
const nav = new mapmetricsgl.NavigationControl({
  showCompass: true,    // show compass rose (default: true)
  showZoom: true,       // show +/- zoom buttons (default: true)
  visualizePitch: true  // tilt compass icon based on pitch
});
map.addControl(nav, 'top-right');

ScaleControl Options ​

javascript
const scale = new mapmetricsgl.ScaleControl({
  maxWidth: 100,    // max width in pixels
  unit: 'metric'   // 'metric', 'imperial', or 'nautical'
});
map.addControl(scale, 'bottom-left');

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: [2.349902, 48.852966],
        zoom: 5
      });

      // Zoom + Compass
      map.addControl(new mapmetricsgl.NavigationControl(), 'top-right');

      // Fullscreen
      map.addControl(new mapmetricsgl.FullscreenControl(), 'top-right');

      // Scale bar
      map.addControl(new mapmetricsgl.ScaleControl({ unit: 'metric' }), 'bottom-left');
    </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 NavigationControls = () => {
  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: [2.349902, 48.852966],
      zoom: 5
    });

    // Zoom + Compass
    map.current.addControl(new mapmetricsgl.NavigationControl(), 'top-right');

    // Fullscreen
    map.current.addControl(new mapmetricsgl.FullscreenControl(), 'top-right');

    // Scale bar
    map.current.addControl(new mapmetricsgl.ScaleControl({ unit: 'metric' }), 'bottom-left');

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

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

export default NavigationControls;

For more information, visit the MapMetrics GitHub repository.