@nazka/map-gl-js-spiderfy

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

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] [default: 0]

  • zoomIncrement - if minZoomLevel is not reached on cluster click, the map will zoom by this amount instead [number] [default: 2]

  • closeOnLeafClick - remove the spiderfication on leaf click [boolean] [default: true]

  • circleSpiralSwitchover - number of leaves required to switch from circle to spiral spiderfication [number] [default: 10]

  • circleOptions - options that are specific to circle spiderfications [object]

    • leavesSeparation - distance between the spiderfied leaves in pixels [number] [default: 50]

    • leavesOffset - moves the leaves relative to the parent cluster in pixels [array] [default: [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] [default: 25]

    • legLengthFactor - the growth factor of the next leg in pixels [number] [default: 2.2]

    • leavesSeparation - distance between the spiderfied leaves in pixels [number] [default: 30]

    • leavesOffset - moves the leaves relative to the parent cluster in pixels [array] [default: [0, 0]]

  • spiderLegsAreHidden - don't render the spider legs [boolean] [default: false]

  • spiderLegsWidth - the width of the spider legs in pixel [number] [default: 1]

  • spiderLegsColor - the color of the spider legs [string] [default: 1]

  • spiderLeavesLayout - your own style layout attributes ('icon-offset' can't be used) [object] [default: cluster layout]

  • spiderLeavesPaint - your own style paint attributes [object] [default: cluster paint]

  • maxLeaves - limits the amount of leaves that can be in a spiderfication [number] [default: 255]

  • renderMethod - set to "3D" for this experimental render feature [string] [default: 'flat']

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.

License

This package is published under the BSD-3-Clause License. Copyright (c) 2022, nazka mapps