wakeb-map

wakeb-map

A free, multi-provider Vue 3 map library supporting Leaflet, Mapbox GL JS, Google Maps, and custom providers.
Default engine: Leaflet + OpenStreetMap — zero API key needed.
Includes a built-in SVG vector map engine (world maps, regions, markers, lines — no external dependencies).
Full offline support, 19 composables, 3 components, and 30+ utility functions.

Features

Components

Composables (19)

Key Highlights

• 100% Free — no API key, no subscription, no usage limits (Leaflet default)
• Multi-Provider — switch between Leaflet, Mapbox GL JS, or Google Maps per-component with one prop
• Works Offline — built-in canvas tile layer, inline SVG markers, Haversine distance — all work without internet
• Vector Map Engine — pure SVG renderer with regions, markers, curved/straight lines, animated dash flow, fade-in animations, data series, tooltips, zoom/pan, touch support
• 5 Map Styles — streets, satellite, topo, dark, offline (auto-mapped across providers)
• Free Geocoding — Nominatim address search + reverse geocode
• Drawing — paths, polygons, rectangles, circles, measurements, with constraint boundaries
• Fleet Tracking — real-time vehicle/entity tracking with animated movement
• Full TypeScript — every type exported

Installation

npm install wakeb-map

vue (>=3.3) and leaflet (>=1.9.4) are peer dependencies:

npm install wakeb-map leaflet
npm install -D @types/leaflet

Optional: Mapbox GL JS

npm install mapbox-gl

Then register the provider:

import mapboxgl from "mapbox-gl";
import "mapbox-gl/dist/mapbox-gl.css";
import { createMapboxProvider, registerProvider } from "wakeb-map";

registerProvider(createMapboxProvider(mapboxgl));

Optional: Google Maps

npm install @googlemaps/js-api-loader

Then register the provider:

import { Loader } from "@googlemaps/js-api-loader";
import { createGoogleMapsProvider, registerProvider } from "wakeb-map";

const google = await new Loader({ apiKey: "YOUR_KEY" }).load();
registerProvider(createGoogleMapsProvider(google));

Quick Start

Basic Map

<template>
  <WakebMap
    :center="{ lat: 24.7136, lng: 46.6753 }"
    :zoom="14"
    :markers="markers"
    height="500px"
    @click="onMapClick"
    @marker-click="onMarkerClick"
  />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { WakebMap } from "wakeb-map";
import "wakeb-map/style.css";
import type { WakebLatLng, WakebMarker } from "wakeb-map";

const markers = ref<WakebMarker[]>([
  {
    id: "1",
    position: { lat: 24.7136, lng: 46.6753 },
    title: "Riyadh",
    snippet: "Capital of Saudi Arabia",
  },
]);

function onMapClick(e: { position: WakebLatLng }) {
  console.log("Clicked:", e.position.lat, e.position.lng);
}

function onMarkerClick(marker: WakebMarker) {
  console.log("Marker:", marker.title);
}
</script>

Location Picker

<template>
  <WakebMapPicker
    v-model="location"
    height="500px"
    confirm-label="Confirm Location"
    @location-picked="onPicked"
  />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { WakebMapPicker } from "wakeb-map";
import "wakeb-map/style.css";
import type { WakebLatLng } from "wakeb-map";

const location = ref<WakebLatLng | null>(null);

function onPicked(result: { position: WakebLatLng; address: string }) {
  console.log(result.position, result.address);
}
</script>

Vector Map (SVG — No External Dependencies)

<template>
  <div ref="mapEl" style="width: 100%; height: 400px" />
</template>

<script setup lang="ts">
import { ref, onMounted } from "vue";
import { useVectorMap } from "wakeb-map";

const mapEl = ref<HTMLElement | null>(null);

const vectorMap = useVectorMap({
  map: "world",
  regionStyle: {
    initial: { fill: "#d1d5db", stroke: "#fff", strokeWidth: 0.5 },
    hover: { fill: "#3b82f6", fillOpacity: 0.8 },
    selected: { fill: "#10b981" },
  },
  markerStyle: {
    initial: { fill: "#ef4444", stroke: "#fff", r: 6 },
    hover: { fill: "#f59e0b", r: 8 },
  },
  lineStyle: {
    stroke: "#3b82f6",
    strokeWidth: 1.5,
    strokeDasharray: "6 3 6",
    animation: true,
    curvature: 0.15,
  },
  zoomButtons: true,
  showTooltip: true,
  regionsSelectable: true,
});

onMounted(() => {
  if (mapEl.value) vectorMap.init(mapEl.value);

  vectorMap.addMarkers([
    { name: "Cairo", coords: [30.04, 31.24] },
    { name: "London", coords: [51.51, -0.13] },
    { name: "Tokyo", coords: [35.68, 139.69] },
  ]);

  vectorMap.addLines([
    { from: "Cairo", to: "London" },
    { from: "London", to: "Tokyo" },
  ]);
});
</script>

Plugin Setup (Optional)

Register globally to set default center, zoom, map type, provider, and offline options:

