All integrations MapLibre Leaflet OpenLayers React Vue Svelte Angular React Native WordPress Webflow Squarespace Wix Shopify API docs

ExpressMaps in Vue

A small Vue 3 component around MapLibre GL JS, written with the Composition API and <script setup>. No wrapper library and no token; the component below produces the map you see here.

1. Install MapLibre GL JS

The examples are for MapLibre GL JS 6, the current major version, built with Vite (the default for npm create vue@latest and for Nuxt).

npm install maplibre-gl

Put your key in .env. Create one in the console.

VITE_EXPRESSMAPS_KEY=YOUR_API_KEY

2. The map component

Create the map in onMounted, when the container element exists, and remove it in onBeforeUnmount. Keep the map in a plain variable rather than a ref: MapLibre objects should not be wrapped in Vue's reactive proxies.

<!-- src/components/ExpressMap.vue -->
<script setup>
import { onMounted, onBeforeUnmount, useTemplateRef, watch } from "vue";
import { Map, Marker, NavigationControl, Popup, setWorkerUrl } from "maplibre-gl";
import "maplibre-gl/dist/maplibre-gl.css";
import workerUrl from "maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url";

const KEY = import.meta.env.VITE_EXPRESSMAPS_KEY;
const styleUrl = (id) => `https://tiles.expressmaps.com/styles/${id}.json?key=${KEY}`;

const {
  mapStyle = "standard",
  center = [-0.1276, 51.5072],
  zoom = 12,
  popup = ""
} = defineProps({ mapStyle: String, center: Array, zoom: Number, popup: String });

const container = useTemplateRef("container");
let map = null;

onMounted(() => {
  setWorkerUrl(workerUrl);
  map = new Map({ container: container.value, style: styleUrl(mapStyle), center, zoom });
  map.addControl(new NavigationControl(), "top-right");

  const marker = new Marker().setLngLat(center).addTo(map);
  if (popup) marker.setPopup(new Popup().setText(popup));
});

watch(() => mapStyle, (id) => map?.setStyle(styleUrl(id)));

onBeforeUnmount(() => {
  map?.remove();
  map = null;
});
</script>

<template>
  <div ref="container" class="express-map"></div>
</template>

<style scoped>
.express-map { width: 100%; height: 400px; }
</style>

Use it anywhere:

<ExpressMap :center="[-0.1276, 51.5072]" :zoom="12" popup="Our office" />

The worker import is MapLibre's documented Vite setup for version 6: the library runs tile parsing in a web worker, and setWorkerUrl tells it where the bundled worker file is. Without it no tiles are drawn. On MapLibre 5 or earlier, leave out the worker lines.

Markers, popups and your own data

After the map is created you are writing ordinary MapLibre code. Add GeoJSON layers inside the load event, inside onMounted. MapLibre uses [lng, lat] order.

map.on("load", () => {
  map.addSource("stores", { type: "geojson", data: "/stores.geojson" });
  map.addLayer({
    id: "stores",
    type: "circle",
    source: "stores",
    paint: { "circle-radius": 6, "circle-color": "#1a73e8", "circle-stroke-width": 2, "circle-stroke-color": "#fff" }
  });
  map.on("click", "stores", (e) => {
    new Popup().setLngLat(e.lngLat).setText(e.features[0].properties.name).addTo(map);
  });
});

Switching style

The component above watches its mapStyle prop, so <ExpressMap :map-style="dark ? 'darklands' : 'standard'" /> follows your app's dark mode. Any of the ten styles work: standard, basic, enhanced, darklands, greyscale, navigator, subtle, autobahn, lithium and mulberry.

map.setStyle() replaces the whole style, including layers you added yourself. If you add your own layers and want a style picker, the optional expressmaps package has a StyleSwitcher control that carries your sources and layers across to the new style, and a createMap() helper that replaces most of the setup:

npm install expressmaps maplibre-gl
import * as maplibregl from "maplibre-gl";
import { createMap, StyleSwitcher } from "expressmaps";
import "expressmaps/expressmaps.css";

onMounted(() => {
  maplibregl.setWorkerUrl(workerUrl);
  map = createMap({
    maplibregl,
    container: container.value,
    key: KEY,
    style: "standard",
    center: [-0.1276, 51.5072],
    zoom: 12,
    marker: { popup: "Our office" }
  });
  map.addControl(new StyleSwitcher({ key: KEY, styles: ["standard", "subtle", "darklands"] }), "top-left");
});

Nuxt and server-side rendering

MapLibre needs a browser and WebGL, so the map must only be created on the client. onMounted never runs on the server, which covers the map itself; to keep the whole component out of the server render, name the file ExpressMap.client.vue, or wrap it where you use it:

<ClientOnly>
  <ExpressMap popup="Our office" />
  <template #fallback><div style="height: 400px"></div></template>
</ClientOnly>

The fallback keeps the page from jumping when the map appears. In Nuxt, read the key from runtime config instead of import.meta.env:

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: { public: { expressmapsKey: "" } } // set NUXT_PUBLIC_EXPRESSMAPS_KEY
});

// in the component
const KEY = useRuntimeConfig().public.expressmapsKey;

Nuxt builds with Vite, so the same ?worker&url import works unchanged.

Things to know

  • The key ends up in your client bundle, which is normal for web maps. Restrict it to your domains in the console; requests from other sites are refused.
  • One map load is counted each time the map is created. Switching style on an existing map does not count as another load, and panning and zooming are free. Unmounting and remounting the component (for example with v-if or when changing route) counts again, so use v-show or <KeepAlive> if the map is toggled often.
  • The free plan includes 100,000 map loads a month.
  • Keep the attribution control on. The OpenStreetMap credit comes from the style and is required by the data licence.
  • Wrapper libraries such as vue-maplibre-gl exist if you prefer declarative components; they take the same style URL.

New to MapLibre? The MapLibre GL JS guide covers the map API in more detail. Sign up for a free API key to get started.

Get a free API key MapLibre guide