@richpods/tiny-geojson-tool

Vue 3 component library for editing and viewing GeoJSON on a MapLibre GL JS map. Draw polygons, lines, and markers, style them with simplestyle-spec properties, and bind the result with v-model.

[!IMPORTANT] The Tiny GeoJSON Tool is currently v0.x and subject to breaking changes prior to v1.0.0. Pin to a specific version or commit SHA if you need stability.

You can find a demo of this editor at code.richpods.org/tiny-geojson-tool/

Components

GeoJsonEditor — Full editing UI with a drawing toolbar, property editor, and interactive map. Supports drawing polygons, lines, and point markers, selecting and deleting features, and editing style properties (fill, stroke, marker color/size/icon).

GeoJsonViewer — Read-only map display. Renders GeoJSON features with hover popups for title/description.

Install

npm install @richpods/tiny-geojson-tool maplibre-gl pmtiles

Vue 3.5+, maplibre-gl, and pmtiles are peer dependencies.

Usage

<script setup lang="ts">
import { ref } from "vue";
import { GeoJsonEditor } from "@richpods/tiny-geojson-tool";
import "@richpods/tiny-geojson-tool/styles";
import type { EditorFeatureCollection } from "@richpods/tiny-geojson-tool";

const geojson = ref<EditorFeatureCollection>({
    type: "FeatureCollection",
    features: [],
});
</script>

<template>
    <GeoJsonEditor v-model="geojson" pmtilesUrl="https://example.com/tiles.pmtiles" />
</template>

For read-only display:

<GeoJsonViewer :modelValue="geojson" pmtilesUrl="https://example.com/tiles.pmtiles" />

Props

Both components accept:

| Prop | Type | Default | Description | |------|------|---------|-------------| | pmtilesUrl | string | (required) | URL to a PMTiles archive for the base map | | center | [lng, lat] | [0, 20] | Initial map center | | zoom | number | 2 | Initial zoom level | | bboxPadding | [top, right, bottom, left] | [0, 0, 0, 0] | Extra padding used when fitting to GeoJSON bounds |

GeoJsonEditor additionally accepts:

| Prop | Type | Default | Description | |------|------|---------|-------------| | modelValue | EditorFeatureCollection | Empty collection | GeoJSON feature collection (v-model) | | pointRadius | number | 10 | Radius of point features in pixels | | l10n | Partial<EditorLocale> | English | Override UI strings for localization | | photonUrl | string | — | Base URL for a Photon geocoder instance. Enables the location search box in the layer panel | | searchDelay | number | — | Debounce delay in ms before firing a search request | | searchBoosting | boolean | true | Boost search results towards the current map viewport | | searchLanguage | string | — | Language code for search results (e.g. "de", "fr") — passed as lang to the Photon API |

Initial map view priority on load:

1. If modelValue.bbox is present, it is used directly.
2. Otherwise, bounds are calculated from modelValue.features.
3. If no bounds can be determined (empty map), center and zoom are used.

Accessing the MapLibre Instance

Both components expose a getMap() method via template ref that returns the underlying MapLibre GL JS Map instance (or null before the map is initialized). This lets you call MapLibre methods directly — add controls, fly to coordinates, query features, etc.

<script setup lang="ts">
import { ref } from "vue";
import { GeoJsonEditor } from "@richpods/tiny-geojson-tool";
import "@richpods/tiny-geojson-tool/styles";
import type { EditorFeatureCollection } from "@richpods/tiny-geojson-tool";

const editorRef = ref<InstanceType<typeof GeoJsonEditor> | null>(null);
const geojson = ref<EditorFeatureCollection>({
    type: "FeatureCollection",
    features: [],
});

function flyToVienna() {
    editorRef.value?.getMap()?.flyTo({ center: [16.37, 48.21], zoom: 12 });
}
</script>

<template>
    <button @click="flyToVienna">Fly to Vienna</button>
    <GeoJsonEditor
        ref="editorRef"
        v-model="geojson"
        pmtilesUrl="https://example.com/tiles.pmtiles" />
