@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 |

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.

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.

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