nuxt-mapbox
Go to documentationElegant Mapbox integration with Nuxt
Nuxt-Mapbox
Elegant Mapbox integration with Nuxt
Features
- 🏗 Easily add Mapbox to your Nuxt app with Vue components
- 🌎 useMapbox Composable for easy access
- 👷 defineMapboxMarker & defineMapboxPopup for making custom components
- 📖 Supports many map instances across routes
TODO
PopupMarkerAdd rest of global properties to configEvent ListenersPopup & Marker Events- Unit tests
- Custom Control Component?
Quick Setup
- Add
nuxt-mapbox
&mapbox-gl
dependencies to your project
# Using pnpmpnpm add -D nuxt-mapbox mapbox-gl# Using yarnyarn add --dev nuxt-mapbox mapbox-gl# Using npmnpm install --save-dev nuxt-mapbox mapbox-gl
- Add
nuxt-mapbox
to themodules
section ofnuxt.config.ts
export default defineNuxtConfig({ modules: [ 'nuxt-mapbox' ]})
- Add your Mapbox API key to the
mapbox
section ofnuxt.config.ts
export default defineNuxtConfig({ modules: [ 'nuxt-mapbox' ], mapbox: { accessToken: '{API_KEY}' }})
Usage
View the Mapbox GL JS Docs for reference.
Map instances are created with components. You can provide all the options through component props
Example:
<MapboxMap map-id="{ID}" style="position: absolute; top: 0; bottom: 0; left: 250px; width: 500px;" :options="{ style: 'mapbox://styles/mapbox/light-v11', // style URL center: [-68.137343, 45.137451], // starting position zoom: 5 // starting zoom }" >
You can add Layers & Controls by nesting their components inside the Map
Examples:
<MapboxMap> <MapboxSource source-id="geojson" :source="{ type: 'geojson', data: '/test.geojson' }" /> <MapboxLayer source-id="geojson" :layer="{ source: 'geojson', id: 'geojson-layer', type: 'fill' }" /> </MapboxMap>
<MapboxMap> <MapboxLayer source-id="{ID}" :source="{ type: 'geojson', data: '/test.geojson' }" :layer="{ source: '{ID}', id: 'geojson-layer', type: 'fill' }" /> <MapboxFullscreenControl /> </MapboxMap>
Events
All Map events are accessible directly through the component (With full Typescript support!)
View a list of events in the Mapbox Docs
Example:
<MapboxMap ... @load="exampleFunction" @click="exampleFunction" @resize="exampleFunction" >
You can access events directly on layers as well
Example:
<MapboxLayer ... @click="exampleFunction" >
Map Instance
You can access the map instance with the useMapbox composable. You must provide the map id.
The map instance will not be available until the page is fully loaded, so you must access it through a callback
useMapbox(mapId, (map) => { // Do whatever with map here })
You can access the map instance ref directly with useMapboxInstance
NOTE: The map instance will be null until is initialized so you cannot access it directly on setup. Use a watcher as shown or useMapbox instead:
const map = useMapboxInstance(mapId) watch(map, () => { if (map.value) // Do whatever with map })
Custom Components
While it is recommended to use the default components, making your own is easy with the built in composables!
Custom Popups & Markers
You can use defineMapboxPopup
& defineMapboxMarker
for custom marker & popup components
By passing a template ref you can put custom html directly into your component
Examples:
const popup = defineMapboxPopup(popupId, options, templateRef) popup?.setLngLat(lnglat)
NOTE: Because of the way markers are implemented in Mapbox, if passing a template ref to defineMapboxPopup you have to define properties in a callback like so:
const markerRef = defineMapboxMarker(markerId, options, templateRef, (marker) => { marker.setLngLat([110, 6]) })
Custom Map Component
If you would like to make your own map component, you can use defineMapboxInstance
Example:
// NOTE: Map instance will be null on server & until it is loaded on client const map = defineMapboxInstance(MAP_DIV_ID, options);
Development
# Install dependenciesnpm install# Generate type stubsnpm run dev:prepare# Develop with the playgroundnpm run dev# Build the playgroundnpm run dev:build# Run ESLintnpm run lint# Run Vitestnpm run testnpm run test:watch# Release new versionnpm run release