Leaflet Draw API reference

This documentation is has been transcribed from the original README.MD to jsdoc's or natural docs style for use with Leafdoc. If you identify a typo or have a suggestion for this documentation, please feel free toedit the js comment blocks in the src directory, build with 'jake docs' and submit a pull request.

Leaflet 1.0+ Examples

Leaflet 0.7+ Examples

L.Draw

To add the draw toolbar set the option drawControl: true in the map options.

Usage example

     var map = L.map('map', {drawControl: true}).setView([51.505, -0.09], 13);
     L.tileLayer('http://{s}.tile.osm.org/{z}/{x}/{y}.png', {
         attribution: '&copy; <a href="http://osm.org/copyright">OpenStreetMap</a> contributors'
     }).addTo(map);

Adding the edit toolbar

To use the edit toolbar you must initialise the Leaflet.draw control and manually add it to the map.

     var map = L.map('map').setView([51.505, -0.09], 13);
     L.tileLayer('http://{s}.tile.osm.org/{z}/{x}/{y}.png', {
         attribution: '&copy; <a href="http://osm.org/copyright">OpenStreetMap</a> contributors'
     }).addTo(map);
     // FeatureGroup is to store editable layers
     var drawnItems = new L.FeatureGroup();
     map.addLayer(drawnItems);
     var drawControl = new L.Control.Draw({
         edit: {
             featureGroup: drawnItems
         }
     });
     map.addControl(drawControl);

The key here is the featureGroup option. This tells the plugin which FeatureGroup contains the layers that should be editable. The featureGroup can contain 0 or more features with geometry types Point, LineString, and Polygon. Leaflet.draw does not work with multigeometry features such as MultiPoint, MultiLineString, MultiPolygon, or GeometryCollection. If you need to add multigeometry features to the draw plugin, convert them to a FeatureCollection of non-multigeometries (Points, LineStrings, or Polygons).

L.drawLocal

The core toolbar class of the API — it is used to create the toolbar ui

Usage example

     var modifiedDraw = L.drawLocal.extend({
         draw: {
             toolbar: {
                 buttons: {
                     polygon: 'Draw an awesome polygon'
                 }
             }
         }
     });

The default state for the control is the draw toolbar just below the zoom control. This will allow map users to draw vectors and markers. Please note the edit toolbar is not enabled by default.

L.Draw.Toolbar

The toolbar class of the API — it is used to create the ui This will be depreciated

Usage example

   var toolbar = L.Toolbar();
   toolbar.addToolbar(map);

Disabling a toolbar

If you do not want a particular toolbar in your app you can turn it off by setting the toolbar to false.

     var drawControl = new L.Control.Draw({
         draw: false,
         edit: {
             featureGroup: editableLayers
         }
     });

Disabling a toolbar item

If you want to turn off a particular toolbar item, set it to false. The following disables drawing polygons and markers. It also turns off the ability to edit layers.

     var drawControl = new L.Control.Draw({
         draw: {
             polygon: false,
             marker: false
         },
         edit: {
             featureGroup: editableLayers,
             edit: false
         }
     });

Methods

Methods for modifying the toolbar

Method Returns Description
initialize(options) void

Toolbar constructor

enabled() boolean

Gets a true/false of whether the toolbar is enabled

disable() void

Disables the toolbar

addToolbar(map) L.DomUtil

Adds the toolbar to the map and returns the toolbar dom element

removeToolbar() void

Removes the toolbar and drops the handler event listeners

L.Draw.Event

Use L.Draw.Event.EVENTNAME constants to ensure events are correct.

Usage example

map.on(L.Draw.Event.CREATED; function (e) {
   var type = e.layerType,
       layer = e.layer;
   if (type === 'marker') {
       // Do marker specific actions
   }
   // Do whatever else you need to. (save to db; add to map etc)
   map.addLayer(layer);
});
     map.on('draw:edited', function (e) {
         var layers = e.layers;
         layers.eachLayer(function (layer) {
             //do whatever you want; most likely save back to db
         });
     });

