Vue3 MapLibre GL

The most comprehensive Vue 3 library for MapLibre GL JS - Build interactive maps with 10+ components and 15+ composables

A powerful, feature-rich Vue 3 component library that provides an intuitive, reactive way to build interactive maps in your Vue applications using MapLibre GL JS.

✨ Features

• 🗺️ Interactive Maps - High-performance vector maps with WebGL rendering
• 🧩 10+ Vue Components - Mapbox, GeoJsonSource, FillLayer, CircleLayer, LineLayer, SymbolLayer, Marker, PopUp, Image, GeolocateControls
• 🔧 15+ Composables - Complete map management, animations, events, and utilities
• 🎯 Full TypeScript Support - Comprehensive type definitions and interfaces
• ⚡ High Performance - Optimized rendering with automatic resource cleanup
• 📱 Mobile-Friendly - Touch controls and responsive design for all devices
• 🌐 Self-Contained - Bundled CSS and automatic dependency management
• 🔄 Reactive Data Binding - Seamless integration with Vue 3's reactivity system

📦 Installation

Using Yarn (Recommended)

yarn add vue3-maplibre-gl

Using npm

npm install vue3-maplibre-gl

Using pnpm

pnpm add vue3-maplibre-gl

🚀 Quick Start

<template>
  <Mapbox :options="mapOptions" style="height: 500px" @load="onMapLoad">
    <!-- GeoJSON Data Source -->
    <GeoJsonSource :data="geoJsonData">
      <FillLayer :style="fillStyle" />
      <CircleLayer :style="circleStyle" />
    </GeoJsonSource>

    <!-- Interactive Marker -->
    <Marker :lnglat="[0, 0]" :draggable="true">
      <div class="marker">📍</div>
    </Marker>

    <!-- Popup -->
    <PopUp :lnglat="[0, 0]" :show="true">
      <div class="popup-content">
        <h3>Welcome to Vue3 MapLibre GL!</h3>
        <p>Interactive maps made easy with Vue 3</p>
      </div>
    </PopUp>

    <!-- Geolocation Control -->
    <GeolocateControls position="top-right" />
  </Mapbox>
</template>

<script setup>
import { ref } from 'vue';
import {
  Mapbox,
  GeoJsonSource,
  FillLayer,
  CircleLayer,
  Marker,
  PopUp,
  GeolocateControls,
} from 'vue3-maplibre-gl';
import 'vue3-maplibre-gl/dist/style.css';

const mapOptions = ref({
  style: 'https://demotiles.maplibre.org/style.json',
  center: [0, 0],
  zoom: 2,
});

const geoJsonData = ref({
  type: 'FeatureCollection',
  features: [
    {
      type: 'Feature',
      geometry: { type: 'Point', coordinates: [0, 0] },
      properties: { name: 'Sample Point' },
    },
  ],
});

const fillStyle = ref({
  'fill-color': '#088',
  'fill-opacity': 0.8,
});

const circleStyle = ref({
  'circle-radius': 6,
  'circle-color': '#007cbf',
});

function onMapLoad(map) {
  console.log('Map loaded:', map);
}
</script>

<style>
.marker {
  font-size: 24px;
  cursor: pointer;
}

.popup-content {
  padding: 10px;
  max-width: 200px;
}
</style>

🧩 Components

Vue3 MapLibre GL provides 10+ reactive Vue components:

Component	Description
Mapbox	Main map container with comprehensive event handling
GeoJsonSource	Reactive data source for GeoJSON data with clustering support
FillLayer	Render filled polygons with customizable styling
CircleLayer	Display point data as circles with dynamic sizing
LineLayer	Render linear features like routes and boundaries
SymbolLayer	Display icons and text labels
Marker	HTML markers with drag support and custom content
PopUp	Interactive popup windows with custom HTML
Image	Manage and load images for map styles
GeolocateControls	User location tracking with comprehensive events

🔧 Composables

15+ powerful composables for advanced map functionality:

Map Management

• useCreateMapbox - Enhanced map creation with error handling
• useMapbox - Simplified map state management

Layer Management

• useCreateFillLayer - Fill layer creation and management
• useCreateCircleLayer - Circle layer for point visualization
• useCreateLineLayer - Line layer for linear features
• useCreateSymbolLayer - Symbol layer for icons and text

Source Management

