npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@stereobooster/leaflet-freedraw

v2.12.0

Published

Zoopla inspired freehand polygon creation using Leaflet.js.

Downloads

4

Readme

FreeDraw allows the free-hand drawing of shapes on your Leaflet.js map layer – providing an intuitive and familiar UX for creating geospatial boundaries similar to Zoopla and others. Included out-of-the-box is the concaving of polygons, polygon merging and simplifying, as well as the ability to add edges and modify existing shapes. Note: For drawing polylines instead, try L.Pather.

Travis   npm   Bower   MIT License

  • npm: npm i leaflet-freedraw
  • Bower: bower i leaflet-freedraw
  • JSFiddle: https://jsfiddle.net/0dzhs5Lg/3/

Table of Contents

  1. Browser Support
  2. Getting Started
  3. Markers
  4. Modes
  5. Options
  6. Classes
  7. Methods
  8. Predefined Polygons

FreeDraw Screenshot

Browser Support

Getting Started

FreeDraw functions as a standard Leaflet module, meaning you initialise it and add it to your map layer via the addLayer function on your map instance – when you instantiate FreeDraw you can pass a set of options for behaviour customisation.

import L from 'leaflet';
import FreeDraw from 'leaflet-freedraw';

const map = new L.Map(node);
const freeDraw = new FreeDraw();

map.addLayer(freeDraw);

By attaching FreeDraw to your map layer, an SVG node will be appended to the DOM, and mouse event listeners will be attached to the map instance for creating and managing the geospatial polygons.

Adding Markers

When a user creates a polygon an event is fired on the map instance called markers which you can listen for by using the native Leaflet on function.

freeDraw.on('markers', event => {
    console.log(event.latLngs);
});

Note: You can obtain the event type through the event.eventType field – such as create, edit, etc...

Once you have received the latitude and longitude values the next step would likely be to perform any necessary geospatial queries, and then render the relevant markers onto the map – for this you could use L.Marker and the native addTo method for placing markers on the map – however the important take-away is that FreeDraw doesn't concern itself with marker placement, as this is sufficiently covered by Leaflet.

Setting Modes

By default the mode is ALL which means all actions can be performed on the FreeDraw layer — create, edit, delete, and append — you're able to modify the mode at any time by using the mode method, or upon instantiation by passing an object as the first argument.

import L from 'leaflet';
import FreeDraw, { CREATE, EDIT } from 'leaflet-freedraw';

const map = new L.Map(node);
const freeDraw = new FreeDraw({
    mode: CREATE | EDIT
});

By passing in the mode as CREATE | EDIT you're only allowing the user to create and edit polygons, they are not able to append edges, nor delete them. You may use the mode method post-instantiation to modify the mode at any time – in the case below to also allow deleting of polygons.

// Allow create, edit and delete.
freeDraw.mode(CREATE | EDIT | DELETE);

// Allow everything except create.
freeDraw.mode(ALL ^ CREATE);

// Allow nothing.
freeDraw.mode(NONE);

Note: Invoking mode without passing a mode simply returns the current mode.

Passing Options

All of the following options can be passed in when instantiating FreeDraw in the same way that we pass mode in the previous examples.

| Option | Default | Result | | ---------------------- |------------- | ------------------------------------ | | mode | ALL | Modifies the default mode. | | smoothFactor | 0.3 | By how much to smooth the polygons. | | elbowDistance | 10 | Factor to determine when to delete or when to append an edge. | | simplifyFactor | 1.1 | By how much to simplify the polygon. | | mergePolygons | true | Whether to attempt merging of polygons that intersect. | | concavePolygon | true | Whether to apply the concaving algorithm to the polygons. | | maximumPolygons | Infinity | Maximum number of polygons to be added to the map layer. | | notifyAfterEditExit | false | Whether to defer markers event until after exiting EDIT mode. | | leaveModeAfterCreate | false | Whether to exit CREATE mode after each polygon creation. | | strokeWidth | 2 | Size of the stroke when drawing. |

By using the options above we can tweak how FreeDraw functions – whilst some of the options have obvious effects, others are much more tweak and see based on your expected outcome – such as the subjective simplifyFactor and elbowDistance options.

Classes

Depending on the current modes active on the map instance, the relevant classes are applied to the map container that you instantiated L.Map with – by using these class names it allows you to tailor the UX to the current mode, such as changing the cursor to crosshair when the user is allowed to create polygons.

| Class Name | Mode | | ------------------- |------------- | | mode-none | NONE | | mode-create | CREATE | | mode-edit | EDIT | | mode-delete | DELETE | | mode-append | APPEND |

.map.mode-create {
    cursor: crosshair;
}

From the above example if the current mode is CREATE | EDIT | APPEND then the three class names that will be present on the map node will be mode-create, mode-edit and mode-append, allowing you to provide a better UX from within your attached stylesheet.

Bundled Methods

With the instance of freeDraw there are certain methods for manipulating FreeDraw directly, such as creating polygon from a set of latitude and longitude values.

| Method | Yields | Result | | ------------------- |------------- | -------------------------------------------------------------- | | create | Array | Creates a polygon by passing an array of LatLngs | | remove | void | Removes a polygon that is yielded from create | | clear | void | Clears all polygons from the current instance | | mode | Number | Sets and retrieves the current mode. | | cancel | void | Cancels the current create action – such as on escape. | | size | Number | Yields the number of polygons on the map layer. | | all | Array | Enumerate all of the current polygons for the current layer |

When using the create method to create polygons from an array of latitude and longitude values, the CREATE mode is disregarded, which means it doesn't need to be enabled to create to succeed – if you would like such behaviour then you could simply assert that CREATE is enabled.

import L, { LatLng } from 'leaflet';
import FreeDraw from 'leaflet-freedraw';

const map = new L.Map(node);
const freeDraw = new FreeDraw();

// Create a polygon based on the given lat/long values.
const polygons = freeDraw.create([
    new LatLng(51.50046151184328, -0.08771896362304689),
    new LatLng(51.50067523261736, -0.09175300598144533),
    new LatLng(51.50329323076107, -0.09106636047363283),
    new LatLng(51.50409462869737, -0.08763313293457033)
]);

// Remove the created polygons from the map.
polygons.forEach(polygon => freeDraw.remove(polygon));

// Alternatively you could have cleared ALL polygons.
freeDraw.clear();

Note: create method returns an array of polygons, as often it may yield more than one.

In the case of the cancel method it's often desirable to cancel the creation of the polygon when the escape key is pressed – for this you simply need to attach an event to the document.body.

document.addEventListener('keydown', event => {

    // Cancel the current action when the escape key is pressed.
    event.key === 'Escape' && freeDraw.cancel();

});

Predefined Polygons

You can add polygons to the map layer at any point by using the create method. You must remember to setup FreeDraw through Leaflet, rather than instantiating FreeDraw without tying it to a Leaflet map instance.

freeDraw.create([
    new L.LatLng(51.50046151184328, -0.08771896362304689),
    new L.LatLng(51.50067523261736, -0.09175300598144533),
    new L.LatLng(51.50329323076107, -0.09106636047363283),
    new L.LatLng(51.50409462869737, -0.08763313293457033)
]);