@nazka/map-gl-js-spiderfy NPM

map-gl-js-spiderfy ·

Spiderfy plugin for maplibre-gl and mapbox-gl. This plugin creates the spiderfication in the canvas itself instead of on top of it. This allows for more advanced interactions with the map and its content. This plugin builds further upon the cluster functionality of maplibre and mapbox.

This opensource project is maintained by nazka mapps, we gladly welcome any contributions!

We try to stand out by:

compatibility with both mapbox-gl and maplibre-gl
rendering in the canvas (with 3D rendering support)
a lot of customizable properties and options (see advanced demo)

A nice extra, since the spiderfication is part of the canvas, generating screenshots of it is really easy

screenshot (15)

Demo examples

Maplibre ^4.0.0

map-gl-js-spiderfy basic demo - highlights what you can already achieve with little code
map-gl-js-spiderfy advanced demo - includes all spiderfy options to play around with

Mapbox and older Maplibre versions

map-gl-js-spiderfy basic demo - highlights what you can already achieve with little code
map-gl-js-spiderfy advanced demo - includes all spiderfy options to play around with

Usage

Install the npm package:

npm install @nazka/map-gl-js-spiderfy

Simple setup:

import Spiderfy from '@nazka/map-gl-js-spiderfy';

...

// create a new spiderfy object
const spiderfy = new Spiderfy(map, {
  onLeafClick: f => console.log(f),
  minZoomLevel: 12,
  zoomIncrement: 2,
});

// enable spiderfy on a layer
// IMPORTANT: the layer must have a cluster source
spiderfy.applyTo('markers');

Please refer to the demo examples first if you're having issues.

Docs

New Spiderfy instance

new Spiderfy(map, options)

Options

map - reference to a maplibre-gl or mapbox-gl instance object
options
- onLeafClick - allows to put an action on the clicked leaf function (feature, event)
- onLeafHover - allows to put an action on the hovered leaf function (feature, event)
- minZoomLevel - allows spiderfication starting from this zoom level number
- zoomIncrement - if minZoomLevel is not reached on cluster click, the map will zoom by this amount instead number
- closeOnLeafClick - remove the spiderfication on leaf click boolean
- circleSpiralSwitchover - number of leaves required to switch from circle to spiral spiderfication number
- circleOptions - options that are specific to circle spiderfications object
  - leavesSeparation - distance between the spiderfied leaves in pixels number
  - leavesOffset - moves the leaves relative to the parent cluster in pixels arraydefault: 0, 0]
- spiralOptions - options that are specific to spiral spiderfications, these interact with each other and will probably all require some tweaking when changing one of them object
  - legLengthStart - the starting length of the spider leg in pixels number
  - legLengthFactor - the growth factor of the next leg in pixels number
  - leavesSeparation - distance between the spiderfied leaves in pixels number
  - leavesOffset - moves the leaves relative to the parent cluster in pixels arraydefault: 0, 0]
- spiderLegsAreHidden - don't render the spider legs boolean
- spiderLegsWidth - the width of the spider legs in pixel number
- spiderLegsColor - the color of the spider legs string
- spiderLeavesLayout - your own style layout attributes ('icon-offset' can't be used) object
- spiderLeavesPaint - your own style paint attributes object
- maxLeaves - limits the amount of leaves that can be in a spiderfication number
- renderMethod - set to "3D" for this experimental render feature string

Functions

applyTo(layerId) apply the spiderfier on a layer function
- layerId maplibre/mapbox layer id string
unspiderfyAll() clears any active spiderfication from the map function

Contributing

If an issue has a help wanted tag this means you can pick it up, just let us know.

You will have to create a fork of this project with your own branch and work on there. Once that's done you can create a pull request on this repo. One of the maintainers will have a look at it and give the necessary feedback/questions or merge it into this project.

Take a look at this repo if you haven't made a contribution to a project on github yet.