Map
Create maps as (filterable!) facets
This add-on adds a Map facet type, which works just like any other facet type. The generated map displays geocoded results and can also filter results by showing only results within the map viewport.
Combine a Map facet with a Proximity facet
A Map facet can be combined well with a Proximity facet, which returns results within a chosen radius from a specified location.
When a location and radius are set (or changed) with the Proximity facet, the map will automatically zoom in or out, showing the locations that are within the radius of the set location.

If the Proximity facet is in use, it will display a yellow marker pin at the set location. This marker pin can be customized, disabled, or excluded from marker clustering behavior).
See our Advanced Map customization page for more things you can do with the map and the Proximity facet/marker.
Available options
Name | Description |
---|---|
Data source | The Data source should be a custom field containing a comma-separated latitude, longitude . Or – if you use a separate custom field for the longitude – only a latitude . See below for more info. |
Longitude | Choose a custom field to use for the longitude value, if stored separately from the latitude (optional). See below for more info. |
Map design | Choose a design / style / color scheme for the map. See the Advanced Maps customizations page to learn how to use your own map styles. |
Enable filtering button | The button text of the “Enable map filtering” button. Note: this text is translatable with the facetwp_i18n hook. The default text is also translatable with a translation plugin or with a gettext filter. |
Reset button | The button text of the “Reset” button, which appears after clicking the “Enable map filtering” button. Note: this text is translatable with the facetwp_i18n hook. The default text is also translatable with a translation plugin or with a gettext filter. |
Marker clustering | This option will group markers that are close to each other into marker clusters, from a certain zoom level. See the Advanced Maps customizations page for ways to customize marker clustering behavior. |
Ajax marker content | Enable to dynamically 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 |
|
Map width / height | Width and height of map. Without units, px is assumed: e.g. 300 is the same as 300px . Use other CSS units if needed, e.g. 100% for responsive full width of the parent container. Note: don’t use 100% for the height if the map’s container does not have a fixed height, else the map will have no height and will not show. |
Zoom min / max | Set the minimum and maximum zoom level. The values must be a number between 1 (minimum zoom) and 20 (maximum zoom). |
Fallback lat / lng / zoom: | Set a fallback location (lat/lng) and/or zoom level. The zoom level must be a number between 1 (minimum zoom) and 20 (maximum zoom). These settings are only used when no results/markers are found. With some customization, this setting can also be used to set a default custom center and/or zoom level on load of the map. |
Marker content | Enter display code (HTML and/or PHP) to create the content that displays in an info window popup when a marker is selected. For an example, see below |
Data source
The Data source should be a custom field containing a comma-separated latitude, longitude
.
You can also use separate custom fields for the latitude and longitude, see the available options.
Other data sources
The following plugins and themes offer dedicated custom fields for latitude and longitude that can be used as data sources for the Map facet. Click the links for specific instructions on using these fields:
Multiple data sources
It is possible to index multiple locations for a post, by using a multi-value custom field, like an ACF repeater field or for example a checkboxes/dropdown field (if you have a select number of locations to choose from).
Google Maps API key
Generate a Google Maps API key
The Map facet requires a valid Google Maps API key. To generate a key, you have to log into Google Cloud Console, set up a project, add an API key under API's & Services > Credentials
, and enable the following three API services for the key:
- Maps JavaScript API: required for the Map / Proximity facets to work
- Geocoding API: required for the Proximity facet’s “Locate me” button
- Places API: required for the Proximity facet’s autocomplete box
To be able to use the key, you also need to set up a Billing Account in Google Cloud Console, and add your project to it. You will need a creditcard to set up billing. There is a free monthly credit of $200, which amounts to 28000+ map loads per month.
Add the Google Maps API key to FacetWP
After generating an API key, add it to: Settings > FacetWP > Settings > Google Maps API key
.
Both the Map facet and the Proximity facet use this key.
Besides in FacetWP’s settings, the API key can also be set with a constant in wp-config.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
define( 'GMAPS_API_KEY', 'your-api-key' );
Or with a hook in your (child) theme’s functions.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_gmaps_api_key', function( $api_key) { return 'your-api-key'; });
Add the Google Maps API key to Advanced Custom Fields
If you are using the Advanced Custom Fields Google Map field as the data source, make sure you pass the same Google Maps API key into ACF. ACF needs the Google Maps API in the backend to geolocate the address entered for each post.
Add the Google Maps API key to Listify, Listable, WP Job Manager
If you are using Listify theme, Listable theme and/or the WP Job Manager plugin, make sure to also add the Google Maps API key to:
(Job) Listings > Settings > Google Maps API Key
The Listify theme itself has a second settings to enter the Google Maps API key, at:
Appearance > Customize > Listings > Map settings
Add marker content
The “Marker content” setting can be used to create the content of the info window popup that displays when a marker is selected. The setting’s field accepts HTML and PHP code.
The following example outputs the title, link, and excerpt:
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
<h3> <a href="<?php the_permalink(); ?>" title="<?php the_title_attribute(); ?>"> <?php the_title(); ?> </a> </h3> <?php the_excerpt(); ?>
The “Enable map filtering” button
When the “map filtering” is enabled with the button, the results will be refreshed 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.
To understand how map filtering works, you can think of the rectangular viewport of the map acting as a facet filter. When map filtering is enabled, you’ll see that the map viewport’s bottom-left, and top-right lat/lng coordinates are present in the URL variables as the active values of the map facet. These coordinates are updated when panning or zooming the map, just like any other facet updates its values when making selections.
Hide 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:
How to use custom CSS?
CSS code can be placed in your (child) theme's style.css file. Alternatively, you can add it manually between
<style>
tags in the<head>
section, in 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 thefacetwp_scripts
hook. To load it on all pages, usewp_head
orwp_footer
. Or you can use a code snippets plugin. More info.facetwp-map-filtering { display: none; }
Translate the “Enable map filtering” and “Reset” button text
The text of the “Enable map filtering”, and “Reset” buttons can be changed with a setting.
Both texts can be changed or translated with a translation plugin, with the facetwp_i18n hook, or with a WordPress gettext filter:
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( 'gettext', function( $translated_text, $untranslated_text, $domain ) { if ( 'facetwp-map-facet' == $domain ) { if ( $translated_text == 'Enable map filtering' ) { $translated_text = 'Use map as filter'; } if ( $translated_text == 'Reset' ) { $translated_text = 'Disable map as filter'; } } return $translated_text; }, 10, 3 );
Enable map filtering on load of the map
It’s possible to enable map filtering by default on load of the map, with the following code.
However, be aware that having map filtering enabled will prevent other facets – like a Proximity facet – from automatically zooming or panning the map. This can be confusing for users, even more so if it is unclear that map filtering is enabled. So it’s not a good idea to combine this with hiding the “Enable map filtering” button.
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_footer', function () { ?> <script> (function ($) { $(document).on('facetwp-loaded', function () { if ('undefined' === typeof FWP_MAP) { return; } var filterButton = $(".facetwp-map-filtering"); if (!filterButton.hasClass('enabled') && 'undefined' == typeof FWP_MAP.enableFiltering) { filterButton.text(FWP_JSON['map']['resetText']); FWP_MAP.is_filtering = true; filterButton.addClass('enabled'); FWP_MAP.enableFiltering = true; } }); })(jQuery); </script> <?php }, 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 disables the map from auto-refreshing.
Advanced map customizations
Don’t miss our page with advanced map customizations, among which:
- Customize Google Maps API loading, or localize your map
- Change the map type
- Customize the map controls
- Customize the map style/design
- Set a custom zoom level or location/center, or Restrict the map viewport
- Customize the marker pins
- Customize the Proximity facet marker pin
- Customize marker clustering behavior
- Customize Overlapping Marker Spiderfier behavior
- How to use advanced map marker hooks and functions
Changelog
1.0.4
- New added settings to customize the "Reset" and "Enable map filtering" button labels
1.0.3
- Fixed Prevent need to double-click custom markers
- Fixed PHP8 deprecation notices
1.0.2
- Fixed "Google Maps JavaScript API without a callback is not supported" JS error
1.0.1
- New added `facetwp_gmaps_url` hook for customizing the GMaps script URL
- Improved changed the admin UI label from "Other data source" to "Longitude" for clarification
1.0
- Improved refactored the "Enable map filtering" logic slightly
- Improved support changing the spiderfier init arguments
- Improved updated (and patched) markerclusterer.js
- Improved renamed "Default lat / lng" to "Fallback lat / lng / zoom" for clarification
- Fixed cleared up google `addDomListener` console warnings
- Fixed make sure lat / lng aren't empty during indexing
0.9.3
- Improved FacetWP 3.9 compatibility
0.9.2
- Improved removed jQuery dependency
0.9.1
- 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
0.9
- Improved significant performance boost (esp. for maps with many markers)
0.8.1
- Fixed issue causing "maxZoom" JS error
0.8
- Changed use `FWP()->filtered_post_ids` if available
- Fixed prevent infinite refresh when "Enable map filtering" is on
0.7.1
- Fixed only load posts if the "Marker Content" box is filled (performance boost)
0.7
- 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"