vue-map-radius

vue-map-radius

A Vue 3 component for drawing radius circles and administrative polygons on MapTiler (MapLibre GL JS) maps.

Motivations

I built this over a weekend because my team needed a map radius/polygon picker — a low-priority feature that kept getting deprioritised. It was also a chance to try out vibe coding: letting an AI assistant drive most of the implementation. v1 was written with OpenCode running the Big Pickle model; v2 — the multi-circle rewrite — with Claude Code on Opus. The result is a real, shippable component that solved the original need and doubled as a fun experiment in AI-assisted development.

Features

• Radius mode — add any number of circles by search, each one independently draggable by its centre or its radius handle
• Polygon mode — search and merge administrative boundaries (country, region, subregion, county) into one shape
• One combined output — every circle or zone merges into a single MultiPolygon, emitted separately from the model
• Round-trippable v-model — what comes out goes back in: store it, reload, and the map rebuilds itself
• Accessible — combobox search, radiogroup mode toggle and selectable chips, all keyboard- and screen-reader-operable
• TypeScript — typed props, emits, slots and exposed methods
• Lightweight — 13.4 kB (JS) + 1.3 kB (CSS) gzipped, on top of MapLibre itself (npm run size)

Installation

npm install vue-map-radius

You also need vue (3.5+) and maplibre-gl (6+) as peer dependencies:

npm install vue maplibre-gl

MapLibre ships its own stylesheet, and this package does not inline it — import it once in your app, alongside this package's:

import "maplibre-gl/dist/maplibre-gl.css"
import "vue-map-radius/style.css"

Point MapLibre at its worker

MapLibre 6 locates its web worker through its own import.meta.url, which no bundler resolves to the real file, so every app calls setWorkerUrl() once at startup — without it the map paints its background colour and no tile ever appears. This is MapLibre's requirement, not this package's; see its installation guide for the other bundlers. With Vite:

// main.ts
import { setWorkerUrl } from "maplibre-gl"
import workerUrl from "maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url"

setWorkerUrl(workerUrl)

?worker&url, not a bare ?url: the worker imports a sibling maplibre-gl-shared.mjs that ?url does not emit, and tiles then fail to parse in production only. Vite's dev server also needs MapLibre kept out of its dependency pre-bundler, which moves that import.meta.url somewhere the worker is not:

// vite.config.ts
export default defineConfig({
  optimizeDeps: { exclude: ["maplibre-gl"] },
})

docs/main.ts and vite.config.ts in this repo do exactly this, if you want a working reference.

Quick start

<script setup lang="ts">
import { ref } from "vue"
import MapRadius from "vue-map-radius"
import type { MapRadiusState, MapRadiusGeometry } from "vue-map-radius"
import "maplibre-gl/dist/maplibre-gl.css"
import "vue-map-radius/style.css"

// Restore this from your backend and the map rebuilds itself.
const state = ref<MapRadiusState>({ mode: "radius", circles: [] })

// Derived output: the merged shape of everything drawn. Never fed back in.
const geometry = ref<MapRadiusGeometry | null>(null)
</script>

<template>
  <MapRadius
    v-model="state"
    api-key="YOUR_MAPTILER_API_KEY"
    :center="[2.3522, 48.8566]"
    :zoom="10"
    height="500px"
    @geometry="geometry = $event"
  />
</template>

State vs. geometry

The model holds what the user chose; the geometry is what that draws. Keeping them apart is what makes the model small enough to store and safe to hand back:

type MapRadiusState = MapRadiusRadiusState | MapRadiusPolygonState

interface MapRadiusRadiusState {
  mode: "radius"
  circles: MapRadiusCircleZone[]      // { id, name, center, radiusKm, color?, bearing? }
  selectedCircleId?: string | null    // which circle the radius field edits
}

interface MapRadiusPolygonState {
  mode: "polygon"
  zones: MapRadiusZone[]              // { id, name, geometry, color? }
  center?: [number, number] | null    // fallback centre when a result had no polygon
}

mode discriminates the union, so state.circles and state.zones narrow correctly:

if (state.mode === "radius") state.circles.forEach(/* … */)

The merged shape arrives through the geometry event (or getGeometry() on the instance), never inside the model:

interface MapRadiusGeometry {
  feature: GeoJSON.Feature<GeoJSON.MultiPolygon> | null
  name: string | null
}

Circle geometry is generated from center + radiusKm, and zone geometry is simplified once and cached — so the emitted state stays orders of magnitude smaller than the shape on screen.

Props

Labels

