🗺️ Vue-Leaflet v2 Wrapper

A modern Vue 3 wrapper for Leaflet v2-alpha, based on vue-leaflet/vue-leaflet. Built with the Composition API, fully SSR-compatible, and designed for future extensibility.

⚠️ This is a Beta version and may be unstable. Contributions, feedback, and bug reports are welcome via issues or discussions.

✅ Fully compatible with SSR (tested in Nuxt playground)

🚀 What's New

• ✅ Leaflet v2-alpha support
• ✅ Refactored with Vue 3 Composition API
• ✅ SSR compatibility without useGlobalLeaflet
• ✅ >95% test coverage
• ✅ Improved documentation (vue-leaflet-docs)
• ✅ Component playground for live demos
• ✅ Plugin support via vue-leaflet-plugins

✅ Available Components

☑️ LCircle
☑️ LCircleMarker
☑️ LControl
☑️ LControlAttribution
☑️ LControlLayers
☑️ LControlScale
☑️ LControlZoom
☑️ LFeatureGroup
☑️ LGeoJson
☑️ LIcon
☑️ LImageOverlay
☑️ LMap
☑️ LMarker
☑️ LPolygon
☑️ LPolyline
☑️ LPopup
☑️ LRectangle
☑️ LSVGOverlay
☑️ LTileLayer
☑️ LTooltip
☑️ LVideoOverlay
☑️ LWmsTileLayer

🔌 Plugin Support

Leaflet plugins compatible with version 2 can be seamlessly integrated using a dedicated wrapper:
👉 vue-leaflet-plugins

Explore the documentation to see which plugins are already supported and learn how to build your own wrappers for additional functionality.

The first plugin has already been implemented. If you need support for a specific plugin, open an issue in the plugin repo and help shape the roadmap.

⚠️ Important: Leaflet v1 plugins are not compatible with Leaflet v2 and cannot be used directly. To use a plugin with v2, it must be ported and wrapped appropriately.
However, there is a possibility to use the Leaflet-V1-polyfill. Check out the vue-leaflet-plugins wrapper for more.

📦 Installation

pnpm add @maxel01/vue-leaflet [email protected]
# or
yarn add @maxel01/vue-leaflet [email protected]
# or
npm i @maxel01/vue-leaflet [email protected]

🧑‍💻 Usage

Check out the full documentation at vue-leaflet-docs or explore the playground.

Most props mirror the vanilla Leaflet options for a familiar experience.

⚡ Quickstart

<script setup>
import 'leaflet/dist/leaflet.css'
import { LMap, LTileLayer } from '@maxel01/vue-leaflet'
import { ref } from 'vue'

const zoom = ref(2)
</script>

<template>
  <div style="height:600px; width:800px">
    <LMap v-model:zoom="zoom" :center="[47.41322, -1.219482]">
      <LTileLayer
        url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"
        layer-type="base"
        name="OpenStreetMap"
      />
    </LMap>
  </div>
</template>

🧪 Interactive Playground

Unlock the full potential of vue-leaflet with interactive demo components built right into the official documentation. The playground lets you explore real-world examples, experiment with features live, and see how everything fits together.

Want to test Server-Side Rendering (SSR)? Dive into the Nuxt playground for a hands-on SSR experience.

To run the Nuxt Playground locally:

git clone https://github.com/maxel01/vue-leaflet.git
cd vue-leaflet
pnpm install
pnpm dev

Visit: http://127.0.0.1:3000

Or use the Vue-specific playground:

pnpm dev:vue

Visit: http://127.0.0.1:5173

🛠 Contribution

This repo uses pnpm for building and development.

📘 How to install PNPM

See the contribution guide for more.

🙌 Credits

• vue-leaflet/vue-leaflet
• nuxt-modules/leaflet