Map Facet FacetWP Add-on

This page gives an overview of possible customizations of the built-in “Overlapping Marker Spiderfier” (OMS) feature of the Map facet.

What is Overlapping Marker Spiderfier?

Overlapping marker with (almost) the same location will fan-out ('spiderfy') in a circle or spiral on click.
Overlapping marker with (almost) the same location will fan-out (“spiderfy”) in a circle or spiral on click.

The Map facet has a feature that helps deal with markers that are very close together or overlap because they share (almost) the same latitude/longitude.

The built-in “Overlapping Marker Spiderfier JavaScript libary” makes markers fan-out (“spiderfy”) into a circle with spokes, on click. Larger numbers (by default more than 8) will fan out into a more space-efficient spiral.

Overlapping Marker Spiderfier plays nice with marker clustering: once you get down to a zoom level where clusters de-cluster into individual markers, these markers will then spiderfy if they are (almost) in the same location.

You may need to adapt the maxZoom parameter on the clusterer though, to ensure that it doesn’t cluster close markers all the way to the level that spiderfying would be more helpful behavior.

OMS is enabled by default, and cannot be disabled.

Customize Overlapping Marker Spiderfier options

The Overlapping Marker Spiderfier library that FacetWP uses, has several useful options that determine how the ‘spider parts’ look and behave.

For example, setting the keepSpiderfied option to false overrides the default behavior where the currently spiderfied marker stays ‘spiderfied’ when it is clicked.

And the circleSpiralSwitchover option sets the number of markers at which the marker configuration turns into a spiral instead of a circle.

You can also set the leg length, leg thickness and several spiral properties. The code below shows some examples:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_filter( 'facetwp_map_init_args', function( $args ) {

  if ( isset( $args['config']['spiderfy'] ) ) {

    // 'Unspiderfy' when clicking a 'spiderfied' marker
    $args['config']['spiderfy']['keepSpiderfied'] = false; // (FacetWP's) default: true. When set to false, when you click a spiderfied marker, the markers unspiderfy before any other action takes place. FacetWP sets this to true, so that the currently spiderfied marker stays spiderfied when clicked. 

    // Do not 'unspiderfy' when clicking an empty spot on the map
    $args['config']['spiderfy']['ignoreMapClick'] = true; // default: false

    // Set the pixel radius within which a marker is considered to be overlapping a clicked marker.
    $args['config']['spiderfy']['nearbyDistance'] = 30; // default: 20

    // Switch from circular to spiral above 11 markers instead of above 8
    $args['config']['spiderfy']['circleSpiralSwitchover'] = 11; // default: 8

    // Set spider leg length when circular
    $args['config']['spiderfy']['circleFootSeparation'] = 40; // default: 23

    // Set spider leg length and other settings when spiral
    $args['config']['spiderfy']['spiralFootSeparation'] = 40; // default: 26
    $args['config']['spiderfy']['spiralLengthStart']    = 15; // default: 11
    $args['config']['spiderfy']['spiralLengthFactor']   = 6; // default: 4

    // Set spider leg thickness
    $args['config']['spiderfy']['legWeight'] = 3; // default: 1.5

  }
  return $args;
} );

Note that the FacetWP Map facet sets the following options to true by default, overriding the defaults mentioned in the Overlapping Marker Spiderfier library’s documentation:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
// FacetWP Map facet Spiderfier defaults:
'spiderfy' => [
  'markersWontMove'   => true,
  'markersWontHide'   => true,
  'basicFormatEvents' => true,
  'keepSpiderfied'    => true
]

Customize spider leg colors

The following example shows how to set the color and highlight color of the spider legs. The colors need to be set for each map type separately. This example only sets the colors for the ROADMAP map type. See the defaults and map type options here.

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_action( 'facetwp_scripts', function () {
  ?>
  <script>
    document.addEventListener('facetwp-maps-loaded', function() {
      if ('undefined' !== typeof FWP_MAP) {
        var mti = google.maps.MapTypeId;
        FWP_MAP.oms.legColors.usual[mti.ROADMAP] = '#cc52ab'; // Normal leg color. Default: '#444'
        FWP_MAP.oms.legColors.highlighted[mti.ROADMAP] = '#6233ca'; // Highlight leg color. Default '#f00'
      }
    });
  </script>
  <?php
}, 100 );

Customize spiderfiable and/or spiderfied marker icons

It is possible to use different marker icons for spiderfiable and/or spiderfied markers.

The OverlappingMarkerSpiderfier library gives markers specific status values. Which of these status values are available depends on how the basicFormatEvent option is set. FacetWP sets this option to true by default (which is better for performance). In this situation, the following two status values are available:

How to use custom JavaScript code?
JavaScript code can be placed in your (child) theme's main JavaScript file. Alternatively, you can add it manually between <script> tags in the <head> section of your (child) theme's header.php file. You can also load it with a hook in your (child) theme's functions.php file, or in the Custom Hooks add-on. To load the code only on pages with facets, use the facetwp_scripts hook. To load it on all pages, use wp_head or wp_footer. Or you can use a code snippets plugin. More info
// Marker status values with basicFormatEvent = true (FacetWP default)
OverlappingMarkerSpiderfier.markerStatus.SPIDERFIED
OverlappingMarkerSpiderfier.markerStatus.UNSPIDERFIED