Events

Event Data Description
draw:created PolyLine Polygon; Rectangle; Circle; Marker | String Layer that was just created. The type of layer this is. One of: polyline; polygon; rectangle; circle; marker Triggered when a new vector or marker has been created.
draw:edited LayerGroup List of all layers just edited on the map. Triggered when layers in the FeatureGroup; initialised with the plugin; have been edited and saved.
draw:deleted LayerGroup List of all layers just removed from the map. Triggered when layers have been removed (and saved) from the FeatureGroup.
draw:drawstart String The type of layer this is. One of:polyline; polygon; rectangle; circle; marker Triggered when the user has chosen to draw a particular vector or marker.
draw:drawstop String The type of layer this is. One of: polyline; polygon; rectangle; circle; marker Triggered when the user has finished a particular vector or marker.
draw:drawvertex LayerGroup List of all layers just being added from the map. Triggered when a vertex is created on a polyline or polygon.
draw:editstart String The type of edit this is. One of: edit Triggered when the user starts edit mode by clicking the edit tool button.
draw:editmove ILayer Layer that was just moved. Triggered as the user moves a rectangle; circle or marker.
draw:editresize ILayer Layer that was just moved. Triggered as the user resizes a rectangle or circle.
draw:editvertex LayerGroup List of all layers just being edited from the map. Triggered when a vertex is edited on a polyline or polygon.
draw:editstop String The type of edit this is. One of: edit Triggered when the user has finshed editing (edit mode) and saves edits.
draw:deletestart String The type of edit this is. One of: remove Triggered when the user starts remove mode by clicking the remove tool button.
draw:deletestop String The type of edit this is. One of: remove Triggered when the user has finished removing shapes (remove mode) and saves.
draw:toolbaropened String Triggered when a toolbar is opened.
draw:toolbarclosed String Triggered when a toolbar is closed.
draw:markercontext String Triggered when a marker is right clicked.

L.Draw.Feature

Methods

Method Returns Description
initialize() void
enable() void

Enables this handler

disable() void
addHooks() void

Add's event listeners to this handler

removeHooks() void

Removes event listeners from this handler

setOptions(object) void

Sets new options to this handler

L.Draw.SimpleShape

Methods

Method Returns Description
initialize() void
addHooks() void

Add listener hooks to this handler.

removeHooks() void

Remove listener hooks from this handler.

Method Returns Description
enable() void

Enables this handler

disable() void
setOptions(object) void

Sets new options to this handler

L.Draw.Marker

Methods

Method Returns Description
initialize() void
addHooks() void

Add listener hooks to this handler.

removeHooks() void

Remove listener hooks from this handler.

Method Returns Description
enable() void

Enables this handler

disable() void
setOptions(object) void

Sets new options to this handler

L.Draw.CircleMarker

Methods

Method Returns Description
initialize() void
Method Returns Description
addHooks() void

Add listener hooks to this handler.

removeHooks() void

Remove listener hooks from this handler.

Method Returns Description
enable() void

Enables this handler

disable() void
setOptions(object) void

Sets new options to this handler

L.Draw.Circle

Methods

Method Returns Description
initialize() void
Method Returns Description
addHooks() void

Add listener hooks to this handler.

removeHooks() void

Remove listener hooks from this handler.

Method Returns Description
enable() void

Enables this handler

disable() void
setOptions(object) void

Sets new options to this handler

L.Draw.Polyline

Methods

Method Returns Description
initialize() void
addHooks() void

Add listener hooks to this handler

removeHooks() void

Remove listener hooks from this handler.

deleteLastVertex() void

Remove the last vertex from the polyline, removes polyline from map if only one point exists.

addVertex() void

Add a vertex to the end of the polyline

completeShape() void

Closes the polyline between the first and last points

Method Returns Description
enable() void

Enables this handler

disable() void
setOptions(object) void

Sets new options to this handler

L.Draw.Rectangle

Methods

Method Returns Description
initialize() void
disable() void
Method Returns Description
addHooks() void

Add listener hooks to this handler.

