API Reference

To use Draw

var Draw = new MapboxDraw({ options });
map.addControl(Draw);

Draw only works after the map has loaded so it is wise to perform any interactions in the load event callback of mapbox-gl:

map.on('load', function() {
    Draw.add({ ... });
    console.log(Draw.getAll());
    ...
});

Options

option	values	function
keybindings	boolean	Keyboard shortcuts for drawing - default: `true`
touchEnabled	boolean	If true, enables touch interaction - default: `true`
boxSelect	boolean	If true, shift + click to features. If false, click + select zooms to area - default: `true`
clickBuffer	number	On click, include features beyond the coordinates of the click by clickBuffer value all directions - default: `2`
touchBuffer	number	On touch, include features beyond the coordinates of the touch by touchBuffer value all directions - default: `25`
displayControlsDefault	boolean	Sets default value for the control keys in the control option - default `true`
userProperties	boolean	If true, user properties will be present and prefixed with `user_` on the feature objects via styling. - default `false`
controls	Object	Lets you hide or show individual controls. See `displayControlsDefault` for default. Available options are: `point`, `line_string`, `polygon`, `trash`, `combine_features` and `uncombine_features`.
styles	Array	An array of style objects. By default draw provides a style for you. To override this see Styling Draw further down.

Modes

The modes names are available as an enum at Draw.modes.

`simple_select`

Draw.modes.SIMPLE_SELECT === 'simple_select'

Lets you select, delete and drag features.

In this mode, features can have their active state changed by the user. To control what is active, react to changes as described in the events section below.

Draw will transition into simple_select mode every time a single feature has completed drawing.

`direct_select`

Draw.modes.DIRECT_SELECT === 'direct_select'

Lets you select, delete and drag vertices.

direct_select mode doesn't handle point features.

`draw_line_string`

Draw.modes.DRAW_LINE_STRING === 'draw_line_string'

Lets you draw a LineString feature.

`draw_polygon`

Draw.modes.DRAW_POLYGON === 'draw_polygon'

Lets you draw a Polygon feature.

`draw_point`

Draw.modes.DRAW_POINT === 'draw_point'

Lets you draw a Point feature.

`static`

Draw.modes.STATIC === 'static'

Disables editing for all drawn features. It does not take an options argument.

Note that this mode can only be entered or exited via .changeMode

API Methods

new MapboxDraw() returns an instance of Draw which has the following API for working with your data:

###.add(Object: GeoJSON) -> [String]

This method takes either a Feature or a FeatureCollection and adds it to Draw. It returns an array of ids for interacting with the added features.

Currently the supported GeoJSON feature types are Point, LineString, Polygon, MultiPoint, MultiLineString, and MultiPolygon.

Adding a feature with the same id as another feature performs an update.

Example:

var feature = { type: 'Point', coordinates: [0, 0] };
var featureId = Draw.add(feature);
console.log(featureId);
//=> 'random-string'

Example with ID:

var feature = { type: 'Point', coordinates: [0, 0], id: 'unique-id' };
var featureId = Draw.add(feature);
console.log(featureId)
//=> unique-id

###.get(String: featureId) -> Object

This method takes an ID returns a GeoJSON feature.

Example:

var id = Draw.add({ type: 'Point', coordinates: [0, 0] });
console.log(Draw.get(id));
//=> { type: 'Feature', geometry: { type: 'Point', coordinates: [0, 0] } }

`.getFeatureIdsAt(Object: point) -> [featureId, featuresId]`

This method takes an object with x and y and returns a list of features currently rendered by draws at that spot.

This is good for using mouse events to get information out of draw.

x and y must be from from pixel space, not latitude and longitude.

var featureIds = Draw.getFeatureIdsAt(20, 20);
console.log(featureIds)
//=> ['top-feature-at-20-20', 'another-feature-at-20-20']

`.getSelectedIds() -> [featureId, featuresId]`

This method returns the feature ids for all features currently in a selected state. If no features are currently selected than it will return an empty array.

`.getSelected() -> Object`

This method returns a FeatureCollection of all the selected features. If nothing is selected, it will return an empty FeatureCollection.

###.getSelectedPoints() -> [Object: GeoJSON]

This method returns all vertices currently in a selected state in an array of GeoJSON points.

###.getAll() -> Object

This method returns all features added to Draw in a single GeoJSON FeatureCollection.

Example:

