<!-- ########################################################################## NOTE TO CONTRIBUTOR: this README is automatically generated from build/readme.template.md. Should you need to modify the README, please make your modifications on the template file. ########################################################################### -->

Leaflet.FeatureGroup.SubGroup

Creates a Leaflet Feature Group that adds its child layers into a parent group when added to a map (e.g. through L.Control.Layers).

Typical usage is to dynamically add/remove groups of markers from Marker Cluster.

Leaflet.markercluster plugin provides beautiful animated Marker Clustering functionality.

Leaflet is the leading open-source JavaScript library for mobile-friendly interactive maps.

Size: 2 kB minified, < 1 kB gzipped.

Requirements

Requires Leaflet ^1.0.0

For Leaflet ~0.7.7 use the v0.1.2 release or the leaflet-0.7 branch

Optional: Leaflet.markercluster plugin

Demos

• SubGroup with standard L.Control.Layers and MarkerCluster
• SubGroup with standard L.Control.Layers to display Nested Groups

Usage instructions

Quick Guide

HTML:

<!-- after Leaflet script -->
<script src="leaflet.featuregroup.subgroup.js"></script>

JavaScript:

var map = L.map("map"),
  parentGroup = L.markerClusterGroup(options), // Could be any other Layer Group type.
  // This is where the magic happens!
  mySubGroup = L.featureGroup.subGroup(parentGroup, arrayOfMarkers);

parentGroup.addTo(map);
mySubGroup.addTo(map);

Now adding the sub-group to the map adds clustered markers!

It should virtually be compatible with any LayerGroup plugin, not only MarkerCluster.

Installing the sub-plugin

Local copy

1. Download the "<a href="https://github.com/ghybs/Leaflet.FeatureGroup.SubGroup/releases/download/v1.0.2/leaflet.featuregroup.subgroup.js">leaflet.featuregroup.subgroup.js</a>" file from the v1.0.2 release.
2. Place the file alongside your page.
3. Add the script tag (see Quick Guide > HTML) to your page after Leaflet script.

CDN

You can alternatively use the free unpkg CDN service, but keep in mind that it "is a free, best-effort service and cannot provide any uptime or support guarantees".

<!-- After Leaflet script -->
<script src="https://unpkg.com/leaflet.featuregroup.subgroup@1.0.2/dist/leaflet.featuregroup.subgroup.js"></script>

npm

1. Add this package to your project:

   $ npm install leaflet.featuregroup.subgroup --save
   

2. If you are using a bundling tool, import in your JavaScript. It only performs the side effect of attaching to the global L namespace, so you do not need to store it into a local variable or import a namespace.

   require("leaflet.featuregroup.subgroup");
   // Or with ES6:
   import "leaflet.featuregroup.subgroup";
   

Creation

Simply use the L.featureGroup.subGroup factory instead of your regular L.featureGroup or L.layerGroup:

var mySubGroup = L.featureGroup.subGroup(parentGroup);

mySubGroup.addTo(map);

Do not forget to add the parent group to your map.

API Reference

Creation

| Factory | Description | | :-------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------- | | L.featureGroup.subGroup( <ILayer> parentGroup?, <ILayer[]> layersArray? ) | Creates a sub-group with events, optionally given a parent group and an initial array of child layers. |

Methods

| Method | Returns | Description | | :----------------------------------------------- | :--------- | :------------------------------------------------------------------------------------------------------------------------------- | | setParentGroup( <ILayer> parentGroup ) | this | Changes the parent group into which child markers are added to / removed from. | | setParentGroupSafe( <ILayer> parentGroup ) | this | Removes the current sub-group from map before changing the parent group. Re-adds the sub-group to map if it was before changing. | | getParentGroup() | <ILayer> | Returns the current parent group. |

SubGroup does not provide any extra option or event beyond what L.LayerGroup and L.FeatureGroup already provide.

Limitations

If you change the parent group while the sub-group and/or its child markers are still on map, unexpected behaviour of the previous and/or new parent groups can happen.

Make sure the sub-group and its child layers are removed from map before changing the parent group, or use the setParentGroupSafe method instead.

License

Leaflet.FeatureGroup.SubGroup is distributed under the BSD 2-clause "Simplified" License, like Leaflet.