Composants

registry.unmap.dev est un registre de composants au format shadcn pour les cartes unmap. Les composants sont copiés dans votre projet, et non installés comme un paquet : vous en possédez le code et pouvez le modifier librement. Ils s'installent comme n'importe quel composant shadcn : on enregistre le registre @unmap une fois, puis on ajoute par nom. Les fichiers arrivent dans components/ui/ et lib/ à côté des vôtres, et la CLI demande avant de remplacer quoi que ce soit.

npx shadcn@latest registry add @unmap=https://registry.unmap.dev/r/{name}.json
npx shadcn@latest add @unmap/map

npx shadcn-vue@latest add https://registry.unmap.dev/r/vue/map.json

Deux voies, une par CLI, avec les mêmes éléments :

Les éléments énergie s'associent à profile="energy". Voir Énergie. legal-land-search est le jumeau LSD de well-search.

@unmap/cli crée un projet shadcn ou shadcn-vue avec les composants déjà en place :

npx @unmap/cli create mon-app --key um_live_...

La commande lance npx shadcn init (ou shadcn-vue init pour --framework nuxt et vue) avec votre gabarit et votre préréglage, enregistre @unmap, ajoute les quatre composants, écrit la clé dans le fichier d'environnement public du cadriciel et remplace la page d'accueil par une carte, une boîte de recherche et un marqueur. Passez --theme <code> depuis /create et elle demande si les marqueurs et les itinéraires prennent l'accent du thème ou le --primary de votre système de design.

npx @unmap/cli add map geocoder

add lit votre package.json pour choisir la voie, écrit lui-même l'entrée @unmap dans components.json si elle n'y est pas encore, puis délègue à la CLI shadcn. À la main, cela fait deux commandes sur React et une seule sur Vue et Nuxt :

npx shadcn@latest registry add @unmap=https://registry.unmap.dev/r/{name}.json
npx shadcn@latest add @unmap/map @unmap/geocoder @unmap/routing-panel @unmap/marker-popup

npx shadcn-vue@latest add https://registry.unmap.dev/r/vue/map.json

shadcn-vue n'a pas encore de commande registry add. Pour écrire @unmap/map plutôt qu'une URL, ajoutez le registre à components.json une fois pour toutes (unmap add le fait pour vous) :

{ "registries": { "@unmap": "https://registry.unmap.dev/r/vue/{name}.json" } }

npx shadcn-vue@latest add @unmap/map @unmap/geocoder @unmap/routing-panel @unmap/marker-popup

Chaque composant lié à la carte dépend de map-context : en ajouter un le récupère. Le géocodeur amène le Combobox officiel ; le panneau d'itinéraire amène Field, Input, Button et Alert. Prévisualisez avec --dry-run avant de toucher un fichier (shadcn accepte aussi --diff ; shadcn-vue 2.8 ne gère encore ni l'un ni l'autre, donc sur la voie Vue unmap add --dry-run se contente d'afficher ce qu'il exécuterait). npx shadcn search @unmap (ou npx shadcn-vue search @unmap, et view @unmap/map pour le détail d'un élément) liste chaque élément une fois l'espace de noms enregistré.

import { Map } from "@/components/ui/map";
import { Geocoder } from "@/components/ui/geocoder";
import { Marker, Popup } from "@/components/ui/marker-popup";
import { MAP_THEMES } from "@/lib/map-themes";
 
export default function Demo() {
  const apiKey = process.env.NEXT_PUBLIC_UNMAP_KEY!;
  return (
    <div style={{ height: 480 }}>
      <Map apiKey={apiKey} center={[-114.07, 51.05]} zoom={11} theme={MAP_THEMES.boreal} accent="system">
        <div style={{ position: "absolute", top: 12, left: 12, width: 280, zIndex: 10 }}>
          <Geocoder apiKey={apiKey} />
        </div>
        <Marker lngLat={[-114.07, 51.05]}>
          <Popup>Centre-ville de Calgary</Popup>
        </Marker>
      </Map>
    </div>
  );
}

La carte que ces composants montent est celle que construit @unmap/maps, et elle ressemble à ceci :

import { Unmap } from "@unmap/sdk";

const unmap = new Unmap({
  key: "um_live_...",
  container: "map",
  style: "base",
  mode: "light",
  lang: "fr",
  center: [-114.07, 51.05],
  zoom: 11,
});

Si vous préférez ne pas copier de composants, @unmap/react et @unmap/next fournissent la même carte sous forme de hooks et de composant prêt à l'emploi. Voir la Vue d'ensemble.

