@mapbox/mapbox-gl-draw

@mapbox/mapbox-gl-draw adds interactive drawing and editing capabilities to Mapbox GL JS maps. It ships as a map control that lets users create, select, move, and delete points, lines, and polygons directly on the map, exposing the edited geometries as GeoJSON.

Built around a pluggable mode system and an internal feature store, the library handles hit detection, vertex editing, and rendering of in-progress features, while emitting draw lifecycle events your application can hook into. It is the standard way to add geometry authoring to a Mapbox GL JS application.

What You Get

• A ready-to-add Mapbox GL JS control with draw, select, and direct-edit modes
• GeoJSON-based feature management with an API to add, query, and update features programmatically
• A pluggable custom-mode system for building bespoke drawing interactions
• Draw lifecycle events (create, update, delete, selection, mode change) for application integration

Common Use Cases

• Letting users draw areas of interest or routes on an interactive map
• Building geometry editors for GIS and mapping applications
• Capturing user-drawn GeoJSON to send to a backend or spatial query

Under The Hood

Architecture

The library centers on a store.js that holds features and a modes/ directory implementing the state machines for each interaction (draw_point, draw_line_string, draw_polygon, simple_select, direct_select). events.js wires DOM/map events into the active mode, render.js translates the store into GL JS layers each frame, setup.js bootstraps the control, and api.js exposes the public methods. feature_types/ defines the GeoJSON feature classes the store manipulates.

Tech Stack

Written in JavaScript and designed as a peer of mapbox-gl-js, which it requires at runtime. It renders through GL JS layers and sources rather than its own canvas, and is bundled for browser use.

Code Quality

A mature, heavily-adopted project with 1,600+ commits and 120+ contributors, it maintains an extensive test suite, documented API (docs/API.md), and CI. The mode/store/render separation keeps interaction logic isolated and extensible.

API Design

The control follows GL JS conventions — construct with options, map.addControl(draw), then call methods like draw.add, draw.getAll, and draw.changeMode. The event-driven model and documented custom-mode contract make common tasks straightforward, while advanced customization (custom modes, styling) has a steeper but well-documented path.