X Buy Features Demo (Cars) Demo (Power Plants) Demo (Map) Showcase Add-ons Docs Changelog

Map Facet

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


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.

Common data sources:

    • Advanced Custom Fields has a Google Maps field type that provides geolocation. For the facet’s Data Source, choose the field name underneath the “Advanced Custom Fields” header.
    • WP Job Manager plugin automatically stores geolocation data. Set the facet’s Data Source to geolocation_lat.

Marker content

Enter display code for the content that displays 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()

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 clusters
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

Using a 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.

Changing the map type

The following sets the default map type to Terrain:

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

Customizing the marker pins

add_filter( 'facetwp_map_marker_args', function( $args, $post_id ) {
    $args['icon'] = 'https://URL/TO/marker.png';
    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' => 'https://URL/TO/YOUR/marker.png',
        'scaledSize' => [
            'width' => 16,
            'height' => 16
    return $args;
}, 10, 2 );

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



  • Fixed: issue causing “maxZoom” JS error


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


  • Fix: 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”


  • Better support for ACF repeater Google Map fields. When combined with a proximity facet, only markers within the correct radius will remain!


  • Fixed issue where map wouldn’t load when there are no initial results


  • Added support for multiple locations per post (e.g. ACF repeater sub-fields)
  • Added logic to tie a map marker to its associated result
  • Changed “Enable filtering” to “Enable map filtering”
  • Updated Markerclusterer.js


  • Changed `wp.hooks` to `FWP.hooks` due to conflict with WP 5.0


  • Map facet now requires FacetWP 3.2.0+
  • Fixed issue saving the “Other data source” setting


  • Fixed issue involving filtering across the Prime Meridian


  • Fixed issues with FWP.reset()
  • Compatibility fix for FacetWP 3.1.2+


  • Improved: skip map refreshes when not needed
  • Improved: re-center map on window.resize


  • New: added `facetwp_map_proximity_marker_args` filter
  • Improved: support marker cluster image extensions (props Roy Lodder)


  • Improved: removed unnecessary query
  • Fix: map width / height settings weren’t being respected
  • Fix: limit results to the active map