{"id":15912,"library":"vue-maplibre-gl","title":"Vue 3 Plugin for MapLibre GL JS","description":"Vue-MapLibre-GL is a small, actively maintained Vue 3 plugin that provides components and utilities for integrating MapLibre GL JS into Vue applications. The current stable version is 5.6.1, with minor releases occurring frequently, indicating active development and responsiveness to bug fixes and feature enhancements. Key differentiators include full TypeScript support, a comprehensive set of Vue components for managing maps, controls, sources, markers, and layers, and a built-in 'Simple Draw Control' that allows users to draw polygons, circles, and static circles. It also features support for multiple map instances via the `useMap` composition API hook, customizable style switching, language toggling, and automatic map restart on `CONTEXT_LOST_WEBGL` events, which is particularly useful for mobile device stability.","status":"active","version":"5.6.1","language":"javascript","source_language":"en","source_url":"https://github.com/razorness/vue-maplibre-gl","tags":["javascript","vue","vue3","vuejs","vue3js","component","vue-component","vue3-component","maplibre","typescript"],"install":[{"cmd":"npm install vue-maplibre-gl","lang":"bash","label":"npm"},{"cmd":"yarn add vue-maplibre-gl","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-maplibre-gl","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core mapping library required for rendering maps and geographical data. This package provides the Vue 3 component wrappers and utilities around it.","package":"maplibre-gl","optional":false},{"reason":"A tiny event emitter library used internally for inter-component communication and event management within the Vue-MapLibre-GL plugin.","package":"mitt","optional":false},{"reason":"The core Vue 3 framework on which this plugin is built. Required for all Vue applications using this library.","package":"vue","optional":false},{"reason":"The Draw Plugin feature relies on various modules from the Turf.js library for geospatial analysis (e.g., polygon operations, circle calculations). While not a direct peer dependency, it is a runtime dependency if the drawing capabilities are utilized.","package":"@turf/turf","optional":true}],"imports":[{"note":"This is the default export used for global installation via `app.use(VueMaplibreGl)` in your main Vue application file.","wrong":"const VueMaplibreGl = require('vue-maplibre-gl')","symbol":"VueMaplibreGl","correct":"import VueMaplibreGl from 'vue-maplibre-gl'"},{"note":"Used for importing individual components like `MglMap` when not using the global plugin installation. Other components like `MglNavigationControl` are imported similarly.","wrong":"import MglMap from 'vue-maplibre-gl'","symbol":"MglMap","correct":"import { MglMap } from 'vue-maplibre-gl'"},{"note":"A Vue Composition API hook for accessing registered map instances by a provided key, enabling interaction with multiple maps or global map access.","wrong":"VueMaplibreGl.useMap()","symbol":"useMap","correct":"import { useMap } from 'vue-maplibre-gl'"}],"quickstart":{"code":"import { createApp } from 'vue';\nimport { MglMap, MglNavigationControl } from 'vue-maplibre-gl';\nimport 'maplibre-gl/dist/maplibre-gl.css';\nimport 'vue-maplibre-gl/dist/vue-maplibre-gl.css';\n// import 'vue-maplibre-gl/dist/vue-maplibre-gl-draw.css'; // Uncomment if using MglDrawControl\n\nconst app = createApp({\n components: {\n MglMap,\n MglNavigationControl,\n },\n data() {\n return {\n mapStyle: 'https://demotiles.maplibre.org/style.json', // Or any other MapLibre GL compatible style URL\n center: [-74.0060, 40.7128], // New York City coordinates\n zoom: 10,\n };\n },\n template: `\n
\n \n \n \n
\n `,\n});\n\napp.mount('#app');","lang":"typescript","description":"This quickstart demonstrates how to set up a basic MapLibre GL map within a Vue 3 application, including a navigation control. It shows the necessary imports for CSS and Vue components, and initializes the map with a default style and view."},"warnings":[{"fix":"Manually install required Turf.js modules, e.g., `npm install @turf/turf` or specific `@turf/*` packages if you only need certain functionalities.","message":"When using the `MglDrawControl` component, additional dependencies from Turf.js are required at runtime. These are not always listed as explicit peer dependencies and must be installed separately to avoid runtime errors related to missing geospatial functions.","severity":"gotcha","affected_versions":">=5.0.0"},{"fix":"Add `@use '~vue-maplibre-gl/dist/vue-maplibre-gl-draw.css';` to your CSS or `import 'vue-maplibre-gl/dist/vue-maplibre-gl-draw.css';` in your JavaScript entry point.","message":"The Draw Plugin CSS (`vue-maplibre-gl-draw.css`) must be explicitly imported if you intend to use the `MglDrawControl` component. The base `vue-maplibre-gl.css` only provides styles for the core map and controls.","severity":"gotcha","affected_versions":">=5.0.0"},{"fix":"Always check the `maplibre-gl` changelog for breaking changes when updating. Ensure your `maplibre-gl` peer dependency range is conservative (e.g., `^5.0.0`) to prevent automatic major version upgrades without review. Test your application thoroughly after any `maplibre-gl` update.","message":"While not explicitly documented in the `vue-maplibre-gl` changelog, a major version bump in the underlying `maplibre-gl` library (e.g., from v5 to v6) could introduce breaking changes that might affect `vue-maplibre-gl`'s functionality or require updates to map styles or data handling.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Account for potential map reloads in your application state management, especially if you store map-related settings (e.g., drawn features, current view) that might need to be reapplied after a context loss and restart.","message":"The library automatically restarts the map on `CONTEXT_LOST_WEBGL` events, which commonly occur on mobile devices when a tab is in the background for an extended period. While a feature to improve reliability, developers should be aware that this can lead to temporary map reinitialization.","severity":"gotcha","affected_versions":">=5.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Install the `maplibre-gl` package: `npm install maplibre-gl` or `yarn add maplibre-gl`.","cause":"The `maplibre-gl` package, a peer dependency, has not been installed.","error":"Cannot find module 'maplibre-gl' or its corresponding type declarations."},{"fix":"Ensure `import { MglMap } from 'vue-maplibre-gl'` is present and `MglMap` is listed in the `components` object of your Vue component, or perform a global installation using `app.use(VueMaplibreGl)` in your main.js/ts file.","cause":"The `MglMap` component (or other `Mgl` components) has not been correctly registered globally via `app.use(VueMaplibreGl)` or locally imported and added to the `components` option of a Vue component.","error":"Failed to resolve component: MglMap"},{"fix":"Ensure controls are instantiated and added within the context of an `MglMap` component or its `map` instance, typically after the map `load` event. Use `Mgl*Control` components provided by `vue-maplibre-gl` for easier integration.","cause":"Attempting to use a MapLibre GL JS control (e.g., `NavigationControl`) without initializing it or adding it to an `MglMap` instance correctly. This might also happen if the map instance is not yet ready.","error":"TypeError: Cannot read properties of undefined (reading 'addControl')"}],"ecosystem":"npm"}