Ajouter une carte à React

Les enveloppes React pour MapLibre occupent une étagère bien remplie, et la plupart reposent sur la même idée : un arbre de composants déclaratif au-dessus d'une carte impérative. unmap n'en ajoute pas une de plus. Vous obtenez l'objet carte MapLibre lui-même, et derrière lui les tuiles, le géocodage et les itinéraires sur une seule clé.

Sur Next.js, lisez plutôt Ajouter une carte à Next.js : la frontière client change la réponse.

Registre copie le composant dans votre projet, où il suit vos jetons de design et où le fichier vous appartient. Il faut un projet avec un components.json.

Paquet installe @unmap/react et vous donne des hooks, ce qui est le bon niveau quand vous placez la carte dans une interface que vous avez déjà construite.

npx @unmap/cli add map

npm i @unmap/react maplibre-gl

import { Map } from "@/components/ui/map";
 
export default function App() {
  return (
    <div className="h-dvh">
      <Map
        apiKey={import.meta.env.VITE_UNMAP_KEY as string}
        center={[-114.07, 51.05]}
        zoom={11}
        className="h-full"
      />
    </div>
  );
}

import { useUnmap } from "@unmap/react";
 
export default function App() {
  const { mapContainer } = useUnmap({
    apiKey: import.meta.env.VITE_UNMAP_KEY as string,
    center: [-114.07, 51.05],
    zoom: 11,
  });
 
  return <div ref={mapContainer} style={{ height: "100dvh" }} />;
}

Sur la voie du paquet, importez maplibre-gl/dist/maplibre-gl.css une fois dans votre fichier d'entrée. Le composant copié le fait pour vous.

useUnmap renvoie la carte elle-même, pas une façade : chaque événement, source, couche et contrôle de MapLibre reste donc disponible, que nous ayons pensé à l'exposer ou non. ready indique quand l'événement load s'est produit, soit le premier moment où vous pouvez ajouter une source.

import { useEffect } from "react";
import { useUnmap } from "@unmap/react";
 
export default function AppWithLayer() {
  const { mapContainer, map, ready } = useUnmap({
    apiKey: import.meta.env.VITE_UNMAP_KEY as string,
    center: [-114.07, 51.05],
    zoom: 11,
  });
 
  useEffect(() => {
    if (!ready || !map) return;
    map.addSource("sites", { type: "geojson", data: { type: "FeatureCollection", features: [] } });
    map.addLayer({ id: "sites", type: "circle", source: "sites" });
  }, [ready, map]);
 
  return <div ref={mapContainer} style={{ height: "100dvh" }} />;
}

mapContainer est un ref de rappel plutôt qu'un objet ref : la carte est donc créée quand l'élément apparaît vraiment. Un conteneur rendu derrière une condition ou dans un onglet fonctionne quand même.

Vite insère dans le paquet navigateur tout ce qui est préfixé VITE_. C'est correct pour une clé de carte et mérite d'être dit clairement : une clé utilisée par une carte dans un navigateur est lisible par quiconque charge la page, chez tous les fournisseurs. Restreignez-la à vos origines de production dans le tableau de bord plutôt que de tenter de la cacher.

# .env
VITE_UNMAP_KEY=um_live_...

Problèmes courants

La carte est une boîte vide. Le conteneur n'a pas de hauteur. MapLibre mesure l'élément qu'on lui donne, et un élément de zéro pixel ne signale aucune erreur.

La carte apparaît une fois puis plus jamais après un changement de route. Le conteneur a été démonté alors que le hook gardait l'ancien élément. useUnmap gère ce cas avec son ref de rappel ; une version artisanale à base de useRef ne le fait généralement pas.

Les options changent et la carte se reconstruit. Modifier center ou zoom déplace la carte existante, mais modifier autre chose la recrée. Gardez les objets d'options stables, ou sortez-les du rendu.

Pour aller plus loin

• Ajouter une carte à Next.js pour la version App Router
• Composants pour le géocodeur, le panneau d'itinéraire et les marqueurs
• Exemples pour les versions indépendantes de tout framework