React Map Template: MapLibre GL, Leaflet and OpenLayers

This template shows how to add a Geoapify map to a React app. The steps start from a small Vite + React 19 project and add the map library of your choice: MapLibre GL for vector maps, Leaflet or react-leaflet for raster tiles, or OpenLayers. Building with react-leaflet? Follow the React Leaflet tutorial with custom markers and a route.

Tested on 2026-10-26 with Node 24, Vite 8.3, React 19.3, maplibre-gl 6.16, leaflet 1.9.4, react-leaflet 5.0, ol 10.11 and ol-mapbox-style 13.8.

React-based project on GitHub

We've prepared a React project skeleton for you. Use it as a starting point for a map application or as a code sample:

github.com/geoapify/react-based-project

Build and run the application

1. Clone or download the source code of the application to your computer.
2. Install Node.js 20.19+ or 22.12+.
3. Go to the application directory.
4. Copy .env.example to .env.local and replace YOUR_API_KEY with your Geoapify API key. The file is ignored by git, so the key isn't committed:

VITE_GEOAPIFY_API_KEY=YOUR_API_KEY

5. Run the commands:

npm install
npm run dev

6. Open http://localhost:5173 to view it in the browser. The page reloads automatically when you change the code.

The page shows only one phrase, "The map will be displayed here". Replace it with a map: change src/components/my-map.jsx as shown in the samples below.

Starting from scratch instead? Create the same kind of project with npm create vite@latest my-map -- --template react, add a src/components/my-map.jsx component and give the map container a height, for example .map-container { width: 100%; height: 100vh; }.

Geoapify Map Tiles

Geoapify map styles follow the MapLibre (Mapbox) style specification, which defines what data a map draws, in which order and how. Raster tiles are available for every style too.

Visit the Map Tiles documentation page to get a map style link for a map.

Geoapify API key

You need a Geoapify API key to display a map. Register and get an API key for free on Geoapify MyProjects. We have a Freemium pricing model: start for free and upgrade when you need more.

Text editor

You can use any code editor. We recommend Visual Studio Code.

Display a map with MapLibre GL (an open-source fork of Mapbox GL)

MapLibre GL JS is the open-source fork of Mapbox GL JS (Mapbox GL 2.0 and later are under a proprietary license). It renders Geoapify vector map styles.

1. Go to the application directory.
2. Run the command to install the MapLibre GL library:

npm i maplibre-gl

3. Replace the code of src/components/my-map.jsx:

import { useEffect, useRef } from 'react';
import * as maplibregl from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';
import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?url';
import './my-map.css';

// MapLibre GL 6 loads its web worker from a separate file; this lets Vite serve it
maplibregl.setWorkerUrl(workerUrl);

const apiKey = import.meta.env.VITE_GEOAPIFY_API_KEY;
const mapStyle = 'https://maps.geoapify.com/v1/styles/osm-bright/style.json';

export default function MyMap() {
  const mapContainer = useRef(null);

  useEffect(() => {
    const map = new maplibregl.Map({
      container: mapContainer.current,
      style: `${mapStyle}?apiKey=${apiKey}`,
      center: [11, 49], // [longitude, latitude]
      zoom: 4
    });
    map.addControl(new maplibregl.NavigationControl());

    // remove the map when the component unmounts (and on React StrictMode's second mount)
    return () => map.remove();
  }, []);

  return <div ref={mapContainer} className="map-container" />;
}

4. Set your API key in .env.local (VITE_GEOAPIFY_API_KEY). Get one on Geoapify MyProjects.
5. Change mapStyle to the map style you want to use.

Display a map with Leaflet

Leaflet doesn't support vector map tiles natively, so this sample uses Geoapify raster map tiles. For sharp maps on high-resolution (retina) screens, request tiles with the @2x suffix.

1. Go to the application directory.
2. Run the command to install the Leaflet library:

npm i leaflet

3. Replace the code of src/components/my-map.jsx:

import { useEffect, useRef } from 'react';
import L from 'leaflet';
import 'leaflet/dist/leaflet.css';
import './my-map.css';

const apiKey = import.meta.env.VITE_GEOAPIFY_API_KEY;
const mapStyle = 'osm-bright';

export default function MyMap() {
  const mapContainer = useRef(null);

  useEffect(() => {
    const map = L.map(mapContainer.current).setView([49, 11], 4); // [latitude, longitude]
    const retina = L.Browser.retina ? '@2x' : '';

    L.tileLayer(`https://maps.geoapify.com/v1/tile/${mapStyle}/{z}/{x}/{y}${retina}.png?apiKey=${apiKey}`, {
      attribution: 'Powered by <a href="https://www.geoapify.com/" target="_blank">Geoapify</a> | © <a href="https://www.openstreetmap.org/copyright" target="_blank">OpenStreetMap</a> contributors',
      maxZoom: 20
    }).addTo(map);

    // remove the map when the component unmounts (and on React StrictMode's second mount)
    return () => map.remove();
  }, []);

  return <div ref={mapContainer} className="map-container" />;
}

4. Set your API key in .env.local (VITE_GEOAPIFY_API_KEY). Get one on Geoapify MyProjects.
5. Change mapStyle to the map style you want to use.

With react-leaflet

react-leaflet wraps Leaflet in React components. Version 5 requires React 19. For a step-by-step walkthrough with custom markers and a route, read the React Leaflet tutorial.

npm i leaflet react-leaflet

import { MapContainer, TileLayer } from 'react-leaflet';
import 'leaflet/dist/leaflet.css';
import './my-map.css';

const apiKey = import.meta.env.VITE_GEOAPIFY_API_KEY;
const mapStyle = 'osm-bright';
const retina = window.devicePixelRatio > 1 ? '@2x' : '';

export default function MyMap() {
  return (
    <MapContainer center={[49, 11]} zoom={4} className="map-container">
      <TileLayer
        url={`https://maps.geoapify.com/v1/tile/${mapStyle}/{z}/{x}/{y}${retina}.png?apiKey=${apiKey}`}
        attribution='Powered by <a href="https://www.geoapify.com/" target="_blank">Geoapify</a> | © <a href="https://www.openstreetmap.org/copyright" target="_blank">OpenStreetMap</a> contributors'
        maxZoom={20}
      />
    </MapContainer>
  );
}

Display a map with OpenLayers

1. Go to the application directory.
2. Run the command to install the OpenLayers library and Mapbox style support:

npm i ol ol-mapbox-style

3. Replace the code of src/components/my-map.jsx:

import { useEffect, useRef } from 'react';
import Map from 'ol/Map';
import View from 'ol/View';
import { fromLonLat } from 'ol/proj';
import { apply } from 'ol-mapbox-style';
import 'ol/ol.css';
import './my-map.css';

const apiKey = import.meta.env.VITE_GEOAPIFY_API_KEY;
const mapStyle = 'https://maps.geoapify.com/v1/styles/osm-bright/style.json';

export default function MyMap() {
  const mapContainer = useRef(null);

  useEffect(() => {
    const map = new Map({
      target: mapContainer.current,
      view: new View({ center: fromLonLat([11, 49]), zoom: 4 }) // [longitude, latitude]
    });
    apply(map, `${mapStyle}?apiKey=${apiKey}`);

    // detach the map when the component unmounts (and on React StrictMode's second mount)
    return () => map.setTarget(undefined);
  }, []);

  return <div ref={mapContainer} className="map-container" />;
}

4. Set your API key in .env.local (VITE_GEOAPIFY_API_KEY). Get one on Geoapify MyProjects.
5. Change mapStyle to the map style you want to use.