The following code example uses the format event listener to listen for the SPIDERFIED marker status. It sets a custom icon for spiderfied markers, and resets it to the default icon again when the markers are unspiderfied. To set the marker icons, the code uses the Google Maps setIcon() method which can take a range of Icon options.

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_action( 'facetwp_scripts', function () {
  ?>
  <script>
    document.addEventListener('facetwp-maps-loaded', function() {
      if ('undefined' !== typeof FWP_MAP.oms) {
        FWP_MAP.oms.addListener('format', function (marker, status) {

          let iconURL = status == OverlappingMarkerSpiderfier.markerStatus.SPIDERFIED ? 'icon_spiderfied.png' : null;
          if (iconURL) {
            marker.setIcon({
              url: '/wp-content/themes/my-theme/mapicons/' + iconURL, // Set path to your icons
              // .. other icon options. See: https://developers.google.com/maps/documentation/javascript/reference/marker#Icon
            });
          } else {
            marker.setIcon(null); // Set the default marker icon
          }

        });
      }
    });
  </script>
  <?php
}, 100 );

You may be tempted to also set a custom icon for unspiderfied icons with the above code, using the UNSPIDERFIED status. However, status values are only set after clicking a marker. So a custom unspiderfied icon will only show after clicking an already spiderfied icon, not before clicking it.

This can be solved by setting the basicFormatEvent option to false. In this situation, the following three status values are available:

How to use custom JavaScript code?
JavaScript code can be placed in your (child) theme's main JavaScript file. Alternatively, you can add it manually between <script> tags in the <head> section of your (child) theme's header.php file. You can also load it with a hook in your (child) theme's functions.php file, or in the Custom Hooks add-on. To load the code only on pages with facets, use the facetwp_scripts hook. To load it on all pages, use wp_head or wp_footer. Or you can use a code snippets plugin. More info
// Marker status values with basicFormatEvent = false
OverlappingMarkerSpiderfier.markerStatus.SPIDERFIED
OverlappingMarkerSpiderfier.markerStatus.SPIDERFIABLE
OverlappingMarkerSpiderfier.markerStatus.UNSPIDERFIABLE

This makes it possible to set a spiderfied icon and a spiderfiable icon. And even an unspiderfiable icon (icons that will not spiderfy). You can see this in this demo (source code) that uses a different icon for all three status values.

The following code shows how to accomplish this. It consists of two parts:

Part 1 sets basicFormatEvent option to false: 

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
// Part 1. Needed to have these 3 marker status values:
// SPIDERFIED
// SPIDERFIABLE
// UNSPIDERFIABLE

add_filter( 'facetwp_map_init_args', function( $args ) {
  if ( isset( $args['config']['spiderfy'] ) ) {
    $args['config']['spiderfy']['basicFormatEvents'] = false; // FacetWP's default: true
  }
  return $args;
} );

Part 2 uses the format event listener to listen for the three available marker status values, and sets a different icon for all three.

Note that if your Map facet has the “Marker clustering” setting enabled, it is important to include lines 13-19. These lines makes sure the markerspidering format event is also triggered after zooms and cluster clicks (see this bug). If Marker clustering is disabled, make sure to remove lines lines 13-19.

To set the marker icons, the code uses the Google Maps setIcon() method which can take a range of Icon options.

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
// Part 2. Set a different icon for spiderfied, spiderfiable and unspiderfiable icons.
// Demo: https://github.com/jawj/OverlappingMarkerSpiderfier/blob/gh-pages/demo-2.html
// Status values: https://github.com/jawj/OverlappingMarkerSpiderfier?tab=readme-ov-file#marker-events

add_action( 'facetwp_scripts', function () {
  ?>
  <script>

    document.addEventListener('facetwp-maps-loaded', function() {

      if ('undefined' !== typeof FWP_MAP.oms) {

        // Add this part only if the Map facet's 'Marker clustering' setting is enabled.
        // It re-triggers the format event status values after zooms and cluster clicks.
        // See: https://github.com/jawj/OverlappingMarkerSpiderfier/issues/103#issuecomment-327900374
        // Remove this part if the Map facet's 'Marker clustering' setting is disabled.
        google.maps.event.addListener(FWP_MAP.map, 'idle', () => {
          Object.getPrototypeOf(FWP_MAP.oms).h.call(FWP_MAP.oms); // .h is minified function name of formatMarkers()
        });

        FWP_MAP.oms.addListener('format', function (marker, status) {

          let iconURL = status == OverlappingMarkerSpiderfier.markerStatus.SPIDERFIED ? 'icon_spiderfied.png' :
            status == OverlappingMarkerSpiderfier.markerStatus.SPIDERFIABLE ? 'icon_spiderfiable.png' :
              status == OverlappingMarkerSpiderfier.markerStatus.UNSPIDERFIABLE ? 'icon_unspiderfiable.png' :
                null;

          if (iconURL) {
            marker.setIcon({
              url: '/wp-content/themes/my-theme/mapicons/' + iconURL, // Set path to your icons
              // .. other icon options. See: https://developers.google.com/maps/documentation/javascript/reference/marker#Icon
            });
          } else {
            marker.setIcon(null); // Set the default marker icon
          }

        });
      }
    });
  </script>
  <?php
}, 100 );

More examples

See also

Last updated: February 4, 2025