import { createApp } from "vue";
import { WakebMapPlugin } from "wakeb-map";
import "wakeb-map/style.css";

const app = createApp(App);

app.use(WakebMapPlugin, {
  language: "ar",
  defaultCenter: { lat: 24.7136, lng: 46.6753 },
  defaultZoom: 14,
  defaultMapType: "streets",
  // provider: "mapbox",          // uncomment to use Mapbox as default
  // mapboxAccessToken: "pk.xxx", // required when using Mapbox
  // provider: "google",          // uncomment to use Google Maps as default
});

app.mount("#app");

Offline Mode

Full offline support — the map, markers, shapes, GPS, and distance all work without internet.

// Option 1: Plugin config
app.use(WakebMapPlugin, {
  offline: true,
  offlineGridColor: "#ddd",
  offlineBgColor: "#f0f0f0",
});

// Option 2: Component prop
// <WakebMap map-type="offline" />

// Option 3: Manual tile layer
import { createOfflineTileLayer } from "wakeb-map";
const offlineLayer = createOfflineTileLayer({ offlineGridColor: "#ccc" });

Map Providers

Switching Providers

<!-- Default: Leaflet (no setup needed) -->
<WakebMap :center="center" :zoom="14" height="400px" />

<!-- Mapbox GL JS -->
<WakebMap
  provider="mapbox"
  access-token="pk.xxx"
  :center="center"
  :zoom="14"
  height="400px"
/>

<!-- Google Maps -->
<WakebMap provider="google" :center="center" :zoom="14" height="400px" />

<!-- All three on the same page -->
<WakebMap :center="center" :zoom="14" height="400px" />
<WakebMap
  provider="mapbox"
  access-token="pk.xxx"
  :center="center"
  :zoom="14"
  height="400px"
/>
<WakebMap provider="google" :center="center" :zoom="14" height="400px" />

Provider Comparison

Composable Compatibility

Map Styles

<WakebMap map-type="satellite" />
<WakebMap map-type="dark" />
<WakebMap map-type="topo" />
<WakebMap map-type="offline" />

Composable Examples

useWakebMap

import { useWakebMap } from "wakeb-map";

const {
  position,
  address,
  zoom,
  markers,
  loading,
  setPosition,
  pickMyLocation,
  searchAddress,
  addMarker,
  distanceTo,
} = useWakebMap({ lat: 24.7136, lng: 46.6753 });

useDrawing

import { useDrawing } from "wakeb-map";

const drawing = useDrawing();
drawing.bindMap(leafletMap);
drawing.startDrawing("polygon", { color: "#2196F3", showMeasurements: true });
const result = drawing.finishDrawing();

useGeocoder

import { useGeocoder } from "wakeb-map";

const { search, reverse, results, loading } = useGeocoder();
await search("Kingdom Tower, Riyadh");
await reverse({ lat: 24.7136, lng: 46.6753 });

useRouting

import { useRouting } from "wakeb-map";

const { calculateRoute, route, instructions } = useRouting();
await calculateRoute(
  { lat: 24.7136, lng: 46.6753 },
  { lat: 21.4225, lng: 39.8262 },
  { profile: "driving" },
);

useHeatmap

import { useHeatmap } from "wakeb-map";

const { addPoints, setOptions } = useHeatmap(leafletMap);
addPoints([
  { lat: 24.71, lng: 46.67, intensity: 0.8 },
  { lat: 24.72, lng: 46.68, intensity: 0.5 },
]);

useFleetTracking

import { useFleetTracking } from "wakeb-map";

const fleet = useFleetTracking(leafletMap, {
  showTrails: true,
  animateMovement: true,
});
fleet.updateEntity({
  id: "truck-1",
  type: "truck",
  position: { lat: 24.7, lng: 46.6 },
});

Utilities

Geocoding (Free — Nominatim)

import { reverseGeocode, geocodeAddress } from "wakeb-map";

const addr = await reverseGeocode({ lat: 24.7136, lng: 46.6753 });
const pos = await geocodeAddress("Kingdom Tower, Riyadh");

Distance & Geometry

import {
  calculateDistance,
  calculateBearing,
  midpoint,
  isPointInPolygon,
  isPointInCircle,
  polygonArea,
  pathLength,
  getBoundingBox,
  convexHull,
  simplifyPath,
  bufferPoint,
  distanceMatrix,
} from "wakeb-map";

const meters = calculateDistance(
  { lat: 24.7136, lng: 46.6753 },
  { lat: 21.4225, lng: 39.8262 },
);

GeoJSON Import/Export

import { exportToGeoJSON, importFromGeoJSON, downloadGeoJSON } from "wakeb-map";

const geojson = exportToGeoJSON({ markers, polylines, polygons, circles });
const data = importFromGeoJSON(geojsonObject);
downloadGeoJSON(geojson, "my-map.geojson");

Props Reference

<WakebMap>

<WakebMapPicker>

Events

<WakebMap>

<WakebMapPicker>

Documentation

Full interactive docs with live demos:

visit the hosted docs at wakeb-map.surge.sh

License

MIT © Kerolos Zakaria