Draw.add({ type: 'Point', coordinates: [0, 0] });
Draw.add({ type: 'Point', coordinates: [1, 1] });
Draw.add({ type: 'Point', coordinates: [2, 2] });
console.log(Draw.getAll());
// => {
//  type: 'FeatureCollection',
//  features: [
//    {
//      id: 'random-0'
//      type: 'Feature',
//      geometry: {
//        type: 'Point',
//        coordinates: [0, 0]
//      }
//    },
//    {
//      id: 'random-1'
//      type: 'Feature',
//      geometry: {
//        type: 'Point',
//        coordinates: [1, 1]
//      }
//    },
//    {
//      id: 'random-2'
//      type: 'Feature',
//      geometry: {
//        type: 'Point',
//        coordinates: [2, 2]
//      }
//    }
//  ]
//}

###.delete(String | Array<String> : id) -> Draw

This method takes an id or an array of ids and removes the corresponding features from Draw.

In direct_select mode, deleting the active feature will stop the mode and revert to the simple_select mode.

Example:

var feature = { type: 'Point', coordinates: [0, 0] };
var id = draw.add(feature)
Draw
  .delete(id)
  .getAll();
// => { type: 'FeatureCollection', features: [] }

###.deleteAll() -> Draw

This method removes all geometries in Draw.

Example:

Draw.add({ type: 'Point', coordinates: [0, 0] });
Draw
  .deleteAll()
  .getAll();
// => { type: 'FeatureCollection', features: [] }

`.set(Object: featureCollection) -> [featureId, featureId]`

This function takes a featureCollection and performs the required delete, create and update actions internally to make Draw represent this change. Effectively this is the same as Draw.deleteAll() followed by Draw.add(featureCollection) except that it doesn't effect performance as much.

Example:

var ids = Draw.set({type: 'FeatureCollection', features: [{
  type: 'Feature',
  properties: {},
  id: 'example-id',
  geometry: { type: 'Point', coordinates: [0, 0] }
}]});
// => ['example-id']

`.trash() -> Draw`

This invokes the current modes trash action. For the simple_select mode this deletes all active features. For the direct_select mode this deletes the active vertices. For the drawing modes, this cancels the current process.

This is different from delete or deleteAll in that it follows rules described by the current mode.

`.combineFeatures() -> Draw`

This invokes the current modes combineFeatures action. For the simple_select mode this function will combine all selected features into a multifeature, so long as they are all of the same geometry type. For example:

LineString, LineString => MultiLineString
MultiLineString, LineString => MultiLineString
MultiLineString, MultiLineString => MultiLineString

Calling this function on different geometry types will not cause any changes. For example:

Point, LineString => no action taken
MultiLineString, MultiPoint => no action taken

When called in the direct_select and drawing modes no action is taken. The current modes are also not exited.

`.uncombineFeatures() -> Draw`

This invokes the current modes uncombineFeatures action. For the simple_select mode this takes the currently selected features, and for each multi-feature selected, it will split it into its component feature parts. For example:

MultiLineString (of two parts) => LineString, LineString
MultiLineString (of three parts) => LineString, LineString, LineString
MultiLineString (of two parts), Point => LineString, LineString, Point
LineString => LineString

When called in the direct_select and drawing modes no action is taken. The current modes are also not exited.

`.getMode() -> Draw`

Returns Draw's current mode. For more about the modes, see below.

`.changeMode(String: mode, ?Object: options) -> Draw`

changeMode triggers the mode switching process inside Draw. mode must be one of the below strings. simple_select and direct_select modes accept an options object.

// `simple_select` options
{
  // Array of ids of features that will be initially selected
  featureIds: Array<string>
}

// `direct_select` options
{
  // The id of the feature that is directly selected (required)
  featureId: string
}

`.setFeatureProperty(String: featureId, String: property, Any: value) -> Draw`

Sets the value of a property on the indicated feature. This is good if you are using Draw as your primary data store in your application.

Events

Draw fires off a number of events. All of these events are namespaced with draw. and are emitted from the map object.

They are all triggered as the result of user interaction.

If you invoke a function in the Draw API, any event that directly corresponds with that function will not be fired. For example, if you invoke Draw.delete(..), there will be no corresponding draw.delete event, since you already know what you've done. Subsequent events may fire, though, that do not directly correspond to the invoked function. For example, if you have a one feature selected and then invoke Draw.changeMode('draw_polygon'), you will not see a draw.modechange event (because that directly corresponds with the invoked function) but you will see a draw.selectionchange event, since by changing the mode you deselected a feature.