removeHooks() void

Remove listener hooks from this handler.

Method Returns Description
enable() void

Enables this handler

setOptions(object) void

Sets new options to this handler

L.Draw.Polygon

Methods

Method Returns Description
initialize() void
Method Returns Description
addHooks() void

Add listener hooks to this handler

removeHooks() void

Remove listener hooks from this handler.

deleteLastVertex() void

Remove the last vertex from the polyline, removes polyline from map if only one point exists.

addVertex() void

Add a vertex to the end of the polyline

completeShape() void

Closes the polyline between the first and last points

Method Returns Description
enable() void

Enables this handler

disable() void
setOptions(object) void

Sets new options to this handler

L.Edit.SimpleShape

Methods

Method Returns Description
intialize() void
addHooks() void

Add listener hooks to this handler

removeHooks() void

Remove listener hooks from this handler

updateMarkers() void

Remove the edit markers from this layer

L.Edit.Marker

Methods

Method Returns Description
initialize() void
addHooks() void

Add listener hooks to this handler

removeHooks() void

Remove listener hooks from this handler

L.Edit.CircleMarker

Methods

Method Returns Description
intialize() void
addHooks() void

Add listener hooks to this handler

removeHooks() void

Remove listener hooks from this handler

updateMarkers() void

Remove the edit markers from this layer

L.Edit.Circle

Methods

Method Returns Description
intialize() void
addHooks() void

Add listener hooks to this handler

removeHooks() void

Remove listener hooks from this handler

updateMarkers() void

Remove the edit markers from this layer

L.Edit.Polyline

Methods

Method Returns Description
initialize() void
addHooks() void

Add listener hooks to this handler

removeHooks() void

Remove listener hooks from this handler

updateMarkers() void

Fire an update for each vertex handler

L.Edit.Rectangle

Methods

Method Returns Description
intialize() void
addHooks() void

Add listener hooks to this handler

removeHooks() void

Remove listener hooks from this handler

updateMarkers() void

Remove the edit markers from this layer

L.EditToolbar.Edit

Methods

Method Returns Description
intialize() void
enable() void

Enable the edit toolbar

disable() void

Disable the edit toolbar

addHooks() void

Add listener hooks for this handler

removeHooks() void

Remove listener hooks for this handler

revertLayers() void

Revert each layer's geometry changes

save() void

Save the layer geometries

L.EditToolbar.Delete

Methods

Method Returns Description
intialize() void
enable() void

Enable the delete toolbar

disable() void

Disable the delete toolbar

addHooks() void

Add listener hooks to this handler

removeHooks() void

Remove listener hooks from this handler

revertLayers() void

Revert the deleted layers back to their prior state.

save() void

Save deleted layers

removeAllLayers() void

Remove all delateable layers

L.GeometryUtil

Methods

Method Returns Description
geodesicArea() number
formattedNumber(n, precision) string

Returns n in specified number format (if defined) and precision

readableArea(area, isMetric, precision) string

Returns a readable area string in yards or metric. The value will be rounded as defined by the precision option object.

readableDistance(distance, units) string

Converts a metric distance to one of [ feet, nauticalMile, metric or yards ] string

readableDistance(distance, isMetric, useFeet, isNauticalMile, precision) string

Converts metric distance to distance string. The value will be rounded as defined by the precision option object.

isVersion07x() boolean

Returns true if the Leaflet version is 0.7.x, false otherwise.

L.LatLngUtil

Methods

Method Returns Description
cloneLatLngs() L.LatLngs[]

Clone the latLng point or points or nested points and return an array with those points

cloneLatLng(LatLng) L.LatLng

Clone the latLng and return a new LatLng object.

L.LineUtil

Methods

Method Returns Description
segmentsIntersect() boolean

Checks to see if two line segments intersect. Does not handle degenerate cases. http://compgeom.cs.uiuc.edu/~jeffe/teaching/373/notes/x06-sweepline.pdf

L.Polygon

Methods

Method Returns Description
intersects() boolean

