Registry / web-framework / vue-maplibre-gl

vue-maplibre-gl

library5.6.1jsnpmunverified

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.

web-framework http-networking

npm install vue-maplibre-gl

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VUE-MAPLIBRE-GL

vue-maplibre-gl

web-frameworkjavascriptv5.6.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

VueMaplibreGl

✓ import VueMaplibreGl from 'vue-maplibre-gl'

✗ const VueMaplibreGl = require('vue-maplibre-gl')

This is the default export used for global installation via `app.use(VueMaplibreGl)` in your main Vue application file.

MglMap

✓ import { MglMap } from 'vue-maplibre-gl'

✗ import MglMap from 'vue-maplibre-gl'

Used for importing individual components like `MglMap` when not using the global plugin installation. Other components like `MglNavigationControl` are imported similarly.

useMap

✓ import { useMap } from 'vue-maplibre-gl'

✗ VueMaplibreGl.useMap()

A Vue Composition API hook for accessing registered map instances by a provided key, enabling interaction with multiple maps or global map access.

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.

import { createApp } from 'vue'; import { MglMap, MglNavigationControl } from 'vue-maplibre-gl'; import 'maplibre-gl/dist/maplibre-gl.css'; import 'vue-maplibre-gl/dist/vue-maplibre-gl.css'; // import 'vue-maplibre-gl/dist/vue-maplibre-gl-draw.css'; // Uncomment if using MglDrawControl const app = createApp({ components: { MglMap, MglNavigationControl, }, data() { return { mapStyle: 'https://demotiles.maplibre.org/style.json', // Or any other MapLibre GL compatible style URL center: [-74.0060, 40.7128], // New York City coordinates zoom: 10, }; }, template: ` <div style="width: 100%; height: 500px;"> <mgl-map :map-style="mapStyle" :center="center" :zoom="zoom" > <mgl-navigation-control position="top-right" /> </mgl-map> </div> `, }); app.mount('#app');

Debug

Known issues

gotchaWhen 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.

fix

Manually install required Turf.js modules, e.g., `npm install @turf/turf` or specific `@turf/*` packages if you only need certain functionalities.

affects: >=5.0.0

gotchaThe 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.

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.

affects: >=5.0.0

breakingWhile 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.

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.

affects: >=5.0.0

gotchaThe 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.

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.

affects: >=5.0.0

Errors

Common errors & fixes

Cannot find module 'maplibre-gl' or its corresponding type declarations.

The `maplibre-gl` package, a peer dependency, has not been installed.

fix

Install the `maplibre-gl` package: `npm install maplibre-gl` or `yarn add maplibre-gl`.

Failed to resolve component: MglMap

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.

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.

TypeError: Cannot read properties of undefined (reading 'addControl')

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.

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.

Upgrade

Version history

5.6.1latest on npm

Audit

Dependencies

maplibre-glrequiredCore mapping library required for rendering maps and geographical data. This package provides the Vue 3 component wrappers and utilities around it.

mittrequiredA tiny event emitter library used internally for inter-component communication and event management within the Vue-MapLibre-GL plugin.

vuerequiredThe core Vue 3 framework on which this plugin is built. Required for all Vue applications using this library.

@turf/turfoptionalThe 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.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/razorness/vue-maplibre-gl ↗

packagehttps://www.npmjs.com/package/vue-maplibre-gl ↗

homepagehttps://z0h4n.github.io/vue-maplibre-gl/ ↗