Performance, CSP & Accessibility

ScriptMapLibreMap loads near the viewport by default and reserves its configured dimensions during SSR. The SDK, stylesheet, Web Worker, style, and tiles stay off the network until the trigger runs.

Loading Strategies

Use the default visible trigger for maps below the fold:

<ScriptMapLibreMap
  :center="[144.9631, -37.8136]"
  map-style="https://tiles.openfreemap.org/styles/liberty"
/>

Load immediately when the map is the page's primary content:

<ScriptMapLibreMap
  trigger="immediate"
  :center="[144.9631, -37.8136]"
  map-style="https://tiles.openfreemap.org/styles/liberty"
/>

Always provide a height so SSR and the first client render use the same layout:

<ScriptMapLibreMap
  width="100%"
  height="clamp(24rem, 60vw, 36rem)"
  :center="[144.9631, -37.8136]"
  map-style="https://tiles.openfreemap.org/styles/liberty"
/>

WebGL and Loading Failures

MapLibre needs WebGL and several resources referenced by the style. Use the error slot for browsers without WebGL and for network or initialization failures:

<ScriptMapLibreMap
  :center="[144.9631, -37.8136]"
  map-style="https://tiles.openfreemap.org/styles/liberty"
>
  <template #error>
    <p role="alert">
      The route map is unavailable. Follow the delivery status list instead.
    </p>
  </template>
</ScriptMapLibreMap>

Keep essential locations, route status, and actions in normal HTML rather than relying on the canvas.

Accessibility

Give each interactive map a useful aria-label. Use the description slot for the locations, routes, or links a screen-reader user needs, and give each marker a unique aria-label.

<ScriptMapLibreMap
  aria-label="Delivery route from the depot to Flinders Lane"
  :center="[144.9538, -37.8151]"
  map-style="https://tiles.openfreemap.org/styles/liberty"
>
  <template #description>
    The courier is at Docklands and is heading to Flinders Lane.
  </template>
</ScriptMapLibreMap>

For a decorative map, set :interactive="false". The component disables input, removes the map from the accessibility tree, and makes its descendants inert.

Stylesheet Loading

Nuxt Scripts loads the stylesheet from the maplibre-gl package when the SDK starts loading. To control the stylesheet through Nuxt instead:

export default defineNuxtConfig({
  css: ['maplibre-gl/dist/maplibre-gl.css'],
})

<ScriptMapLibreMap
  :center="[144.9631, -37.8136]"
  :inject-styles="false"
  map-style="/maps/style.json"
/>

Content Security Policy

MapLibre v6 loads its worker from a real URL served by your own build, so worker-src blob: is no longer required. The map still needs img-src data: blob: alongside the origins used by your style.

To serve the worker from a different path, set worker-url:

<ScriptMapLibreMap
  :center="[144.9631, -37.8136]"
  map-style="/maps/style.json"
  worker-url="/maplibre-gl-worker.mjs"
/>

Add the style, tile, sprite, glyph, and worker origins to the matching directives in your policy. See MapLibre's CSP directives for the complete requirements.