Overview

GeoCertaMap is an interactive map with built-in drawing tools, a toolbar, and a clean API for loading and reading back site geometries.

Configuration

Pass a config object to the constructor. All fields are optional — defaults are shown below.

const map = new GeoCertaMap.GeoCertaMap({ /* options */ });

Top-level options

Option	Type	Default	Description
`container`	`string \| HTMLElement`	`'#map'`	CSS selector or DOM element for the map
`center`	`[lng, lat]`	`[0, 0]`	Initial map centre
`zoom`	`number`	`2`	Initial zoom level
`style`	`StyleSpecification \| string`	OpenStreetMap tiles	Map style object or URL. Defaults to OSM raster tiles
`initialGeometry`	`DrawableGeometry`	—	GeoJSON geometry to pre-load on mount
`disableRotation`	`boolean`	`true`	Lock the map to North-up

`drawOptions`

Controls the drawing tool behaviour and visual style.

Option	Type	Default	Description
`modes`	`DrawMode[]`	all modes	Which drawing tools to enable. Possible values: `'polygon'` `'line'` `'point'` `'circle'` `'rectangle'` `'select'`
`defaultMode`	`DrawMode \| null`	`null`	Drawing mode activated on load
`strokeColor`	`string`	`'#3b82f6'`	Stroke colour for drawn features
`fillColor`	`string`	`'rgba(59,130,246,0.15)'`	Fill colour for drawn features
`strokeWidth`	`number`	`2`	Stroke width in pixels
`pointRadius`	`number`	`6`	Point marker radius in pixels
`snapDistance`	`number`	`10`	Snap distance in pixels
`enableSnapping`	`boolean`	`true`	Enable vertex snapping

`controls`

Option	Type	Default	Description
`navigation`	`boolean`	`true`	Show zoom and pan controls
`geolocate`	`boolean`	`false`	Show geolocate button
`scale`	`boolean`	`false`	Show scale bar
`fullscreen`	`boolean`	`false`	Show fullscreen button

`toolbar`

Set to true to show the default toolbar, or pass a ToolbarConfig object to customise it.

Option	Type	Description
`modes`	`DrawMode[]`	Which mode buttons to display
`position`	`'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'`	Toolbar position on the map
`showEdit`	`boolean`	Show the edit button
`showDeleteSelected`	`boolean`	Show the delete-selected button
`showDeleteAll`	`boolean`	Show the delete-all button
`showUncombine`	`boolean`	Show the uncombine button
`enableKeyboardShortcuts`	`boolean`	Enable keyboard shortcuts (Shift+D, Shift+S, Backspace, etc.)

Default configuration

{
  container: '#map',
  center: [0, 0],
  zoom: 2,
  style: {
    version: 8,
    sources: {
      osm: {
        type: 'raster',
        tiles: ['https://a.tile.openstreetmap.org/{z}/{x}/{y}.png'],
        tileSize: 256,
        attribution: '&copy; OpenStreetMap Contributors',
        maxzoom: 19,
      },
    },
    layers: [{ id: 'osm', type: 'raster', source: 'osm' }],
    glyphs: 'https://demotiles.maplibre.org/font/{fontstack}/{range}.pbf',
  },
  drawOptions: {
    modes: ['polygon', 'line', 'point', 'circle', 'rectangle'],
    defaultMode: null,
    strokeColor: '#3b82f6',
    fillColor: 'rgba(59,130,246,0.15)',
    strokeWidth: 2,
    pointRadius: 6,
    snapDistance: 10,
    enableSnapping: true,
  },
  controls: {
    navigation: true,
    geolocate: false,
    scale: false,
    fullscreen: false,
  },
  disableRotation: true,
  onFeatureCreate: null,
  onFeatureUpdate: null,
  onFeatureDelete: null,
  onModeChange: null,
  onDrawChange: null,
  onError: null,
  onIdle: null,
  onReady: null,
}

Events

`onDrawChange` — primary event

onDrawChange fires every time the drawn geometry changes — when a feature is created, edited, or deleted. The payload is the current combined GeoJSON geometry, or null when the canvas is empty. This is the main callback to use when you need the geometry.

const map = new GeoCertaMap.GeoCertaMap({
  container: '#map',
  onDrawChange: (geometry) => {
    if (geometry) {
      // geometry is a GeoJSON Polygon, MultiPolygon, or Point
      console.log(geometry);
    }
  },
});

Other events

These fire for lower-level feature lifecycle events. Most integrations won't need them.

Callback	Payload	When it fires
`onFeatureCreate(feature)`	`Feature`	A new feature is drawn
`onFeatureUpdate(feature)`	`Feature`	A feature's vertices are edited
`onFeatureDelete(feature)`	`Feature`	A feature is deleted
`onModeChange(mode)`	`DrawMode \| null`	The active drawing mode changes
`onReady(instance)`	`GeoCertaMapInstance`	The map has finished loading
`onError(error)`	`Error`	An internal error occurs
`onIdle()`	—	The map becomes idle after rendering

Event emitter API

All events are also available as an emitter, as an alternative to config callbacks:

map.on('geometry:change', (geometry) => { /* ... */ });
map.off('geometry:change', handler);

Available event names: 'ready' 'geometry:change' 'feature:create' 'feature:update' 'feature:delete' 'mode:change' 'selection:change'

Methods

Core methods

Method	Signature	Description
`geometry`	`→ DrawableGeometry \| null`	Read-only getter. Returns the current combined GeoJSON geometry (Polygon, MultiPolygon, or Point), or `null` when nothing is drawn.
`setGeometry`	`(geometry: DrawableGeometry) → this`	Load a GeoJSON geometry onto the map and fit the camera to its bounds.
`centerCameraOnDraw`	`(options?: FitBoundsOptions) → this`	Fit the camera to the bounds of the current drawn geometry.

// load a saved geometry and zoom to it
map.setGeometry(savedPolygon);

// re-centre the camera without changing the geometry
map.centerCameraOnDraw({ padding: 40 });

// read the geometry at any time
const geojson = map.geometry;

Other methods

Method	Description
`setMode(mode)`	Activate a drawing mode (`'polygon'`, `'line'`, `'point'`, `'circle'`, `'rectangle'`, `'select'`)
`clearMode()`	Deactivate the current drawing mode
`getMode()`	Return the active drawing mode, or `null`
`getFeatures()`	Return all drawn features as a GeoJSON FeatureCollection
`getFeature(id)`	Return a single feature by ID, or `null`
`addFeature(feature)`	Programmatically add a GeoJSON Feature; returns its assigned ID
`removeFeature(id)`	Remove a feature by ID; returns `true` if found
`clearFeatures()`	Remove all drawn features
`deleteSelected()`	Delete the currently selected feature(s)
`editSelected()`	Enter vertex-edit mode for the selected feature
`editFeature(id)`	Enter vertex-edit mode for a specific feature by ID
`uncombineFeatures()`	Split any multi-part features into individual features
`moveTo(lngLat, options?)`	Pan the camera to the given coordinates
`on(event, fn)`	Subscribe to an event
`off(event, fn)`	Unsubscribe from an event
`getCanvas()`	Return the underlying HTML canvas element
`destroy()`	Tear down the map and release all resources