Guide
Getting Started
Get started with v-maplibre in your Vue 3 or Nuxt project
Installation
Only two packages are required.
@geoql/v-maplibre keeps the install lean — deck.gl, raster, wind, LiDAR, and starfield support are all opt-in. See Optional Packages below.Install the library and its single peer dependency:
pnpm add @geoql/v-maplibre maplibre-gl
npm install @geoql/v-maplibre maplibre-gl
yarn add @geoql/v-maplibre maplibre-gl
That covers VMap, VMarker, VPopup, all controls (VControl*), and every MapLibre-native layer (VLayerMaplibre*).
Import Styles
Import the required CSS files in your main application file or component:
// main.ts or app.vue
import 'maplibre-gl/dist/maplibre-gl.css';
import '@geoql/v-maplibre/dist/v-maplibre.css';
Basic Usage
Here's a simple example to render a map:
<script setup lang="ts">
import { VMap } from '@geoql/v-maplibre';
import 'maplibre-gl/dist/maplibre-gl.css';
import '@geoql/v-maplibre/dist/v-maplibre.css';
const mapOptions = {
style: 'https://demotiles.maplibre.org/style.json',
center: [-74.5, 40],
zoom: 9,
};
</script>
<template>
<VMap :options="mapOptions" style="height: 500px"></VMap>
</template>
Nuxt Usage
For Nuxt applications, you need to configure the component to only render on the client side:
<script setup lang="ts">
import { VMap } from '@geoql/v-maplibre';
const mapOptions = {
style: 'https://demotiles.maplibre.org/style.json',
center: [-74.5, 40],
zoom: 9,
};
</script>
<template>
<ClientOnly>
<VMap :options="mapOptions" style="height: 500px"></VMap>
</ClientOnly>
</template>
Nuxt Global CSS (Recommended)
Add the styles to your nuxt.config.ts for global availability:
// nuxt.config.ts
export default defineNuxtConfig({
css: [
'maplibre-gl/dist/maplibre-gl.css',
'@geoql/v-maplibre/dist/v-maplibre.css',
],
});
Or use a Nuxt plugin:
// plugins/maplibre.client.ts
import 'maplibre-gl/dist/maplibre-gl.css';
import '@geoql/v-maplibre/dist/v-maplibre.css';
export default defineNuxtPlugin(() => {
// Plugin loaded
});
Optional Packages
Add these only for the layers you actually use. Each row's components stay tree-shaken out of your bundle until you import them:
| Feature | Components | Install |
|---|---|---|
| deck.gl base | VLayerDeckgl, VLayerDeckglScatterplot, VLayerDeckglArc, VLayerDeckglLine, VLayerDeckglPath, VLayerDeckglPolygon, VLayerDeckglSolidPolygon, VLayerDeckglGeojson, VLayerDeckglIcon, VLayerDeckglText, VLayerDeckglColumn, VLayerDeckglBitmap, VLayerDeckglPointCloud | pnpm add @deck.gl/core @deck.gl/layers @deck.gl/mapbox |
| Aggregation | VLayerDeckglHeatmap, VLayerDeckglHexagon, VLayerDeckglGrid, VLayerDeckglGridCell, VLayerDeckglContour, VLayerDeckglScreenGrid | pnpm add @deck.gl/aggregation-layers |
| Geo / tiles | VLayerDeckglTrips, VLayerDeckglMVT, VLayerDeckglTile, VLayerDeckglTile3D, VLayerDeckglTerrain, VLayerDeckglH3Hexagon, VLayerDeckglH3Cluster, VLayerDeckglS2, VLayerDeckglGeohash, VLayerDeckglQuadkey, VLayerDeckglGreatCircle, VLayerDeckglWMS | pnpm add @deck.gl/geo-layers |
| 3D mesh | VLayerDeckglSimpleMesh, VLayerDeckglScenegraph | pnpm add @deck.gl/mesh-layers |
| Raster (COG) | VLayerCog, VLayerMultiCog, VLayerMosaic | pnpm add @developmentseed/deck.gl-geotiff @developmentseed/deck.gl-raster @developmentseed/geotiff @developmentseed/proj |
| Zarr | VLayerZarr | pnpm add @developmentseed/deck.gl-zarr zarrita |
| GeoArrow | VLayerDeckglGeoArrowScatterplot, VLayerDeckglGeoArrowPath, VLayerDeckglGeoArrowPolygon, VLayerDeckglGeoArrowSolidPolygon, VLayerDeckglGeoArrowText, VLayerDeckglGeoArrowTrips | pnpm add @deck.gl/layers apache-arrow (+ @deck.gl/geo-layers for trips) |
| Wind particles | VLayerWindParticle | pnpm add maplibre-gl-wind |
| LiDAR | VControlLidar | pnpm add maplibre-gl-lidar |
| Starfield | VLayerStarfield | pnpm add @geoql/maplibre-gl-starfield three |
If you import a layer without its peer deps installed, your bundler will report Cannot find module '...' — install the missing package(s) from the row above to resolve it.