La voie Vue s'installe par shadcn-vue dans un projet qui a exécuté npx shadcn-vue init. Les fichiers arrivent un dossier par élément, chacun avec un index.ts : components/ui/map/UnmapMap.vue, geocoder/UnmapGeocoder.vue, routing-panel/UnmapRoutingPanel.vue, marker-popup/UnmapMarker.vue et UnmapPopup.vue, plus lib/map-context/index.ts, sous src/ ou le app/ de Nuxt 4 selon vos alias. L'import reste @/lib/map-context. Vous migrez depuis l'ancienne disposition à plat components/ui/Unmap*.vue ? Supprimez ces fichiers après avoir réinstallé les éléments ; les nouveaux dossiers s'installent à côté d'eux, et supprimez tout dossier lib/vue/ ou fichier plat lib/map-context.ts laissé par une installation antérieure au 2026-09-07 : un fichier plat masque le nouveau lib/map-context/index.ts.

<script setup lang="ts">
import { UnmapMap } from "@/components/ui/map";
import { UnmapGeocoder } from "@/components/ui/geocoder";
import { UnmapMarker, UnmapPopup } from "@/components/ui/marker-popup";
 
const apiKey = import.meta.env.VITE_UNMAP_KEY;
</script>
 
<template>
  <div style="height: 480px">
    <UnmapMap :api-key="apiKey" :center="[-114.07, 51.05]" :zoom="11" theme="u4e" accent="system">
      <div style="position: absolute; top: 12px; left: 12px; width: 280px; z-index: 10">
        <UnmapGeocoder :api-key="apiKey" />
      </div>
      <UnmapMarker :lng-lat="[-114.07, 51.05]">
        <UnmapPopup>Centre-ville de Calgary</UnmapPopup>
      </UnmapMarker>
    </UnmapMap>
  </div>
</template>

UnmapMap reçoit le style sous map-style ("base", "muted", "outdoor", "blueprint", "blush", "orchid", "canopy", "lagoon", "tropic", "sunset", "bold" ou "pastel") pour que l'attribut style continue de styler le conteneur ; class et style lui sont transmis. Il accepte aussi mode ("light" ou "dark") et lang ("en" ou "fr"). Les noms gardent le préfixe Unmap parce que <map> est un élément HTML. Sur Nuxt, shadcn-nuxt lit l'index.ts de chaque dossier et importe automatiquement les composants sous <UiUnmapMap>, <UiUnmapGeocoder>, etc. ; définissez shadcn: { prefix: "" } dans nuxt.config.ts pour les utiliser sous <UnmapMap>.

Pas sur shadcn-vue ? @unmap/vue et @unmap/nuxt fournissent la carte, le géocodeur et l'itinéraire sous forme de composables pour n'importe quelle interface. Voir la Vue d'ensemble.

Style et thème

Le registre ne livre ni thème ni couleur de marque. Les composants adoptent votre système de design :

• Le conteneur de carte utilise rounded-lg et bg-muted, donc il suit votre --radius et votre palette.
• Le géocodeur et le panneau d'itinéraire sont vos propres primitives shadcn.
• Les infobulles, les boutons de zoom et de boussole, l'attribution et l'échelle de MapLibre sont restylés sur --popover, --background, --border, --radius, --ring et --muted-foreground par le CSS que l'élément map ajoute à votre feuille de style à l'installation, limité à [data-unmap-map] pour laisser intactes les autres cartes de votre application ; les infobulles et les contrôles prennent la police de la page via font: inherit. Le mode sombre suit votre classe .dark.
• Les marqueurs et les lignes d'itinéraire prennent par défaut votre --primary, résolu en couleur concrète à leur création, parce que la peinture MapLibre ne lit pas var().
• Les boutons de zoom et de boussole sont activés par défaut, en haut à droite. <Map controls={false}> les retire et <Map controls={{ position: 'bottom-left' }}> les déplace.
• <Map projection="globe"> dessine la carte en sphère. Par défaut mercator, la carte plane.

La cartographie est distincte de l'interface. La propriété theme reçoit un code court comme u4e ou un code ut1. complet du compositeur de thèmes ; ce code porte ses propres couleurs de marqueur et d'itinéraire. <Map accent="theme" | "system"> dit laquelle l'emporte : "theme" par défaut quand un theme est défini, "system" sinon, et la boîte d'export de /create vous pose la question avant d'écrire l'extrait. Une propriété color ou lineColor explicite l'emporte toujours sur les deux. Voir l'API de cartes.

Chaque composant marque sa racine d'un attribut data-unmap-map, data-unmap-geocoder ou data-unmap-routing, et chaque infobulle porte la classe unmap-popup, comme points d'accroche pour votre propre CSS.

Prochaines étapes

• Parcourez chaque élément avec ses commandes d'installation sur registry.unmap.dev.
• Le Démarrage rapide pour la voie JavaScript pur avec @unmap/sdk.
• L'API de géocodage et l'API d'itinéraires pour ce que le géocodeur et le panneau d'itinéraire appellent sous le capot.
• Énergie pour energy-map, well-search, energy-popup et energy-layer-control.