vue-maplibre-gl

@indoorequal/vue-maplibre-gl is a lightweight Vue 3 plugin designed for maplibre-gl-js. It provides a component-based abstraction for working with MapLibre GL JS within Vue applications.

Key features include:

• Support for MapLibre GL JS v6.x.
• Full TypeScript support.
• Dedicated components for map instances, controls, sources, markers, popups, and layers.
• Support for custom controls.
• Support for multiple map instances with global access via the useMap(key: string | symbol) utility.
• Automatic restart handling for CONTEXT_LOST_WEBGL events (useful for mobile devices when tabs are backgrounded).
• Small bundle size.

To use the map component within a Vue Single-File Component, import MglMap from @indoorequal/vue-maplibre-gl inside your <script setup> block. Ensure you also import the MapLibre GL CSS, either in your global styles or within the component's <style> block.

<template>
  <mgl-map ... />
</template>

<script setup>
  import { MglMap } from '@indoorequal/vue-maplibre-gl';
</script>

<style lang="css">
  @import "maplibre-gl/dist/maplibre-gl.css";
</style>

You can add any native MapLibre controls by including their corresponding components as children of the <mgl-map> component.

Supported controls include:

• NavigationControl
• GeolocateControl
• AttributionControl
• FullscreenControl
• LogoControl
• ScaleControl

You can customize the placement of the control using the position prop.

<mgl-map map-style="...">
  <mgl-navigation-control position="top-left" />
</mgl-map>

The @indoorequal/vue-maplibre-gl component supports all MapLibre sources and layers. When structuring your component tree, follow these hierarchy rules:

1. Sources must be direct children of the <MapLibreMap> component.
2. Layers must be nested inside a <Source> component.

Supported source types include GeoJSON, Vector, and Video sources.

To use this library, you must install both @indoorequal/vue-maplibre-gl and maplibre-gl as peer dependencies. Use your preferred package manager to add both packages to your project.

npm install @indoorequal/vue-maplibre-gl maplibre-gl

The library provides a <mgl-custom-control> component for adding your own arbitrary HTML/UI elements to the map.

This component supports the following props:

• position: Controls where the custom control is placed on the map.
• class: Allows you to apply custom CSS classes to the control container.

Place your custom HTML content inside the component tags as a child.

<mgl-map map-style="...">
  <mgl-custom-control class="my-custom-class">
    <div>Your custom HTML code</div>
  </mgl-custom-control>
</mgl-map>

You can integrate the library into your Vue application using two primary methods:

1. Global Registration

Register all components globally by using the plugin in your main application file. This makes all components available throughout your app.

2. Specific Component Registration

If you want to reduce bundle size, you can import only the specific components you need (e.g., MglMap) and register them manually using app.component().

Note: In both cases, you must import the MapLibre GL CSS file to ensure the map renders correctly.

// Global registration
import 'maplibre-gl/dist/maplibre-gl.css';
import VueMaplibreGl from '@indoorequal/vue-maplibre-gl';
app.use(VueMaplibreGl);

// OR Specific component registration
import 'maplibre-gl/dist/maplibre-gl.css';
import { MglMap } from '@indoorequal/vue-maplibre-gl';
app.component('MglMap', MglMap);

You can install the library globally in your Vue application using app.use(). This automatically registers all available MapLibre GL components provided by the package, making them available throughout your application template.

import { createApp } from 'vue';
import vueMapLibreGl from '@indoorequal/vue-maplibre-gl';
import App from './App.vue';

const app = createApp(App);

app.use(vueMapLibreGl);

app.mount('#app');

To display a map, use the <mgl-map> component and provide a map-style prop containing the URL to a MapLibre GL style JSON.

Example usage:

<template>
  <mgl-map map-style="https://demotiles.maplibre.org/style.json" />
</template>

<script setup>
  import { MglMap } from '@indoorequal/vue-maplibre-gl';
</script>

<style lang="css">
  @import "maplibre-gl/dist/maplibre-gl.css";
</style>

The useControl composable allows you to add a MapLibre control that implements the IControl interface to the map. It accepts a factory function that returns the control instance and an optional configuration object to specify the position (e.g., 'top-left'). It returns an object containing both the created control and the map instance.

<script setup>
import { useControl } from '@indoorequal/vue-maplibre-gl';
import MaplibreInspect from '@maplibre/maplibre-gl-inspect';

// Add a control by providing a factory function
useControl(() => {
  return new MaplibreInspect();
});
</script>