Map | FacetWP

  • Description
  • FAQ
  • Screenshots
  • DEMO
  • Updates & Support

This add-on generates a map to display geocoded results. It can also filter results by showing only results within the map viewport.


This add-on generates a Map facet type, which works just like any other facet type.

The Data Source should be a custom field containing a comma-separated latitude, longitude.

Advanced Custom Fields has a Google Maps field type that provides geolocation. For the facet’s Data Source, choose the field underneath the “Advanced Custom Fields” header.

WP Job Manager plugin automatically stores geolocation data. Set the facet’s Data Source to geolocation_lat.

Google Maps API key

The map facet requires a valid Google Maps API key. After generating an API key, add it to Settings > Facet > Settings. Both the proximity facet and map facet will use this key.

Your API key needs to have the following API services enabled:

  • Geocoding API: required for the Proximity “Locate me” button
  • Maps JavaScript API: required for the map to render
  • Places API: required for the Proximity autocomplete box

Available options

Name Description
Other data source Choose a longitude field if stored separately from the latitude
Map Design Choose a design/color scheme for the map
Marker clustering This option will group markers into marker clusters (see below)
Ajax marker content Enable to load marker content via AJAX. Works best for maps with many markers, since it prevents all the marker content from loading all at once
Marker limit “Show all results” will show all markers that match the results, “Show current page results” will only display markers matching the results on the current page of paginated results
Map width / height Width and height of map. Use unitless for px, ex. 300, or with %, ex. 100%
Zoom min / max Set the zoom bounds between 1 (minimum zoom) and 20 (maximum zoom)
Default lat / lng / zoom Centers map to this location when there’s no map results

Add marker content

Enter display code for the content that displays in an info window popup when a marker is selected. The following example outputs the title, link, and excerpt.

  <a href="<?php the_permalink(); ?>" title="<?php the_title_attribute(); ?>">
    <?php the_title(); ?>
<?php the_excerpt(); ?>

IMPORTANT: marker content should NOT contain have_posts() or the_post()

The ‘Enable map filtering’ button

The purpose of map filtering is to refresh the results whenever the map is zoomed or panned.
So after clicking the button, then zooming or panning the map, only results within the map’s viewport are shown in the filtered listing. You can see this in action in the State Parks map demo.

Disable the ‘Enable map filtering’ button

Currently there is no setting to disable the ‘Enable map filtering’ button/functionality. If you don’t want this button to show, you can hide the button with CSS:

.facetwp-map-filtering { 
    display: none; 

Change the ‘Enable map filtering’ button text

The text of the ‘Enable map filtering’ button can be changed with this code:

add_filter( 'gettext', function ( $translated_text, $untranslated_text, $domain ) {
    if ( $translated_text == 'Enable map filtering' && 'facetwp-map-facet' == $domain ) {
        $translated_text = 'Your button text';
    return $translated_text;
}, 10, 3 );

Enable map filtering on load of the map

You can enable map filtering by default on load of the map with this code:


add_action( 'wp_footer', function () {
        (function ($) {
            $(document).on('facetwp-loaded', function () {
                if ('undefined' === typeof FWP_MAP) {
                var filterButton = $(".facetwp-map-filtering");
                if (!filterButton.hasClass('enabled') && 'undefined' == typeof FWP_MAP.enableFiltering) {
                    FWP_MAP.is_filtering = true;
                    FWP_MAP.enableFiltering = true;
}, 100 );

Common issues with ‘Enable map filtering’

If the ‘Enable map filtering’ button is not working, make sure you have not disabled auto_refresh. That also disabled the map from auto-refreshing.

Change the map type

The following sets the default map type to terrain:

add_filter( 'facetwp_map_init_args', function ( $args ) {
    $args['init']['mapTypeId'] = 'terrain'; // valid options are: roadmap, satellite, hybrid, terrain
    return $args;

Customize the marker pins

You can change the marker pin images with this code. Make sure to use transparent png’s or svg’s.

add_filter( 'facetwp_map_marker_args', function( $args, $post_id ) {
    $args['icon'] = get_template_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’s JS objects:

add_filter( 'facetwp_map_marker_args', function( $args, $post_id ) {
    $args['icon'] = [
        'url' => get_template_directory_uri() . '/assets/images/marker.png'; // set your theme image path here
        'scaledSize' => [
            'width' => 16,
            'height' => 16
    return $args;
}, 10, 2 );

Map clustering

If you have large numbers of markers in one area, you can enable the ‘marker clustering’ option. Marker clustering combines markers of close proximity into clusters, simplifying the display of markers on the map.

Set marker cluster to zoom in when clicking on it

The behaviour of the map after clicking on a marker cluster can be set to zoom into it with this code:

add_filter( 'facetwp_map_init_args', function ( $args ) {
    if ( isset( $args['config']['cluster'] ) ) {
        $args['config']['cluster']['zoomOnClick'] = true; // default: false

Set the maximum zoom level for a cluster to appear

The maximum zoom level that a marker can be part of a cluster can be set like this:

add_filter( 'facetwp_map_init_args', function ( $args ) {
    if ( isset( $args['config']['cluster'] ) ) {
        $args['config']['cluster']['maxZoom'] = 10; // default: 15

Set the minimum number of markers in a cluster

The minimum number of markers to be in a cluster before the markers are hidden and a count is shown, can be set like this:

add_filter( 'facetwp_map_init_args', function ( $args ) {
    if ( isset( $args['config']['cluster'] ) ) {
        $args['config']['cluster']['minimumClusterSize'] = 5; // default: 2

Set custom marker cluster images

You can change the marker cluster images with the following code:

if ( isset( $args['config']['cluster'] ) ) {
    $args['config']['cluster']['imagePath'] = get_template_directory_uri() . '/assets/img/googlemaps/m'; // set your own path to an image directory in your theme here
    $args['config']['cluster']['imageExtension'] = 'png';

For this to work, in the specified directory, you need to place 5 png’s with transparent backgrounds, each slightly bigger than the next, which show on different cluster sizes. The images need the following specific names and sizes to work:

m1.png (size: 53x53 px)
m2.png (size: 56x56 px)
m3.png (size: 66x66 px)
m4.png (size: 78x78 px)
m5.png (size: 90x90 px)

More marker clusterer options, methods and examples can be found here.

Map marker hooks

FacetWP provides javascript hooks to perform actions when markers are interacted with.

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[data-id="' + post_id + '"]').addClass('is-active');

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

On the flip side, if you want to find all markers associated with a POST_ID, you could use:

var markers = FWP_MAP.get_post_markers(THE_POST_ID);

More examples



  • Improved FacetWP 3.9 compatibility


  • Improved removed jQuery dependency


  • New added “Ajax marker content” UI option to choose between ajax-loaded and preloaded markers
  • Fixed switched from `init` to `facetwp_init` hook to prevent timing issues


  • Improved significant performance boost (esp. for maps with many markers)


  • Fixed issue causing “maxZoom” JS error


  • Changed use `FWP()->filtered_post_ids` if available
  • Fixed prevent infinite refresh when “Enable map filtering” is on


  • Fixed only load posts if the “Marker Content” box is filled (performance boost)


  • New `facetwp_map/fit_bounds` JS hook to disable fitBounds and manually center the map
  • Improved immediately trigger a refresh when the “Enable filtering” button is clicked
  • Improved replaced GMaps “scrollWheel” setting with “gestureHandling”
Shopping Cart
  • Your cart is empty.
Scroll to Top