Checks a polygon for any intersecting line segments. Ignores holes.

L.Polyline

Methods

Method Returns Description
intersects() boolean

Check to see if this polyline has any linesegments that intersect. NOTE: does not support detecting intersection for degenerate cases.

newLatLngIntersects() boolean

Check for intersection if new latlng was added to this polyline. NOTE: does not support detecting intersection for degenerate cases.

newPointIntersects() boolean

Check for intersection if new point was added to this polyline. newPoint must be a layer point. NOTE: does not support detecting intersection for degenerate cases.

L.Map.TouchExtend

Methods

Method Returns Description
initialize() void

Sets TouchExtend private accessor variables

addHooks() void

Adds dom listener events to the map container

removeHooks() void

Removes dom listener events from the map container

L.Control.Draw

Methods

Method Returns Description
initialize() void

Initializes draw control, toolbars from the options

onAdd() container

Adds the toolbar container to the map

onRemove() void

Removes the toolbars from the map toolbar container

setDrawingOptions(options) void

Sets options to all toolbar instances

L.Draw.Tooltip

The tooltip class — it is used to display the tooltip while drawing This will be depreciated

Usage example

   var tooltip = L.Draw.Tooltip();

Methods

Methods for modifying draw state

Method Returns Description
initialize(map) void

Tooltip constructor

dispose() void

Remove Tooltip DOM and unbind events

updateContent(labelText) this

Changes the tooltip text to string in function call

updatePosition(latlng) this

Changes the location of the tooltip

showAsError() this

Applies error class to tooltip

removeError() this

Removes the error class from the tooltip

L.DrawToolbar

Methods

Method Returns Description
initialize() void
getModeHandlers() object

Get mode handlers information

getActions() object

Get action information

setOptions() void

Sets the options to the toolbar

L.EditToolbar

Methods

Method Returns Description
intialize() void
getModeHandlers() object

Get mode handlers information

getActions() object

Get actions information

addToolbar(map) L.DomUtil

Adds the toolbar to the map

removeToolbar() void

Removes the toolbar from the map

disable() void

Disables the toolbar

L.Edit.PolyVerticesEdit

Methods

Method Returns Description
intialize() void
addHooks() void

Add listener hooks to this handler.

removeHooks() void

Remove listener hooks from this handler.

updateMarkers() void

Clear markers and update their location

L.Marker.Touch

This isn't full Touch support. This is just to get markers to also support dom touch events after creation

#TODO: find a better way of getting markers to support touch.

Install

You have four methods of installing Leaflet.Draw, copy the leaflet.draw.js, css, and images from dist and embed directly into your application.

npm

To install the plugin run npm install leaflet-draw via command line in your project. You must also require this in your project like so: var leafletDraw = require('leaflet-draw');

bower

To install the plugin run bower install leaflet-draw.

Builder

There is a custom builder at ../build/build.html to help make a custom package of Leaflet.Draw with the command line.

CDN's

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/leaflet.draw/0.4.2/leaflet.draw.css"/>
<script src="https://cdnjs.cloudflare.com/ajax/libs/leaflet.draw/0.4.2/leaflet.draw.js"></script>

Options

You can configure the plugin by using the different options listed here. If you identify a typo or have a suggestion for this section of the documentation, please edit docs-misc.leafdoc in the build directory.

Control.Draw

Option Type Default Description
position String 'topleft' The initial position of the control (one of the map corners). See control positions.
draw DrawOptions {} The options used to configure the draw toolbar.
edit EditPolyOptions false The options used to configure the edit toolbar.

DrawOptions

Option Type Default Description
polyline PolylineOptions { } Polyline draw handler options. Set to false to disable handler.
polygon PolygonOptions { } Polygon draw handler options. Set to false to disable handler.
rectangle RectangleOptions { } Rectangle draw handler options. Set to false to disable handler.
circle CircleOptions { } Circle draw handler options. Set to false to disable handler.
marker MarkerOptions { } Marker draw handler options. Set to false to disable handler.
circlemarker CircleMarkerOptions { } Circle marker draw handler options. Set to false to disable handler.

