MapLibre GL JS

MapLibre GL JS is an open-source WebGL renderer for interactive vector maps. It renders the map and handles interaction; you choose the style, tile source, attribution, geocoding, and routing services separately.

Nuxt Scripts supports MapLibre GL JS 5.24 through the useScriptMapLibre() composable and declarative components for common map resources. First-party mode can bundle the JavaScript SDK. Nuxt Scripts loads the required MapLibre stylesheet separately by default.

Setup

Install MapLibre for its TypeScript definitions, then enable the registry entry:

pnpm add -D maplibre-gl

export default defineNuxtConfig({
  scripts: {
    registry: {
      maplibre: { trigger: false },
    },
  },
})

Quick Start

Pass a MapLibre style URL or an inline style specification. This example uses OpenFreeMap's keyless Liberty style.

<script setup lang="ts">
import type { LngLatLike } from 'maplibre-gl'

const center = ref<LngLatLike>([144.9631, -37.8136])
</script>

<template>
  <ScriptMapLibreMap
    v-model:center="center"
    map-style="https://tiles.openfreemap.org/styles/liberty"
    :zoom="12"
    width="100%"
    :height="480"
    aria-label="Map of central Melbourne"
  >
    <template #description>
      Interactive street map centred on Melbourne CBD.
    </template>

    <ScriptMapLibreNavigationControl position="top-right" />

    <ScriptMapLibreMarker
      :position="center"
      aria-label="Melbourne CBD"
    >
      <ScriptMapLibrePopup>
        Melbourne CBD
      </ScriptMapLibrePopup>
    </ScriptMapLibreMarker>
  </ScriptMapLibreMap>
</template>

MapLibre coordinates use [longitude, latitude] order. This is the reverse of the [latitude, longitude] convention used by Leaflet.

The default visible trigger defers the SDK, style, and tile requests until the map approaches the viewport. The component reserves its dimensions during SSR to avoid layout shift.

Components

• <ScriptMapLibreMap> creates the map and controls lazy loading.
• <ScriptMapLibreMarker> adds an accessible, reactive marker.
• <ScriptMapLibrePopup> binds slotted HTML to a marker or coordinate.
• <ScriptMapLibreNavigationControl> adds zoom, compass, and pitch controls.
• <ScriptMapLibreGeoJson> manages a GeoJSON source and its style layers.

Guides

• Delivery Tracker builds a practical route tracker from reactive markers and styled GeoJSON.
• Styles & Providers separates the renderer, style, tile service, and map data choices.
• Performance, CSP & Accessibility covers loading triggers, WebGL fallbacks, workers, and decorative maps.