MapMetrics Atlas API Docs

Appearance

React Map Integration ​

This guide shows you how to integrate MapMetrics into a React application.

Prerequisites ​

Quick Start ​

1. Create React App ​

bash
npx create-react-app my-map-app
cd my-map-app

2. Install MapMetrics GL Package ​

bash
npm install @mapmetrics/mapmetrics-gl

Package Details:

3. Create Map Component ​

Create a new file src/MapComponent.jsx:

jsx
import React, { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';

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

  useEffect(() => {
    if (map.current) return; // Initialize map only once

    // Replace with your complete style URL from MapMetrics Portal
    const YOUR_STYLE_URL = 'https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_USER_ID/YOUR_STYLE.json&token=YOUR_TOKEN';

    map.current = new mapmetricsgl.Map({
      container: mapContainer.current,
      style: YOUR_STYLE_URL,
      center: [-74.006, 40.7128], // New York City
      zoom: 12
    });

    // Add navigation controls
    map.current.addControl(new mapmetricsgl.NavigationControl(), 'top-right');

    // Cleanup on unmount
    return () => {
      if (map.current) {
        map.current.remove();
        map.current = null;
      }
    };
  }, []);

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

export default MapComponent;

4. Use Map Component in App ​

Update src/App.js:

jsx
import React from 'react';
import './App.css';
import MapComponent from './MapComponent';

function App() {
  return (
    <div className="App">
      <h1>My MapMetrics App</h1>
      <MapComponent />
    </div>
  );
}

export default App;

5. Add CSS (Optional) ​

Update src/App.css:

css
.App {
  text-align: center;
  padding: 20px;
}

h1 {
  margin-bottom: 20px;
}

6. Run Your App ​

bash
npm start

Your map should now appear at http://localhost:3000

Important Notes ​

Style URL ​

Replace YOUR_STYLE_URL with the complete URL you get from MapMetrics Portal. It should look like:

javascript
const YOUR_STYLE_URL = 'https://gateway.mapmetrics-atlas.net/styles/?fileName=753b9b14-2fcc-44d3-b273-c8b2b701647a/Bicolor.json&token=eyJhbGc...';

Package Information ​

MapMetrics GL is available on NPM:

  • ✅ Install: npm install @mapmetrics/mapmetrics-gl
  • ✅ Import: import mapmetricsgl from '@mapmetrics/mapmetrics-gl'
  • ✅ CSS: import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css'
  • 📦 NPM: @mapmetrics/mapmetrics-gl

Map Container Height ​

The map container must have a height. Set it via inline style or CSS:

jsx
// Option 1: Inline style
<div ref={mapContainer} style={{ height: '500px', width: '100%' }} />

// Option 2: CSS class
<div ref={mapContainer} className="map-container" />
css
.map-container {
  height: 500px;
  width: 100%;
}

Complete Working Example ​

Here's a complete, copy-paste ready React component:

jsx
// MapComponent.jsx
import React, { useEffect, useRef, useState } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';

const MapComponent = () => {
  const mapContainer = useRef(null);
  const map = useRef(null);
  const [lng] = useState(-74.006);
  const [lat] = useState(40.7128);
  const [zoom] = useState(12);

  useEffect(() => {
    if (map.current) return;

    // Get your complete style URL from https://portal.mapmetrics.org/
    const styleURL = 'YOUR_COMPLETE_STYLE_URL_HERE';

    map.current = new mapmetricsgl.Map({
      container: mapContainer.current,
      style: styleURL,
      center: [lng, lat],
      zoom: zoom
    });

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

    return () => {
      if (map.current) {
        map.current.remove();
        map.current = null;
      }
    };
  }, [lng, lat, zoom]);

  return (
    <div style={{ width: '100%', height: '100vh' }}>
      <div
        ref={mapContainer}
        style={{
          width: '100%',
          height: '100%'
        }}
      />
    </div>
  );
};

export default MapComponent;

Troubleshooting ​

Map doesn't load ​

  • ✅ Check that you replaced YOUR_COMPLETE_STYLE_URL_HERE with actual URL from portal
  • ✅ Verify your API token is valid
  • ✅ Check browser console for errors

Map container has no height ​

  • ✅ Add height: '500px' or height: '100vh' to container style
  • ✅ Ensure parent container also has height

npm install fails ​

Adding Features ​

Add a Marker ​

jsx
// After map initialization
const marker = new mapmetricsgl.Marker()
  .setLngLat([-74.006, 40.7128])
  .addTo(map.current);

Add a Popup ​

jsx
const popup = new mapmetricsgl.Popup()
  .setLngLat([-74.006, 40.7128])
  .setHTML('<h3>Hello World!</h3>')
  .addTo(map.current);

Handle Click Events ​

jsx
map.current.on('click', (e) => {
  console.log('Map clicked at:', e.lngLat);
});

Next Steps ​

Need Help? Join our Discord community or check more examples