leaflet-draw-legacy v0.2.3

Important

Leaflet.draw 0.2.3+ requires Leaflet 0.7 or higher.

#Leaflet.draw Adds support for drawing and editing vectors and markers on Leaflet maps. Check out the demo.

Upgrading from Leaflet.draw 0.1

Leaflet.draw 0.2.0 changes a LOT of things from 0.1. Please see BREAKING CHANGES for how to upgrade.

Table of Contents

Using the plugin
Advanced Options
Common tasks
Thanks

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.

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

// create a map in the "map" div, set the view to a given place and zoom
var map = L.map('map', {drawControl: true}).setView([51.505, -0.09], 13);

// add an OpenStreetMap tile layer
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.

// create a map in the "map" div, set the view to a given place and zoom
var map = L.map('map').setView([51.505, -0.09], 13);

// add an OpenStreetMap tile layer
L.tileLayer('http://{s}.tile.osm.org/{z}/{x}/{y}.png', {
    attribution: '&copy; <a href="http://osm.org/copyright">OpenStreetMap</a> contributors'
}).addTo(map);

// Initialise the FeatureGroup to store editable layers
var drawnItems = new L.FeatureGroup();
map.addLayer(drawnItems);

// Initialise the draw control and pass it the FeatureGroup of editable layers
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.

Events

Once you have successfully added the Leaflet.draw plugin to your map you will want to respond to the different actions users can initiate. The following events will be triggered on the map:

draw:created

Triggered when a new vector or marker has been created.

map.on('draw: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);
});

draw:edited

Triggered when layers in the FeatureGroup, initialised with the plugin, have been edited and saved.

map.on('draw:edited', function (e) {
	var layers = e.layers;
	layers.eachLayer(function (layer) {
		//do whatever you want, most likely save back to db
	});
});

draw:deleted

Triggered when layers have been removed (and saved) from the FeatureGroup.

draw:drawstart

Triggered when the user has chosen to draw a particular vector or marker.

draw:drawstop

Triggered when the user has finished a particular vector or marker.

draw:editstart

Triggered when the user starts edit mode by clicking the edit tool button.

draw:editstop

Triggered when the user has finshed editing (edit mode) and saves edits.

draw:deletestart

Triggered when the user starts remove mode by clicking the remove tool button.

draw:deletestop

Triggered when the user has finished removing shapes (remove mode) and saves.

You can configure the plugin by using the different options listed here.

Control.Draw

These options make up the root object that is used when initialising the Leaflet.draw control.

These options will allow you to configure the draw toolbar and its handlers.

Draw handler options

The following options will allow you to configure the individual draw handlers.

Polyline and Polygon drawing handlers take the same options.

Polygon options include all of the Polyline options plus the option to show the approximate area.

These options will allow you to configure the draw toolbar and its handlers.

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

Leaflet.draw uses the L.drawLocal configuration object to set any text used in the plugin. Customizing this will allow support for changing the text or supporting another language.

See Leaflet.draw.js for the default strings.

E.g.

// Set the button title text for the polygon button
L.drawLocal.draw.toolbar.buttons.polygon = 'Draw a sexy polygon!';

// Set the tooltip start text for the rectangle
L.drawLocal.draw.handlers.rectangle.tooltip.start = 'Not telling...';

The following examples outline some common tasks.

Example Leaflet.draw config

The following example will show you how to:

1. Change the position of the control's toolbar.
2. Customize the styles of a vector layer.
3. Use a custom marker.
4. Disable the delete functionality.

var cloudmadeUrl = 'http://{s}.tile.cloudmade.com/BC9A493B41014CAABB98F0471D759707/997/256/{z}/{x}/{y}.png',
	cloudmade = new L.TileLayer(cloudmadeUrl, {maxZoom: 18}),
	map = new L.Map('map', {layers: [cloudmade], center: new L.LatLng(-37.7772, 175.2756), zoom: 15 });

var editableLayers = new L.FeatureGroup();
map.addLayer(editableLayers);

var MyCustomMarker = L.Icon.extend({
	options: {
		shadowUrl: null,
		iconAnchor: new L.Point(12, 12),
		iconSize: new L.Point(24, 24),
		iconUrl: 'link/to/image.png'
	}
});

var options = {
	position: 'topright',
	draw: {
		polyline: {
			shapeOptions: {
				color: '#f357a1',
				weight: 10
			}
		},
		polygon: {
			allowIntersection: false, // Restricts shapes to simple polygons
			drawError: {
				color: '#e1e100', // Color the shape will turn when intersects
				message: '<strong>Oh snap!<strong> you can\'t draw that!' // Message that will show when intersect
			},
			shapeOptions: {
				color: '#bada55'
			}
		},
		circle: false, // Turns off this drawing tool
		rectangle: {
			shapeOptions: {
				clickable: false
			}
		},
		marker: {
			icon: new MyCustomMarker()
		}
	},
	edit: {
		featureGroup: editableLayers, //REQUIRED!!
		remove: false
	}
};

var drawControl = new L.Control.Draw(options);
map.addControl(drawControl);

map.on('draw:created', function (e) {
	var type = e.layerType,
		layer = e.layer;

	if (type === 'marker') {
		layer.bindPopup('A popup!');
	}

	drawnItems.addLayer(layer);
});

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
	}
});

Changing a drawing handlers options

You can change a draw handlers options after initialisation by using the setDrawingOptions method on the Leaflet.draw control.

E.g. to change the colour of the rectangle:

drawControl.setDrawingOptions({
    rectangle: {
    	shapeOptions: {
        	color: '#0000FF'
        }
    }
});

Creating a custom build

If you only require certain handlers (and not the UI), you may wish to create a custom build. You can generate the relevant jake command using the build html file.

See edit handlers example which uses only the edit handlers.

Thanks so much to @brunob, @tnightingale, and @shramov. I got a lot of ideas from their Leaflet plugins.

All the contributors and issue reporters of this plugin rock. Thanks for tidying up my mess and keeping the plugin on track.

The icons used for some of the toolbar buttons are either from http://glyphicons.com/ or inspired by them. <3 Glyphicons!

Finally, @mourner is the man! Thanks for dedicating so much of your time to create the gosh darn best JavaScript mapping library around.