MapMetrics Atlas API Docs

Appearance

Render World Copies ​

Control whether the world tiles repeatedly when the map is zoomed out using renderWorldCopies.

renderWorldCopies ​

When true (the default), the map tiles the world horizontally so there are no empty areas when panned past the antimeridian. When false, only a single copy of the world is rendered.

javascript
// Enable world copies (default)
const map = new mapmetricsgl.Map({
  container: 'map',
  style: '<StyleFile_URL_with_Token>',
  renderWorldCopies: true,
});

// Disable world copies
const map = new mapmetricsgl.Map({
  container: 'map',
  style: '<StyleFile_URL_with_Token>',
  renderWorldCopies: false,
});

Toggle at Runtime ​

javascript
// Enable
map.setRenderWorldCopies(true);

// Disable
map.setRenderWorldCopies(false);

// Check current value
const isEnabled = map.getRenderWorldCopies(); // boolean

When to Disable World Copies ​

Use caseRecommended
General purpose mapstrue (default)
Globe/world overview mapstrue
Regional maps (single country/city)false
Preventing data duplication in world-spanning queriesfalse
Story maps with fixed boundsfalse

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>
    <button id="on">World Copies ON</button>
    <button id="off">World Copies OFF</button>
    <script>
      const map = new mapmetricsgl.Map({
        container: 'map',
        style: '<StyleFile_URL_with_Token>',
        center: [0, 20],
        zoom: 0.5,
        renderWorldCopies: true,
      });

      document.getElementById('on').addEventListener('click', () => map.setRenderWorldCopies(true));
      document.getElementById('off').addEventListener('click', () => map.setRenderWorldCopies(false));
    </script>
  </body>
</html>
jsx
import React, { useEffect, useRef, useState } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';

const RenderWorldCopies = () => {
  const mapContainer = useRef(null);
  const map = useRef(null);
  const [copies, setCopies] = useState(true);

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

  const toggle = (value) => {
    map.current?.setRenderWorldCopies(value);
    setCopies(value);
  };

  return (
    <div>
      <div ref={mapContainer} style={{ height: '500px', width: '100%' }} />
      <div style={{ marginTop: 10, display: 'flex', gap: 8 }}>
        <button onClick={() => toggle(true)} style={{ background: copies ? '#3b82f6' : '#6b7280', color: 'white', border: 'none', padding: '8px 16px', borderRadius: 6, cursor: 'pointer' }}>
          World Copies ON
        </button>
        <button onClick={() => toggle(false)} style={{ background: !copies ? '#ef4444' : '#6b7280', color: 'white', border: 'none', padding: '8px 16px', borderRadius: 6, cursor: 'pointer' }}>
          World Copies OFF
        </button>
      </div>
    </div>
  );
};

export default RenderWorldCopies;

For more information, visit the MapMetrics GitHub repository.