PolylineOptions

Option Type Default Description
allowIntersection Bool true Determines if line segments can cross.
drawError Object See code Configuration options for the error that displays if an intersection is detected.
guidelineDistance Number 20 Distance in pixels between each guide dash.
shapeOptions Leaflet Polyline options See code The options used when drawing the polyline/polygon on the map.
showLength Bool true Show the length of the drawn line. The area is only approximate and become less accurate the larger the polygon is.
metric Bool true Use the metric measurement system.
feet Bool true Use feet instead of yards and miles, when not using the metric measurement system.
nautic Bool false Use nautic miles instead of yards and miles, when not using the metric measurement system nor feet.
zIndexOffset Number 2000 This should be a high number to ensure that you can draw over all other layers on the map.
repeatMode Bool false Determines if the draw tool remains enabled after drawing a shape.

PolygonOptions

Option Type Default Description
showArea Bool false Show the area of the drawn polygon in m², ha or km². The area is only approximate and become less accurate the larger the polygon is.
showLength Bool false Show the length of the drawn line. The area is only approximate and become less accurate the larger the polygon is.
metric Object true Use the metric measurement system. Can be a boolean value, but can also be an array to specify which units to use. Possible units are km (kilometers), ha (hectares), m (metres). So a value of ['km', 'm'] means that the length will be shown in metres and, when more than a 1000 metres, in kilometers, and the area will be shown in m² or km² and acres will not be used.
feet Bool true Use feet instead of yards and miles, when not using the metric measurement system.
nautic Bool false Use nautic miles instead of yards and miles, when not using the metric measurement system nor feet.
precision Object {km: 2, ha: 2, m: 0, mi: 2, ac: 2, yd: 0, ft: 0, nm: 2} Defines the precision to use for numbers of each type of unit. Possible units are km (kilometers), ha (hectares), m (metres), mi (miles), ac (acres), ya (yards), ft (feet), nm (nautical miles). For example {km: 1} changes the default precision for km and km² to one which gives values like 1.5 km and 15.0 km² in stead of 1.53 km and 15.01 km².

RectangleOptions

Option Type Default Description
shapeOptions Leaflet Path options See code The options used when drawing the rectangle on the map.
repeatMode Bool false Determines if the draw tool remains enabled after drawing a shape.
showRadius Bool true Show the area of the drawn circle in m², ha or km². The area is only approximate and become less accurate the larger the circle is.

CircleOptions

Option Type Default Description
shapeOptions Leaflet Path options See code The options used when drawing the circle on the map.
repeatMode Bool false Determines if the draw tool remains enabled after drawing a shape.

MarkerOptions

Option Type Default Description
icon Leaflet Icon L.Icon.Default() The icon displayed when drawing a marker.
zIndexOffset Number 2000 This should be a high number to ensure that you can draw over all other layers on the map.
repeatMode Bool false Determines if the draw tool remains enabled after drawing a shape.

EditPolyOptions

Option Type Default Description
featureGroup Leaflet FeatureGroup null This is the FeatureGroup that stores all editable shapes. THIS IS REQUIRED FOR THE EDIT TOOLBAR TO WORK
edit EditHandlerOptions { } Edit handler options. Set to false to disable handler.
remove DeleteHandlerOptions { } Delete handler options. Set to false to disable handler.
poly EditPolyOptions { } Set polygon editing options
allowIntersection Bool true Determines if line segments can cross.

EditHandlerOptions

Option Type Default Description
selectedPathOptions Leaflet Path options See code The path options for how the layers will look while in edit mode. If this is set to null the editable path options will not be set.

Note: To maintain the original layer color of the layer use maintainColor: true within selectedPathOptions. E.g. The edit options below will maintain the layer color and set the edit opacity to 0.3.

{
    selectedPathOptions: {
        maintainColor: true,
        opacity: 0.3
    }
}

version

A constant that represents the Leaflet.Draw version in use.

    L.drawVersion; // contains "0.4.2" (or whatever version is currently in use)