Build Status | Leaflet.draw Chat | Leaflet Chat |
---|---|---|
Adds support for drawing and editing vectors and markers on Leaflet maps.
Supports Leaflet 0.7.x and 1.0.0+ branches.
Please check out our new Api Documentation
Leaflet.draw 0.2.0 changes a LOT of things from 0.1. Please see BREAKING CHANGES for how to upgrade.
Install
CDN
Using the plugin
Advanced Options
Common tasks
Thanks
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');
To install the plugin run bower install leaflet-draw
.
Using unpkg
<link rel="stylesheet" href="https://unpkg.com/leaflet-draw@0.4.1/dist/leaflet.draw.css" />
<script src="https://unpkg.com/leaflet-draw@0.4.1/dist/leaflet.draw.js"></script>
Using CDNJS
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/leaflet.draw/0.4.0/leaflet.draw.css"/>
<script src="https://cdnjs.cloudflare.com/ajax/libs/leaflet.draw/0.4.0/leaflet.draw.js"></script>
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: '© <a href="http://osm.org/copyright">OpenStreetMap</a> contributors'
}).addTo(map);
You can configure the plugin by using the different options listed here.
These options make up the root object that is used when initialising the Leaflet.draw control.
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. |
These options will allow you to configure the draw toolbar and its handlers.
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. |
The following options will allow you to configure the individual draw handlers.
Polyline and Polygon drawing handlers take the same options.
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. |
metric | Bool | true |
Determines which measurement system (metric or imperial) is used. |
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. |
Polygon options include all of the Polyline options plus the option to show the approximate area.
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. |
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. |
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. |
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. |
These options will allow you to configure the draw toolbar and its handlers.
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 |
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
}
}
Option | Type | Default | Description |
---|
Option | Type | Default | Description |
---|---|---|---|
allowIntersection | Bool | true |
Determines if line segments can cross. |
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.
The following example will show you how to:
- Change the position of the control's toolbar.
- Customize the styles of a vector layer.
- Use a custom marker.
- 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!');
}
editableLayers.addLayer(layer);
});
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'
}
}
});
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.
To test you can install the npm dependencies:
npm install
and then use:
jake test
Touch friendly version of Leaflet.draw was created and maintained by Michael Guild (https://github.com/michaelguild13).
The touch support was initiated due to a demand for it at National Geographic for their Map Maker Projected (http://mapmaker.education.nationalgeographic.com/) that was created by Michael Guild and Daniel Schep (https://github.com/dschep)
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.