Map Facet FacetWP Add-on

The Map facet is highly customizable. This page gives an overview of possible customizations, among which:

To customize the behavior and icons of the built-in marker clusterer and Overlapping Marker Spiderfier features, see these separate pages:

Customize Google Maps API loading

Add URL parameters

When FacetWP loads a Google map, the script loading URL contains several specific URL parameters that determine which Google Map libraries are loaded and what your Google Maps API key is. The URL looks like this:

https://maps.googleapis.com/maps/api/js?libraries=places&key=YOUR_API_KEY&callback=Function.prototype

As is standard in URLs, all parameters must be preceded by an ampersand (&) character, except the first one directly following the ?. Note that the order of the parameters is not relevant, and that the callback parameter is required, even if there is no actual callback function (which is why FacetWP uses callback=Function.prototype).

Using the facetwp_gmaps_url filter, you can filter the whole URL and change these parameters, or pass additional ones to the Google Maps API. See the localization code snippet below for an example.

Localize your map

By default, the Google Maps API will attempt to automatically load the most appropriate language and region based on the user’s location or browser settings. However, if you want to explicitly set a fixed region and/or language for the map, you can use the region and language parameters.

The region parameter allows you to localize the behavior and features of the map, based on the country or region set. The language parameter parameters lets you translate the map’s user interface.

The following example sets the map’s region to The Netherlands, and the language to Dutch:

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_gmaps_url', function( $url) { $url = $url . '&region=NL&language=nl'; // Adds the 'region' and 'language' parameters to the end of the URL return $url; } );

Use your own Google Maps API script

If your theme or another plugin already loads a Google Maps API script, you’ll have to choose which script to use, as loading the Google Maps API multiple times on the page will lead to errors.

If you choose to use the script that is already there, make sure it loads the Places library that FacetWP needs (with the libraries=places parameter). To remove FacetWP’s Google Maps API script, you can use the facetwp_assets hook like this:

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_assets', function( $assets ) { unset( $assets['gmaps'] ); return $assets; });

Change the map type

Google maps can be displayed in four different basic map types:

  • roadmap displays the default road map view.
  • satellite displays Google Earth satellite images.
  • hybrid displays a mixture of normal and satellite views.
  • terrain displays a physical map based on terrain information.

The default map type is roadmap, which the user can change to the other map types with a Map Type Control (see below) in the left top corner of the map. You can set any of the four map types as default. The following code sets the map type to terrain:

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 ) { $args['init']['mapTypeId'] = 'terrain'; // valid options are: roadmap, satellite, hybrid, terrain return $args; });

Turn off the map controls

Google maps display several UI elements to allow user interaction with the map. These elements are known as “controls”.

The default controls can be individually, or all removed with the following code:

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 ) { $args['init']['zoomControl'] = false; // +- zoom control $args['init']['mapTypeControl'] = false; // roadmap / satellite toggle $args['init']['streetViewControl'] = false; // street view / yellow man icon $args['init']['fullscreenControl'] = false; // full screen icon /** this overwrites all 4 lines above and will disable ALL of the default ui icons instead of the individual icons above */ $args['init']['disableDefaultUI'] = true; // disable the default ui return $args; } );

Reposition the map controls

Besides turning them off, you can also reposition the map controls, with the code below.

You have to reposition each control separately. Use the control names from the previous code example, or check the controls documentation.

It does not work to pass the documented control positions directly to the Map facet. You have to pass the number of which it is an alias:

TOP_LEFT: 1, TOP_CENTER: 2, TOP: 2, TOP_RIGHT: 3, LEFT_CENTER: 4, LEFT_TOP: 5, LEFT: 5, LEFT_BOTTOM: 6, RIGHT_TOP: 7, RIGHT: 7, RIGHT_CENTER: 8, RIGHT_BOTTOM: 9, BOTTOM_LEFT: 10, BOTTOM_CENTER: 11, BOTTOM: 11, BOTTOM_RIGHT: 12, CENTER: 13

The following example moves the “Zoom Control” (the plus-minus buttons) to the left bottom position:

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 ) { $args['init']['zoomControl'] = true; $args['init']['zoomControlOptions']['position'] = 6; // 6 = LEFT_BOTTOM return $args; } );

Customize map gestures behavior

To influence how scrolling and touch events influence zooming and panning the map, you can use the gestureHandling map option.

If you set it to cooperative, scroll events and one-finger touch gestures scroll the page, and do not zoom or pan the map. Two-finger touch gestures will still pan and zoom the map.

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 ) { $args['init']['gestureHandling'] = 'cooperative'; // Default: 'auto' return $args; } );

See this Google Map section on gestureHandling for code examples and demo of all options.

Use a custom map style / design

The Map facet type offers four alternative styles besides the default look, which you can choose with the “Map design” setting.

If these styles are not what you are looking for, it is possible to design your own map style or download a pre-made style from a map style library. With a custom map style, you can not only change the color scheme, but also how and if map features like roads, administrative areas or points of interest are displayed, or not:

A simple greyscale custom Google map style
Custom map style “Subtle Greyscale Map” from SnazzyMaps.

Two websites where you can build your own or download a pre-made custom map style are:

To use a custom map style:

  1. Build or choose the map style in one of the mentioned websites;
  2. Copy or download the resulting JSON array (which begins and ends with square brackets);
  3. Replace the JSON array in the code example below, between the single quotes, with your copied / downloaded JSON array;
  4. Add the code to your (child) theme’s function.php.

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 ) { $args['init']['styles'] = json_decode( '[{"featureType":"administrative","elementType":"labels.text.fill","stylers":[{"color":"#444444"}]},{"featureType":"landscape","elementType":"all","stylers":[{"color":"#f2f2f2"}]},{"featureType":"poi","elementType":"all","stylers":[{"visibility":"off"}]},{"featureType":"road","elementType":"all","stylers":[{"saturation":-100},{"lightness":45}]},{"featureType":"road.highway","elementType":"all","stylers":[{"visibility":"simplified"}]},{"featureType":"road.arterial","elementType":"labels.icon","stylers":[{"visibility":"off"}]},{"featureType":"transit","elementType":"all","stylers":[{"visibility":"off"}]},{"featureType":"water","elementType":"all","stylers":[{"color":"#46bcec"},{"visibility":"on"}]}]' ); return $args; } );