• useCreateGeoJsonSource - GeoJSON source with reactive data
• useGeoJsonSource - Simplified source management

Controls

• useGeolocateControl - User location tracking

Events

• useMapEventListener - Map event handling
• useLayerEventListener - Layer-specific events

Utilities

• useFlyTo - Smooth map animations
• useEaseTo - Easing animations
• useJumpTo - Instant position changes
• useBounds - Bounds management
• useZoom - Zoom controls
• useLogger - Consistent logging

🎯 TypeScript Support

Vue3 MapLibre GL includes comprehensive TypeScript support:

import { ref } from 'vue';
import {
  Mapbox,
  GeoJsonSource,
  FillLayer,
  type MapboxProps,
  type FillLayerStyle,
  type GeoJSONSourceSpecification,
} from 'vue3-maplibre-gl';

const mapOptions = ref<MapboxProps['options']>({
  style: 'https://demotiles.maplibre.org/style.json',
  center: [0, 0],
  zoom: 2,
});

const fillStyle = ref<FillLayerStyle>({
  'fill-color': '#088',
  'fill-opacity': 0.8,
});

const geoJsonData = ref<GeoJSONSourceSpecification['data']>({
  type: 'FeatureCollection',
  features: [],
});

🌟 Advanced Example with Composables

<script setup>
import { ref } from 'vue';
import {
  useCreateMapbox,
  useFlyTo,
  useMapEventListener,
  useCreateGeoJsonSource,
} from 'vue3-maplibre-gl';

const mapContainer = ref();
const mapStyle = ref('https://demotiles.maplibre.org/style.json');

// Create map with enhanced error handling
const { mapInstance, setCenter, setZoom } = useCreateMapbox(
  mapContainer,
  mapStyle,
  {
    onLoad: (map) => console.log('Map loaded:', map),
    onError: (error) => console.error('Map error:', error),
    debug: true,
  },
);

// Add smooth animations
const { flyTo } = useFlyTo({ map: mapInstance });

// Create reactive data source
const { setData } = useCreateGeoJsonSource({
  map: mapInstance,
  id: 'my-source',
  data: { type: 'FeatureCollection', features: [] },
});

// Listen to map events
useMapEventListener({
  map: mapInstance,
  event: 'click',
  handler: (event) => {
    flyTo({
      center: event.lngLat,
      zoom: 12,
      duration: 2000,
    });
  },
});
</script>

📚 Documentation

• Getting Started - Learn the basics and see examples
• Installation Guide - Detailed setup instructions
• Configuration - Advanced configuration options
• Components API - Complete component documentation
• Composables API - Composables reference
• TypeScript Types - Type definitions
• Live Examples - Interactive demos

🛠️ Development

# Clone the repository
git clone https://github.com/danh121097/vue-mapbox-gl.git
cd vue-mapbox-gl

# Install dependencies
yarn install

# Start development server
yarn dev

# Build the library
yarn build

# Run documentation
yarn docs:dev

🌟 Why Choose Vue3 MapLibre GL?

• 🎯 Vue 3 Native - Built specifically for Vue 3 with Composition API support
• 🗺️ MapLibre GL JS - Uses the open-source MapLibre GL JS for high-performance rendering
• 🧩 Component-Based - 10+ Vue components for maps, layers, sources, markers, and controls
• 🔧 Powerful Composables - 15+ composables for map management, animations, and utilities
• 📚 Comprehensive Documentation - Detailed guides, API references, and examples
• ⚡ High Performance - Optimized for performance with automatic resource cleanup
• 🌐 Open Source - MIT licensed with active community support
• 📱 Mobile Ready - Touch-friendly controls and responsive design

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

# Clone the repository
git clone https://github.com/danh121097/vue-mapbox-gl.git
cd vue-mapbox-gl

# Install dependencies
yarn install

# Start development server
yarn dev

# Run tests
yarn test

# Build the library
yarn build

# Run documentation
yarn docs:dev

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built on top of MapLibre GL JS - The open-source mapping library
• Inspired by the Vue.js ecosystem and community
• Thanks to all contributors and users who make this project better

📞 Support

• 📖 Documentation - Comprehensive guides and API reference
• 🐛 Issues - Bug reports and feature requests
• 💬 Discussions - Community discussions and questions
• ⭐ GitHub - Star the project if you find it useful!

---

Made with ❤️ for the Vue.js community