LibreDraw

A polygon drawing and editing library for MapLibre GL JS.

Features

Zero-config — new LibreDraw(map) gives you a full toolbar and drawing capabilities out of the box
Draw polygons — Click/tap to place vertices, double-click/double-tap to finish
Select & edit — Click a polygon to select it, drag vertices to reshape, drag midpoints to add vertices
Polygon drag — Drag an entire selected polygon to reposition it
Split polygon — Cut a polygon into two polygons with a two-point split line
Setback edge — Offset a selected edge inward and remove the setback band
Undo / Redo — Full history support for all operations
GeoJSON in/out — Import and export standard GeoJSON FeatureCollections
Touch-first — Designed for mobile with proper touch targets (44px+), long-press support, and gesture handling
Self-intersection prevention — Invalid geometries are rejected during editing
Framework-agnostic — Works with vanilla JS, React, Vue, or any framework
TypeScript — Full type definitions included
Headless mode — Disable the toolbar and drive everything via API

Quick Start

npm install @sindicum/libre-draw maplibre-gl

import maplibregl from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';
import { LibreDraw } from '@sindicum/libre-draw';

const map = new maplibregl.Map({
  container: 'map',
  style: 'https://demotiles.maplibre.org/style.json',
  center: [0, 0],
  zoom: 2,
});

const draw = new LibreDraw(map);

draw.on('create', (e) => {
  console.log('Polygon created:', e.feature);
});

draw.on('update', (e) => {
  console.log('Polygon updated:', e.feature);
});

API

Constructor

new LibreDraw(map: maplibregl.Map, options?: LibreDrawOptions)

Methods

Method	Description
`setMode(mode)`	Set active mode: `'idle'`, `'draw'`, `'select'`, `'split'`, or `'setback'`
`getMode()`	Get the current mode
`getFeatures()`	Get all features as an array
`toGeoJSON()`	Export all features as a GeoJSON FeatureCollection
`getFeatureById(id)`	Get a single feature by ID
`setFeatures(geojson)`	Replace all features with a GeoJSON FeatureCollection
`addFeatures(features)`	Add an array of GeoJSON Feature objects
`deleteFeature(id)`	Delete a feature by ID (undoable)
`selectFeature(id)`	Programmatically select a feature
`clearSelection()`	Clear the current selection
`getSelectedFeatureIds()`	Get IDs of selected features
`undo()`	Undo the last action
`redo()`	Redo the last undone action
`on(event, callback)`	Register an event listener
`off(event, callback)`	Remove an event listener
`destroy()`	Clean up all resources

Events

Event	Payload	Description
`create`	`{ feature }`	A polygon was created
`update`	`{ feature, oldFeature }`	A polygon was updated
`delete`	`{ feature }`	A polygon was deleted
`split`	`{ originalFeature, features: [featureA, featureB] }`	A polygon was split into two polygons
`splitfailed`	`{ reason, featureId }`	Split operation failed
`setback`	`{ originalFeature, feature, edgeIndex, distance }`	Setback operation succeeded
`setbackfailed`	`{ reason, featureId }`	Setback operation failed
`selectionchange`	`{ selectedIds }`	Selection changed
`modechange`	`{ mode, previousMode }`	Active mode changed

Options

interface LibreDrawOptions {
  toolbar?:
    | boolean
    | {
        position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
        controls?: {
          draw?: boolean;
          select?: boolean;
          split?: boolean;
          setback?: boolean;
          delete?: boolean;
          undo?: boolean;
          redo?: boolean;
        };
      };
  historyLimit?: number; // Default: 100
}

Set toolbar: false for headless mode (API-only, no UI).

Documentation

Full documentation with interactive demos is available at:

https://sindicum.github.io/libre-draw/

Development

# Install dependencies
npm install

# Run dev server with example
npm run dev

# Run tests
npm test

# Lint
npm run lint

# Type check
npm run typecheck

# Build
npm run build

# Documentation site
npm run docs:dev

Requirements

MapLibre GL JS >= 3.0.0, v3.x and v4.x supported (peer dependency)
Modern browser with WebGL support

License

MIT