Alternatively, you can download and install the SnazzyMaps WordPress plugin and select a pre-made custom style. If you connect an API key in the settings, you can also select your own custom styles made on the SnazzyMaps website.

Set a custom zoom level or location/center

To determine the map center and correct zoom level, the map uses Google Maps’ fitBounds function. On every refresh, the map automatically pans to the center of all found markers, and zooms to the zoom level where all found markers fit within the bounds of the map. There is no easy way to change the zoom level that fitBounds ends up using after a page load or refresh.

The Map facet does have a setting called “Fallback lat / lng / zoom” where you can enter a custom center (lat/lng) and/or zoom level. These values are only used as a fallback, when no results/markers are found. In all other situations, these settings have no effect because the map uses the fitBounds function.

However, with a bit of custom code, this behaviour can be overwritten, so you can actually use the “Fallback lat / lng / zoom” setting to set a custom center and zoom level on initial page load, or on every facet refresh.

First, set a custom lat/lng and zoom level in the Map facet settings.

Then add one of the following two code snippets to your (child) theme’s function.php:

Set a custom zoom level and location/center on initial page load only

To disable fitBounds and force the custom lat/lng and zoom settings on the initial page load only:

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

<?php add_action( 'facetwp_scripts', function() { ?> <script> document.addEventListener('facetwp-refresh', function() { if ('undefined' !== typeof FWP && 'undefined' !== typeof FWP.hooks) { FWP.hooks.addFilter('facetwp_map/fit_bounds', function(fit_bounds) { return FWP.loaded; // force the custom lat/lng/zoom only on initial page load }); } }); </script> <?php }, 100 );

Set a custom zoom level and location/center on every refresh

To disable fitBounds and force the custom lat/lng and zoom settings on initial page load and every facet refresh:

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

<?php add_action( 'facetwp_scripts', function() { ?> <script> document.addEventListener('facetwp-refresh', function() { if ('undefined' !== typeof FWP && 'undefined' !== typeof FWP.hooks) { FWP.hooks.addFilter('facetwp_map/fit_bounds', function(fit_bounds) { return false; // force the custom lat/lng/zoom on every refresh }); } }); </script> <?php }, 100 );

If you combine one of the above code snippets with Google Map’s restriction parameter, you can also restrict the map’s viewport to specified bounds.

To only set a custom zoom level on page load, see the two sections below:

Set a custom zoom level on initial page load only

If you want to only set a custom zoom level, and leave the lat/lng determined by the fitBounds function (as explained above) intact, the above solutions that use the “Fallback lat / lng / zoom” setting, will not work. This is because if you leave the fallback lat/lng empty, it will default to 0,0 and your map will load with that location as its center.

The following code will only set a custom zoom level, only on initial page load:

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> function setCustomZoom() { google.maps.event.addListenerOnce(FWP_MAP.map, 'tilesloaded', function(){ FWP_MAP.map.setZoom(5); // Custom zoom level, set only on first page load. document.removeEventListener('facetwp-maps-loaded', setCustomZoom); }); } document.addEventListener('facetwp-refresh', function() { if( ! FWP.loaded ) { // On first page load only. document.addEventListener('facetwp-maps-loaded', setCustomZoom); } }); </script> <?php }, 100 );

Set a custom zoom level on every refresh

The following code will (re)set a custom zoom level on every facet refresh of the map:

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() { google.maps.event.addListenerOnce(FWP_MAP.map, 'tilesloaded', function(){ FWP_MAP.map.setZoom(5); // Custom zoom level, set on each refresh. }); }); </script> <?php }, 100 );

Restrict the map viewport

A map with a viewport restricted by the bounds of New Zealand. No panning or zooming out is possible beyond the viewport.
A map with a viewport restricted by the bounds of New Zealand. No panning or zooming is possible beyond the viewport.

Instead of using the “Fallback lat/lng/zoom” in the Map facet’s settings, it is also possible to restrict the map’s viewport with Google Map’s restriction parameter. With this parameter set, the user cannot pan or zoom out beyond the specified viewport bounds. Manually zooming in is still possible, within the range set with the Zoom min/max setting.

The following code example restricts the map’s viewport to the bounds of New Zealand, and sets the center to Auckland.

To make this code work, it must be combined with the above snippet to disable the fitBounds function on every refresh, otherwise the map will still try to pan and scroll when using facets, which will lead to unexpected behavior.

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 ) { // Auckland New Zealand $args['init']['center'] = [ 'lat' => -36.8598108, 'lng' => 174.2117363 ]; // New Zealand bounds $args['init']['restriction'] = [ 'latLngBounds' => [ 'north' => -34.36, 'south' => -47.35, 'west' => 166.28, 'east' => -175.81 ], 'strictBounds' => false ]; $args['init']['zoom'] = 6; // Is used if no Fallback lat/lng and zoom are set in the Map facet settings. See explanation below. return $args; } );

There are a few settings that determine the zoom level that is used when the map loads with a restricted viewport: the zoom parameter in line 20 of above code, and the Fallback lat/lng/zoom setting in the Map facet settings. They influence each other as follows.

If you want the map to use the exact restricted viewport when it loads, don’t use the zoom parameter and leave the fallback zoom setting empty. Or, if you use any or both of them, make sure the zoom level is lower (zoomed out more) than the equivalent of the restricted viewport: the map will never zoom out more than the restricted viewport.

To zoom into the restricted viewport on page load, you can set a higher zoom level in one or both of these settings. Be aware that they override each other as follows:

  • Without the zoom parameter set, a fallback zoom level will determine the zoom parameter, also if no fallback lat/lng is set.
  • With the zoom parameter set, a fallback zoom level will override the zoom parameter, but only if a fallback lat/lng is also set.

Customize the marker pins

The simplest way to change the marker pin images is with the following code. Make sure to use a transparent PNG or SVG.

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_marker_args', function( $args, $post_id ) { $args['icon'] = get_stylesheet_directory_uri() . '/assets/images/marker.png'; // set your theme image path here return $args; }, 10, 2 );

For more flexibility, you could alternatively use arrays to mimic Google Map API’s JS objects:

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_marker_args', function( $args, $post_id ) { $args['icon'] = [ 'url' => get_stylesheet_directory_uri() . '/assets/images/marker.png', // set your theme image path here 'scaledSize' => [ 'width' => 16, 'height' => 16 ] ]; return $args; }, 10, 2 );

This also gives you access to other properties to fine-tune the position of the marker icon, like anchor and labelOrigin (to position marker labels). See Google maps documentation on the google.maps.Icon interface for an overview of available properties.

Customize the marker pins for selected posts only

The following example is the same as the previous one, but changes the marker pins only for specific posts:

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_marker_args', function( $args, $post_id ) { $myposts_with_custom_markers = array(101, 102, 103); // array with the post id's of posts that need a custom marker if ( in_array( $post_id, $myposts_with_custom_markers ) ) { $args['icon'] = [ 'url' => get_stylesheet_directory_uri() . '/assets/images/marker.png', // set your theme image path here 'scaledSize' => [ 'width' => 16, 'height' => 16 ] ]; } return $args; }, 10, 2 );

Customize the marker pins for each post category or term

You could select posts based on any post property available through the $post_id parameter. An example would be to give each post category/term a different marker pin, using has_category() or has_term():

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_marker_args', function( $args, $post_id ) { if ( has_term( 'my-term-slug', 'my-taxonomy', $post_id ) ) { // replace with your term slug and taxonomy $args['icon'] = [ 'url' => get_stylesheet_directory_uri() . '/assets/images/marker.png', // set your theme image path here 'scaledSize' => [ 'width' => 16, 'height' => 16 ] ]; } return $args; }, 10, 2 );

Customize the marker pins for posts of a certain post type

Another possibility is to check the post type of the post by its $post_id parameter, using get_post_type(). The following example checks if the post type is agriturismi. If it is, it uses a default hard-coded marker icon. If it is not, it gets the marker icon name from an ACF custom field with the get_field() function, and appends the .png extension. The snippet also shows how to use the /wp-content/uploads/ directory in the marker image URL:

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_marker_args', function( $args, $post_id ) { $upload_dir = wp_upload_dir(); // Get the /wp-content/uploads directory URL $post_type = get_post_type( $post_id ); // Get the post type of the marker's post if ( $post_type === 'agriturismi' ) { $custom_img = 'marker-agriturismi.svg'; } else { $custom_img = get_field( 'tipo_azienda', $post_id ) . '.png'; } $args['icon'] = [ 'url' => $upload_dir['baseurl'] .'/'. $custom_img, // Make sure this returns a valid URL 'scaledSize' => [ 'width' => 16, 'height' => 16 ] ]; return $args; }, 10, 2 );

With the following code, you can set an image (for example the post’s featured image) as the marker pin. This makes it possible to display for example company logos or user portraits on the map:

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_marker_args', function( $args, $post_id ) { if ( has_post_thumbnail( $post_id ) ) { $member_photo = get_the_post_thumbnail_url( $post_id, 'post-thumbnail' ); // Set your desired wp image size and adapt scaledSize below } else { $member_photo = get_home_url() . '/wp-content/uploads/default-member-photo.jpg'; // Use a fall-back image if a post does not have a featured image uploaded } $args['icon'] = [ 'url' => $member_photo, 'scaledSize' => [ 'width' => 50, 'height' => 50 ] ]; // $args['optimized'] = false; // Optional: forces DOM elements for marker images instead of Canvas. Only use this when needed, e.g. to reach marker <img> elements with CSS return $args; }, 10, 2 );

Adapt the scaledSize argument to the desired marker image’s width and height. To avoid image distortion, set a WP image size with the same size or proportions in the second parameter of the get_the_post_thumbnail_url() function. The image size defaults to post-thumbnail, but you can use any image size set in Settings > Media or your theme’s settings. Or you can create your own image size with add_image_size(). For more info about how image sizes in WordPress work, see this tutorial section.

Style marker pin images

Circular-styled marker pin images.
Circular-styled marker pin images.

If you try to style the marker pin images (set with above code), you’ll notice that they are hard to target with CSS, as they do not have a specific class.

A solution is to let your CSS target <img> tags within the map that have a src attribute that starts with (^=) your image directory, in this example /wp-content/uploads/. Make sure that your fallback image is also in the same directory.

The following snippet adds CSS that makes the marker pin images circular, with a 2px white border:

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( 'wp_head', function() { ?> <style> .facetwp-type-map img[src^="https://mysite.com/wp-content/uploads/"] { border-radius: 50%; /* circular */ border: 2px solid #fff !important; /* 2px white border */ box-sizing: border-box; /* make sure the border is within the set image dimension */ } </style> <?php }, 100 );

Be aware that there is one possible caveat with this approach: when you have a large number of markers, Google Maps automatically switches to using canvas to draw the marker images, to optimize performance. When that happens, there will be no <img> DOM elements that the above CSS can apply to.

The solution is to set the “optimized” flag to false in the marker options. To do so, you can use the following snippet, or add the argument to the snippet you already have.

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_marker_args', function( $args, $post_id ) { $args['optimized'] = false; // Forces DOM elements instead of Canvas return $args; }, 10, 2 );

Change the marker pins when an info window is open

It is possible the change the (custom) marker icon when an info window is clicked open. See the example below for how to accomplish that.

Add a marker label

Using the facetwp_map_marker_args filter, you can pass properties of the Google Maps MarkerLabel interface. This makes it possible to add a marker label above, below, or beside your marker.

The following example adds a marker label with the post title as text. Optionally, you can set a few other properties like fontSize and fontWeight.

The label will display at the exact origin of your marker, so with a marker already there it will be centered on top of the marker. To position the label relative to the marker, you can pass a custom class (in this example label-position):

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_marker_args', function( $args, $post_id ) { $labeltext = esc_html( get_the_title( $post_id ) ); // Fetch the post title. $args['label'] = [ 'text' => $labeltext, 'className' => 'label-position', // A custom class. // optional: 'color' => 'red', 'fontSize' => '40px', 'fontWeight' => 'bold', 'fontFamily' => 'Courier' ]; return $args; }, 10, 2 );

Using this custom class, the label can now be relatively positioned with a few lines of CSS. Note that to position the label above the marker, you can use a negative value for top:

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( 'wp_head', function() { ?> <style> .facetwp-type-map .label-position { position: relative; top: -40px; /* Use a negative value to position the label above the marker. And you can use 'bottom', 'left' and 'right'. */ } </style> <?php } );

As an alternative to positioning the label with CSS, if you are using custom markers pins, you can use the labelOrigin property to position the label. To position the label above the marker, use a negative value for y:

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_marker_args', function( $args, $post_id ) { $args['icon'] = [ 'url' => get_stylesheet_directory_uri() . '/assets/images/marker.png', // Set your theme image path here. 'scaledSize' => [ 'width' => 16, 'height' => 16 ], 'labelOrigin' => [ 'x' => 0, // You can use negative values. 'y' => -50 // Use a negative value to position the label above the marker. ] ]; return $args; }, 10, 2 );

Add a label and remove the marker pin

If you want to add a marker label, while removing the marker icon itself, you can use an empty icon argument (with a space between the quotes) to unset the marker icons:

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_marker_args', function( $args, $post_id ) { $labeltext = esc_html( get_the_title( $post_id ) ); // Fetch the post title. $args['label'] = [ 'text' => $labeltext, 'className' => 'label-position', // A custom class. // optional: 'color' => 'red', 'fontSize' => '40px', 'fontWeight' => 'bold', 'fontFamily' => 'Courier' ]; $args['icon'] = ' '; // Removes the marker icons. Note: for this to work, there needs to be a space between the quotes. return $args; }, 10, 2 );

Make (some) markers unclickable

If you need (some) markers to be unclickable, you can set their clickable marker argument to false with the facetwp_map_marker_args hook.

This makes all markers unclickable:

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_marker_args', function( $args, $post_id ) { $args['clickable'] = false; // make all markers unclickable return $args; }, 10, 2 );

The hook has access to the post ID of each marker it runs for, so you can check that post ID against an array of post IDs for which the markers must be unclickable:

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_marker_args', function( $args, $post_id ) { $disable_marker_click = array( 5648, 5678 ); // Create an array with the post IDs of posts with unclickable markers if ( in_array( $post_id, $disable_marker_click ) ) { $args['clickable'] = false; // Make this marker unclickable } return $args; }, 10, 2 );

Another approach is to use the $post_id to check the value of a custom field. For example, you could create an is_clickable True/False field with Advanced Custom Fields and get the value of that field for each marker’s post ID:

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_marker_args', function( $args, $post_id ) { if ( get_field( 'is_clickable', $post_id ) === false ) { $args['clickable'] = false; // Make this marker unclickable } return $args; }, 10, 2 );

Display a circle or other shape around (clicked) markers

Display a circle or other shape around clicked markers.
Display a circle (or other shape) around clicked markers.

The following code draws a circle around a marker when it is clicked. Note that instead of a circle, this could be any other type of shape/polygon supported by the Google Maps API.

You can customize the circle’s fill color and opacity, and its stroke color, opacity and weight. The circle’s size is determined by the radius value (in meters) set in line 22.

Clicking another marker will clear the previous circle. The code (optionally) also removes the circle when any marker’s info window is closed, and/or when you click anywhere on the map.

If you want to apply the code only to certain markers, you can use the clicked marker’s post_id to write a condition.

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> (function() { FWP.hooks.addAction('facetwp_map/marker/click', function(marker) { // Clear existing circle if it exists if ( 'undefined' !== typeof FWP_MAP.circle ) { FWP_MAP.circle.setMap(null); // Clear circle from map FWP_MAP.circle = null; // Remove circle instance entirely } // let post_id = marker.post_id; // The marker's post_id could be used to apply this code only to certain markers. let lat = marker.position.lat(); let lng = marker.position.lng(); FWP_MAP.circle = new google.maps.Circle({ center: { lat: lat, lng: lng }, radius: 25000, // Circle radius in meters fillColor: "#D93F7C", // Circle coloring fillOpacity: 0.25, // Circle opacity strokeColor: "#D93F7C", // Circle outline color strokeOpacity: 0.8, // Circle outline color strokeWeight: 2, // Circle outline thickness map: FWP_MAP.map }); // Optional: when an infoWindow is closed, clear the circle from the map google.maps.event.addListener(FWP_MAP.infoWindow, 'closeclick', function() { FWP_MAP.circle.setMap(null); }); // Optional: when the map is clicked anywhere, clear the circle from map google.maps.event.addListener(FWP_MAP.map, 'click', function(event) { FWP_MAP.circle.setMap(null); }); }); })(); </script> <?php }, 100 );

To draw a circle around each marker, without a click, you can do it as follows:

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 type="text/javascript"> (function() { document.addEventListener('facetwp-loaded', function() { // Get all markers let markers = FWP_MAP.markersArray; Object.keys(markers).forEach(function(key) { let value = markers[key]; let lat = value.position.lat(); let lng = value.position.lng(); FWP_MAP.circle = new google.maps.Circle({ center: { lat: lat, lng: lng }, radius: 25000, // Circle radius in meters fillColor: "#d93f7c", // Circle coloring fillOpacity: 0.25, // Circle opacity strokeColor: "#d93f7c", // Circle outline color strokeOpacity: 0.8, // Circle outline color strokeWeight: 2, // Circle outline thickness map: FWP_MAP.map }); FWP_MAP.circle.setMap(FWP_MAP.map); }); }); })(); </script> <?php }, 100 );

To display the Proximity facet radius as a circle on the map, see the example below.

Customize the Proximity facet marker pin

The default Proximity facet marker pin
The default Proximity facet marker pin.

If you are using the map with a Proximity facet, when a location is entered, a yellow location marker is displayed on the map.

With the following code, you can change the proximity marker pin’s path, color, opacity, scale, and anchor. The code example shows the default icon settings. All of these settings need to have a value.

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_proximity_marker_args', function( $args ) { $args['icon'] = [ 'path' => 'M8,0C3.582,0,0,3.582,0,8s8,24,8,24s8-19.582,8-24S12.418,0,8,0z M8,12c-2.209,0-4-1.791-4-4 s1.791-4,4-4s4,1.791,4,4S10.209,12,8,12z', 'fillColor' => 'gold', 'fillOpacity' => 0.8, 'scale' => 0.8, 'anchor' => [ 'x' => 8.5, 'y' => 32 ] ]; return $args; }, 10 );

You can also replace the default proximity marker pin with a custom marker image, with the following code. Make sure to use a transparent PNG or SVG.

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_proximity_marker_args', function( $args ) { $args['icon'] = get_stylesheet_directory_uri() . '/assets/images/marker.png'; // set your theme image path here return $args; }, 10 );

For more flexibility, you could alternatively use arrays to mimic Google Map API’s JS objects:

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_proximity_marker_args', function( $args ) { $args['icon'] = [ 'url' => get_stylesheet_directory_uri() . '/assets/images/marker.png', // set your theme image path here 'scaledSize' => [ 'width' => 16, 'height' => 16 ] ]; return $args; }, 10 );

This also gives you access to other properties to fine-tune the position of the marker icon, like anchor and labelOrigin (to position marker labels). See Google maps documentation on the google.maps.Icon interface for an overview of available properties.

Disable the Proximity facet marker pin

If you want to completely disable the Proximity marker pin, you can use this hook:

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_proximity_marker_args', '__return_false' );

If you have enabled marker clustering, you can also exclude the Proximity marker pin from the clustering behavior.

Display the Proximity radius as a circle on the map

Display the Proximity radius as a circle on the map.
Display the Proximity radius as a circle on the map.

The following code draws a circle shape on the map each time a location is entered in the Proximity facet. The circle’s radius will adapt automatically to the radius set in the Proximity facet.

You can customize the circle’s fill color and opacity, and its stroke color, opacity and weight. Make sure to replace my_proximity_facet with the name of your proximity facet in line 14, and set the correct number of units (kilometers or miles) in line 17, depending on the “Units of measurement” setting you have used.

Be aware that the map’s default fitBounds behavior will make the map zoom into the found locations when the Proximity facet is used. The circle’s edge will then end up outside or around the viewport of the map. If you want the entire circle to be always visible, you could set a maximum zoom level in the map’s Zoom min / max setting, or make the circle smaller than the Proximity radius (which will possibly cause some markers to be outside the circle). In some situations, it may be an idea to disable the fitBounds behavior entirely and set a custom zoom level and/or center.

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 type="text/javascript"> (function() { document.addEventListener('facetwp-loaded', function() { // Clear existing circle if it exists if ( 'undefined' !== typeof FWP_MAP.circle ) { FWP_MAP.circle.setMap(null); // Clear circle from map FWP_MAP.circle = null; // Remove circle instance entirely } let proximityfacet = FWP.facets['my_proximity_facet']; // Replace "my_proximity_facet" with the name of your Proximity facet let lat = parseFloat(proximityfacet[0]); let lng = parseFloat(proximityfacet[1]); let radius = parseFloat(proximityfacet[2]) * 1000; // For Kilometers. Use 1609.344 if you have set the Unit of measurement setting to Miles FWP_MAP.circle = new google.maps.Circle({ center: { lat: lat, lng: lng }, radius: radius, // Circle radius in meters fillColor: "#D93F7C", // Circle coloring fillOpacity: 0.25, // Circle opacity strokeColor: "#D93F7C", // Circle outline color strokeOpacity: 0.8, // Circle outline color strokeWeight: 2, // Circle outline thickness map: FWP_MAP.map }); if (proximityfacet.length) { FWP_MAP.circle.setMap(FWP_MAP.map); } }); })(); </script> <?php }, 100 );

To display a circle (or other shape) around (clicked) markers, see the example above.

Customize or overwrite the marker info window content

The marker info window content can be created in the Map facet’s “Marker content” setting field.

If this field is too limiting, or if you can’t reach certain data with it, you can use the facetwp_map_marker_args hook to output the marker info window content. Note that this will overwrite anything you have in the “Marker content” setting.

As $post_id is available in this hook, you can create or overwrite the content conditionally, only for specific posts:

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_marker_args', function( $args, $post_id ){ if ( $post_id == 5647 ) { // Optionally add a condition to check for specific post IDs $args['content'] = "my custom marker content"; // Create your custom marker infowindow content } return $args; }, 10, 2 );

One use case for this is if you use ACF Repeater fields to support multiple locations per post. With the “Marker content” field you can only get post data, but not the data for the separate locations within the repeater. This snippet shows how to get and output the repeater field data with the facetwp_map_marker_args hook.

How to use map marker hooks and functions

FacetWP provides several JavaScript hooks and functions to perform actions when markers are interacted with, or to perform actions on markers, for example when markers themselves, post (titles) in the result listing, or info windows close buttons are clicked.

Example 1: Add a class to the post which has its marker clicked

The following examples add the CSS class is-active to the active post (the post which has its corresponding marker clicked), which could be used to style it differently than the other posts.

The code also adds an optional scroll to the active post element (when its marker is clicked). If you don’t need that, just remove lines lines 19-24.

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> (function($) { if ('object' !== typeof FWP) { return; } FWP.hooks.addAction('facetwp_map/marker/click', function(marker) { // The post ID associated with the active marker var post_id = marker.post_id; // The following code adds the CSS class "is-active" to the active post, // assuming each result's HTML is structured similarly to: // <div class="post-item" data-id="123">Hello World!</div> $('.post-item').removeClass('is-active'); $('.post-item[data-id="' + post_id + '"]').addClass('is-active'); // Optional: scroll to the active post element var offset = $('.post-item[data-id="' + post_id + '"]').nodes[0].offsetTop; window.scrollTo({ top: offset, behavior: 'smooth', }); }); })(fUtil); </script> <?php }, 100 );

The above example assumes your posts (or post titles) have a class post-item and a data-id attribute containing the post ID. One way to accomplish this is by using the Listing Builder’s Dev mode and adding the following code to the “Display Code” field:

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

<?php while ( have_posts() ): the_post(); ?> <h3><a href="<?php the_permalink(); ?>" class="post-item" data-id="<?php the_id(); ?>"><?php the_title(); ?></a></h3> <?php endwhile; ?>

Now you can add some CSS to highlight the active listing item:

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() { ?> <style> .post-item.is-active { border: 1px solid red !important; } </style> <?php }, 100 );

If you have built your layout in the visual (non-Dev Mode) Listing Builder, it is a bit more difficult to get the post ID on each listing result in the grid. Currently, it is not possible to set it as class on the .fwpl-result container. But you can add it to its direct child div with class .fwpl-row.

To accomplish this, add a “Post ID” item to the listing. Give it the “Unique name” postid, and hide it:

Add a hidden Post ID item in a Listing Builder listing, to be used as dynamic tag.
Add a hidden Post ID item in a Listing Builder listing, to be used as dynamic tag.

Next, click the purple gear icon in the top center of your listing, which will open the main Row settings. Click the “Style” tab, and in the “CSS class” field at the bottom, enter: postid-{{ postid }}:

Add the post ID as class to each listing item's main row, with a dynamic tag.
Add the post ID as class to each listing item’s main row, with a dynamic tag.

This will add a class postid-# to each .fwpl-result > .fwpl-row item. Note that the {{ postid }} part is a so-called dynamic tag.

Next, add the following snippet. The code also adds an optional scroll to the active post element (when its marker is clicked). If you don’t need that, just remove lines lines 17-22.

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> (function($) { if ('object' !== typeof FWP) { return; } FWP.hooks.addAction('facetwp_map/marker/click', function(marker) { // The post ID associated with the active marker var post_id = marker.post_id; // The following code adds the CSS class "is-active" to the active post's main .fwpl-row child div $('.fwpl-result > .fwpl-row').removeClass('is-active'); $('.fwpl-result > .fwpl-row.postid-' + post_id).addClass('is-active'); // Optional: scroll to the active post element var offset = $('.fwpl-result > .fwpl-row.postid-' + post_id).nodes[0].offsetTop; window.scrollTo({ top: offset, behavior: 'smooth', }); }); })(fUtil); </script> <?php }, 100 );

Now you can add some CSS to highlight the active listing item:

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() { ?> <style> .fwpl-result > .fwpl-row.is-active { border: 1px solid red !important; } </style> <?php }, 100 );

Example 2: Open a marker’s info window on mouse hover

In addition to the click event, FacetWP also supports mouseover and mouseout events.

This example opens a marker’s info window on mouse hover:

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> (function($) { if ('object' !== typeof FWP) { return; } let isProgrammaticClick = false; FWP.hooks.addAction('facetwp_map/marker/mouseout', function(marker) { if ('undefined' !== typeof marker.content) { FWP_MAP.infoWindow.setContent(marker.content); } // For ajax marker info window content else if ('undefined' === typeof FWP_MAP.contentCache[marker.post_id]) { FWP_MAP.infoWindow.setContent('Loading...'); FWP_MAP.infoWindow.open(FWP_MAP.map, marker); return $.post(FWP_JSON.map.ajaxurl, { action: 'facetwp_map_marker_content', facet_name: FWP_JSON.map.facet_name, post_id: marker.post_id }, { dataType: 'text', contentType: 'application/x-www-form-urlencoded', done: (resp) => { FWP_MAP.contentCache[marker.post_id] = resp; FWP_MAP.infoWindow.setContent(resp); FWP.hooks.doAction('facetwp_map/marker/click', marker); // Trigger extra click to reposition marker/infowindow within viewport if (!isProgrammaticClick) { isProgrammaticClick = true; google.maps.event.trigger(marker, 'click'); isProgrammaticClick = false; } } }); } FWP_MAP.infoWindow.open(FWP_MAP.map, marker); }); })(fUtil); </script> <?php }, 100 );

Example 3: Trigger a marker click and info window on post click

The get_post_markers() function can be used to get markers by post ID and perform actions on them.

The following example triggers a marker click when you click on a post in the results list. It sets the map center to the marker’s position, opens its info window and sets a custom zoom level.

Make sure that the zoom level is higher than the marker clusterer’s bottom limit, otherwise the separate markers will not be shown.

The click event to use is spider_click because of the built-in Overlapping Marker Spiderfier. If you don’t have any markers close together, you can also use the click event.

This example assumes your post items (or post titles) have a class post-item and a data-id attribute containing the post ID. See the second code block in example 1 above to see how to accomplish that with the Listing Builder’s Dev mode.

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

<?php add_action( 'facetwp_scripts', function () { ?> <script> (function($) { $(document).on('click', '.post-item', function(e) { e.preventDefault(); // Necessary if '.post-item' is an <a> tag and you don't want it to open the post page itself. var postid = $(this).attr('data-id'); var marker = FWP_MAP.get_post_markers(postid); $.each( marker, function( key, value ) { FWP_MAP.map.setCenter({ lat: value.position.lat(), lng: value.position.lng() }); FWP_MAP.is_zooming = true; // Needed if you are using the "Enable map filtering" button FWP_MAP.map.setZoom(17); // Set a zoom level between 1 and 20. Make sure it is higher than the marker clusterer's bottom limit. // google.maps.event.trigger(value, 'click'); // If you don't have spiderfied markers google.maps.event.trigger(value, 'spider_click'); // If you have spiderfied markers. Will also work if you don't have spiderfied markers. }); }); })(jQuery); </script> <?php }, 100 );

Example 4: Change the marker icon when an info window is open

Change marker when info window is open.
Change the marker icon when an info window is open.

This code example changes the (custom) marker icon when an info window is opened and switches it back when it is closed. This can be useful to indicate an ‘active’ marker with a different design or color.

First, we define the ‘default’ and ‘active’ icons, using the properties of the google.maps.Icon interface. The specified ‘default’ icon and its properties should of course be the same as the custom icon you have specified with one of the above methods.

We use the facetwp_map/marker/click hook to detect a click on a marker and store its post_id to get its object. In that object we then set that marker’s icon to the ‘active’ version, with the setIcon() method.

We use Google Map API’s closeclick event to detect the closing of the info window. When that happens, or when the map is clicked anywhere (causing all info windows to close), or when another marker is clicked, we use FacetWP’s get_post_markers function and pass it the stored active marker’s post_id to get the that marker’s object so we can switch its icon back to the original one:

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> (function($) { if ('object' !== typeof FWP) { return; } // Change URL to the default marker icon let icon_default = { url: '/wp-content/themes/storefront/mapicons/m3.png', scaledSize: { width: 40, height: 40 } }; // Change URL to the alternative, 'active' icon let icon_active = { url: '/wp-content/themes/storefront/mapicons/m4.png', scaledSize: { width: 40, height: 40 } }; $(function() { FWP.hooks.addAction('facetwp_map/marker/click', function(marker) { // Check if another marker is already active. If so set to default icon if (window.marker_post_id) { let post_id = window.marker_post_id; let marker = FWP_MAP.get_post_markers(post_id)[0]; marker.setIcon(icon_default); // or use marker.setIcon(null); for the default pin } // Set the clicked marker to have the 'active' icon window.marker_post_id = marker.post_id; marker.setIcon(icon_active); }); // When an infoWindow is closed revert its marker to the default icon google.maps.event.addListener(FWP_MAP.infoWindow, 'closeclick', function() { let post_id = window.marker_post_id; let marker = FWP_MAP.get_post_markers(post_id)[0]; marker.setIcon(icon_default); // or use marker.setIcon(null); for the default pin }); // When the map is clicked anywhere, revert the active marker to the default icon google.maps.event.addListener(FWP_MAP.map, 'click', function(event) { if (window.marker_post_id) { let post_id = window.marker_post_id; let marker = FWP_MAP.get_post_markers(post_id)[0]; marker.setIcon(icon_default); // or use marker.setIcon(null); for the default pin } }); }); })(jQuery); </script> <?php }, 100 );

How to add a map to single posts or pages

We often get the question if it is possible to use the Map add-on to show a map on a single page, post, or custom post type post. A use case would be to show the location of a store, hotel, restaurant, or event.

This is possible, and actually not very complicated. Just follow the steps described in this tutorial.

More examples

See also

Last updated: February 11, 2025