</template>

The same works for GeoJsonViewer:

<script setup lang="ts">
import { ref } from "vue";
import { GeoJsonViewer } from "@richpods/tiny-geojson-tool";

const viewerRef = ref<InstanceType<typeof GeoJsonViewer> | null>(null);
</script>

<template>
    <GeoJsonViewer ref="viewerRef" :modelValue="geojson" pmtilesUrl="https://example.com/tiles.pmtiles" />
</template>

Drawing Tools

The editor toolbar provides six modes:

• Select — Click features to select and edit properties
• Draw Point — Click to place circle points
• Draw Marker — Click to place icon markers
• Draw Line — Click to add vertices, click near the last vertex to finish
• Draw Polygon — Click to add vertices, click near the first vertex to close
• Eraser — Click features to delete them

Right-click or press Escape to cancel drawing.

Location Search

GeoJsonEditor supports geocoded location search powered by Photon, an open-source geocoder built on OpenStreetMap data. Pass a Photon instance URL via the photonUrl prop to enable a search box in the layer panel.

<script setup lang="ts">
import { GeoJsonEditor, PHOTON_PUBLIC_URL } from "@richpods/tiny-geojson-tool";
</script>

<template>
    <GeoJsonEditor
        v-model="geojson"
        pmtilesUrl="https://example.com/tiles.pmtiles"
        :photonUrl="PHOTON_PUBLIC_URL" />
</template>

The library exports PHOTON_PUBLIC_URL (https://photon.komoot.io) for convenience. For production use, consider hosting your own Photon instance. When searchBoosting is enabled (the default), search results are biased towards the current map viewport.

Style Properties

Features support simplestyle-spec 1.1.0 properties:

• Polygons — fill, fill-opacity, stroke, stroke-opacity, stroke-width
• Lines — stroke, stroke-opacity, stroke-width
• Points — fill, fill-opacity, stroke, stroke-opacity, stroke-width
• Markers — marker-color, marker-size (small/medium/large), marker-symbol

All features support title and description. Extensions beyond the spec: circle-radius, marker-label, marker-label-position.

Localization

All user-facing strings in the editor can be overridden via the l10n prop. Pass a partial object — any keys you omit will use the English defaults.

<script setup lang="ts">
import { ref } from "vue";
import { GeoJsonEditor } from "@richpods/tiny-geojson-tool";
import type { EditorLocale, EditorFeatureCollection } from "@richpods/tiny-geojson-tool";

const geojson = ref<EditorFeatureCollection>({
    type: "FeatureCollection",
    features: [],
});

const de: Partial<EditorLocale> = {
    toolSelect: "Auswählen",
    toolMarker: "Markierung",
    toolLine: "Linie",
    toolPolygon: "Polygon",
    toolEraser: "Radierer",
    propTitle: "Titel",
    propDescription: "Beschreibung",
};
</script>

<template>
    <GeoJsonEditor
        v-model="geojson"
        :l10n="de"
        pmtilesUrl="https://example.com/tiles.pmtiles" />
</template>

See EditorLocale for the full list of keys and DEFAULT_LOCALE for the English defaults.

Theming

All styles use CSS custom properties prefixed with --tge-. Override them to customize the look.

Base Map

The base map expects vector tiles served from a PMTiles archive. We recommend the Shortbread schema for your tiles. You must provide the pmtilesUrl prop pointing to your own tile source.

Development

npm install
npm run dev          # Start demo at localhost:5173
npm run build        # Build library to dist/
npm run build:demo   # Build demo app to dist-demo/
npm run preview:demo # Preview built demo locally
npm run typecheck    # Run type checking

Acknowledgements

This project is built with the following open-source libraries:

• Vue — JavaScript framework
• MapLibre GL JS — Open-source map rendering library
• PMTiles — Cloud-optimized tile archive format
• Ionicons — Open-source icon set
• Shortbread — Vector tile schema for OpenStreetMap data

Map data: OpenStreetMap contributors.

License

Blue Oak Model License 1.0.0