Every string the component renders — placeholders, button labels, error text, accessible names — resolves through the translation layer. Override any of them per locale:

<MapRadius
  :translations="{
    en: { 'search.placeholder': 'Find a city…', 'mode.polygon': 'Area' },
  }"
/>

Keys: search.placeholder, search.ariaLabel, search.loading, search.resultCount, info.noResults, info.nonPolygon, radius.label, radius.minMessage, radius.maxMessage, mode.radius, mode.polygon, mode.ariaLabel, map.ariaLabel, error.noApiKey, error.network, zone.remove, zone.loading. TranslationKey types them, and an unknown key warns in dev.

Events

Exposed methods

const map = useTemplateRef("mapRadius")
map.value?.flyTo([2.35, 48.85], 12)
map.value?.getGeometry()   // the merged MultiPolygon, on demand

Slots

Four named slots replace a part of the UI; each renders its default subcomponent when you pass nothing. Slot props are typed.

Styling

Colours and radii come from CSS custom properties, so a theme is a few lines:

.vmr-map-radius {
  --vmr-primary-color: #2563eb;
  --vmr-error-color: #dc2626;
  --vmr-search-bg: #ffffff;
  --vmr-search-border: #d1d5db;
  --vmr-search-radius: 6px;
}

Map layer colours are props rather than CSS, since MapLibre paints them on a canvas — use paintOptions.

Exports

The package's default export is the component. Alongside it:

Geo utils

Composables

Types

Mode, MapRadiusState, MapRadiusRadiusState, MapRadiusPolygonState, MapRadiusGeometry, MapRadiusError, MapRadiusZone, MapRadiusCircleZone, MapRadiusDisplayZone, GeocodingResult, MapRadiusGeoOptions, MapRadiusPaintOptions, MapRadiusInteractiveOptions, TranslationKey, SplitOutlyingPartsOptions, SplitOutlyingPartsResult.

Migrating from v1

[!WARNING] Do not use 2.0.0 — it is deprecated. It pins maplibre-gl@^5, and every MapLibre 5 release carries an unpatched critical XSS in DOM.sanitize() (GHSA-jrc7-96c5-q579); the fix only exists in MapLibre 6. Upgrade to 2.1.0, which requires maplibre-gl@^6. It is a minor release on purpose: a caret range ^2.0.0 picks it up on the next install, which is the point. Coming from 2.0.0, the two bullets marked (2.1.0) below are the whole migration — props, emits, slots, exposed methods and the v-model shape are unchanged.

• MapLibre 6 is required (2.1.0). The peer range is now maplibre-gl@^6; MapLibre 5 has an unpatched XSS in DOM.sanitize(), and no 5.x release fixes it. Run npm install maplibre-gl@^6.
• You must call setWorkerUrl() (2.1.0). New in MapLibre 6 and easy to miss: skip it and the map renders blank with no error. See Point MapLibre at its worker.
• MapLibre 6 requires WebGL2 (2.1.0), having dropped WebGL1. Its v5→v6 migration guide covers the rest, which applies to your own map code rather than to this component.
• The package is ESM only (2.1.0). MapLibre 6 ships no UMD or CJS build, so the dist/vue-map-radius.umd.cjs bundle — which externalised a maplibregl global that no longer exists — is gone, along with the main field and the require export condition. import is unchanged. require() still resolves, but to the ESM build, so it needs Node 22.12+ (or a bundler that handles require of ESM); MapLibre 6 itself carries the same requirement.
• State is a discriminated union. center / radiusKm / name / bearing at the top level are gone; read state.circles in radius mode and state.zones in polygon mode.
• Geometry left the model. state.polygon is gone — listen to @geometry or call getGeometry().
• Radius mode holds many circles. Selecting a search result adds one instead of moving the only one.
• Label option bags are gone. searchOptions, radiusOptions, modeToggleOptions and zoneListOptions are replaced by translations keys; mapOptions.style is now the mapStyle prop.
• useRadius is gone, replaced by the pure clampRadius / getValidationMessage / formatRadius.
• MapLibre's stylesheet is no longer bundled — import maplibre-gl/dist/maplibre-gl.css yourself.

Contributing

Bug reports and feature requests are welcome via GitHub Issues. If you'd like to fix something or add a feature, feel free to open a pull request — contributions of all kinds are appreciated.

Development

cp .env.example .env   # add your VITE_MAPTILER_KEY

npm run dev            # playground at docs/
npm test               # unit + component tests
npm run test:coverage
npm run typecheck
npm run lint
npm run build

License

MIT