After over four years of development, the beta version for v3 is finally here! We’ve rebuilt the decade-old codebase from the ground up. New features include map providers other than Google, a way to restyle the locator without writing CSS, custom fields without writing PHP, real opening/closed statuses, and a lot more control over how results are searched and sorted.

• The top 10 new features
• Update your add-ons to version 2.0
• New shortcode attributes
• For developers: what changed under the hood
• Full changelog

Download the WP Store Locator 3 beta

The top 10 new features

1. You are no longer tied to Google Maps

   3.0 adds Mapbox, Stadia Maps and OpenStreetMap (Leaflet) as fully supported map providers, in addition to Google Maps.

   

   The only option that needs no API key, no account and no credit card. Autocomplete and bulk geocoding aren’t available and driving directions need a free OpenRouteService key, which makes it a better fit for a few dozen locations than a few thousand.

   Mapbox

   Mapbox brings the polished cartography and vector styling it’s known for, along with autocomplete and bulk geocoding, on an allowance of 50,000 free map loads a month. You’ll need an account and a public access token, but for a single-country store locator that allowance is usually more headroom than the site will ever use.

   Stadia Maps

   Stadia covers the full set — autocomplete, bulk geocoding and routing — and works out cheaper than Google Maps or Mapbox.

   It’s also the only one of the three offering EU endpoints: a single toggle routes every tile, search and directions request through servers inside the European Union.

   Stadia does require an API key, and it’s a paid service for commercial sites once the 14-day trial ends.

   Provider	API key	Autocomplete	Bulk geocoding	Cost
   OpenStreetMap (Leaflet)	None	No	No	Free
   Mapbox	Required	Yes	Yes	50,000 free map loads/months
   Stadia Maps	Required	Yes	Standard plan and up	Paid plan
   Google Maps	Required	Yes	Yes	Free quota, billing account required

2. A new Vertical theme

   In addition to the existing Default and Horizontal layouts there is a new Vertical theme: a modern two-column layout with the search form and results in the left column and the map filling the right. It comes with an optional filter panel.

3. The Appearance Editor

   Restyling the locator used to mean writing CSS. Now there is an Appearance editor where you set the theme colors, the call-to-action buttons, the icons and the active map style directly in the admin. It includes a live preview, and a contrast check so your labels stay readable.

   

4. The Template Section Editor

   For the parts the Appearance editor does not cover, there is a Template section editor. It lets you edit the actual markup of individual sections (the store listing, the info window, the “more info” block, the store header) from the admin, without touching a theme file. Your customization survives plugin updates.

5. The Fields Manager

   Adding a custom data field to your locations used to require the wpsl_meta_box_fields filter and a bit of PHP. The Fields manager does it from the admin: define the field, choose where it shows up, done.

   

   How to make the custom fields appear on the front-end is explained here.

6. Marker Studio

   Marker Studio is a new tool for building your own markers without opening an image editor. Pick a shape, choose an icon from the built-in set, set the fill, icon and outline colors, then adjust the outline thickness, size and drop shadow. Save it to a library you can reuse across your locations.

   

   There’s more marker control outside the Studio as well. Set a distinct active store marker, assign markers per category, and pick from new cluster marker styles for Google Maps. The default markers are now SVG instead of PNG (PNG still works). Info windows can open on hover, and clicking the address in the results list opens the matching info window on the map.

7. Map Shapes

   Draw polygons, circles, rectangles and lines straight onto a live map in the admin, and they appear on the map your visitors see. Use this feature to mark delivery zones, service areas, franchise territories, or simply highlight the region you cover. It works on Google Maps, Mapbox and OpenStreetMap alike.

   

   Each shape gets its own fill and outline colour, opacity and line thickness, and you can come back and reshape it later.

8. Opening hours that say whether you are open

   Locations can now show a live Open/Closed status, and visitors can expand it to see the full week. On top of that: a special hours field, the option to replace the hours with custom text, and a way to mark a location temporarily or permanently closed, with an optional automatic reopen date. The start day of the week now follows your WordPress setting.

   

9. Much more control over search and results

   A number of changes:

   • Sort results ascending or descending, by distance, address, city, state, country or ID.
   • Searching for a country or state returns all results in it, instead of nothing.
   • If nothing is found inside the radius, optionally fall back to the nearest location.
   • Exclude locations across a nearby border, so a search in a border town stays in-country.
   • Show the number of returned results.
   • Set a default category filter, or show only the category filter.
   • Choose the geolocation address format (zip, city, or full address), and whether geolocation runs on page load or only when the visitor clicks the button.

10. Built-in GDPR support

    The map no longer has to load before the visitor consents. 3.0 has GDPR handling built in. So no matter which map provider you use, the map only loads after consent is given.

    

A few more additions

New installs go through an onboarding flow instead of a blank settings page, an Alerts section surfaces compatibility warnings, and there are import/export, data management and status report tools. API key problems are now caught and explained instead of failing silently, and the admin location search understands zip, city, state and country.

On top of that: improved accessibility and keyboard navigation, better RTL support, migration to the Google Geocoding v4 and Routes APIs, and a number of new shortcode attributes (see further below).

Update your add-ons to version 2.0

If you use the CSV Manager, Statistics or Search Widget add-on, update it to version 2.0 or later. This is the one thing to take care of around the upgrade.

What happens if you update WP Store Locator first

Nothing breaks, and nothing gets deactivated. 3.0 detects a pre-2.0 add-on and switches its features off rather than letting it fail:

• The Search Widget stops rendering. The widget and the [wpsl_widget] shortcode are removed, so a visitor never hits an error.
• The Statistics and CSV Manager admin pages are hidden, and blocked if you reach them by a bookmarked URL.
• A red warning appears on the Plugins screen under each affected add-on, plus a notice listing which ones need updating and which version they’re on. The add-on deliberately stays active so it keeps receiving updates. Updating it to 2.0 from the Plugins screen turns its features straight back on — no reactivation, no reconfiguration, and the warning disappears without a page reload.

If no update shows up

Updates are license-gated, so an add-on with no license key saved never gets an update row. Check that your key is saved under Store Locator > Settings > Licenses.

An expired license is not the problem. Updates are lifetime, only the support period lapses. If the update still doesn’t appear, download version 2.0 or later from your account page and install it over the current version.

The safe order

1. Update the add-ons to 2.0 first, if the updates are showing.
2. Then update WP Store Locator to 3.0.

New shortcode attributes

3.0 adds a batch of attributes to the shortcodes, most of them to [wpsl]. Together they let you run several locators on one site that each behave differently — a page per country, a map with clustering on and the filters off, a locator locked to one region — without changing anything on the settings page. Everything from version 2 still works; these are additions.

[wpsl]

[wpsl country="Belgium" distance_unit="km" radius_filter="false" results_filter="false"]

One thing worth knowing about the location restrictions: if you set city, state or country without also setting start_location, the map works out its own starting point from that restriction. Otherwise you would get the start location from the settings page — London, say — on a map that only contains Canadian locations.

[wpsl_map]

Clustering here is deliberately per map: switching it on for a [wpsl_map]does not switch it on for the [wpsl] locator elsewhere on the site.

[wpsl_hours]

Both default to what you picked on the settings page, so you only need them when one page should differ from the rest.

[wpsl_address]

For developers: what changed under the hood

Most sites will not notice the rewrite, because the 2.x globals and helper functions are still there as compatibility shims. But if you wrote custom code against $wpsl_settings, $wpsl, or one of the wpsl_* template functions, here is what still works and what needs a small change.

The single flat wpsl_settings option is now split across eleven grouped options, all but wpsl_api and wpsl_local_seo have autoload disabled.

• wpsl_api
• wpsl_search
• wpsl_map
• wpsl_ux
• wpsl_markers
• wpsl_editor
• wpsl_appearance
• wpsl_local_seo
• wpsl_labels
• wpsl_gdpr
• wpsl_tools

The old option is kept as a backup on upgrade but stops being updated — do not read it.

Custom templates

Theme templates still work. A file in your theme’s wpsl-templates/ folder is still picked up, and the wpsl_templates / wpsl_template_list filters are unchanged. The underscore.js syntax (<% %> / <%= %>) is unchanged, and the section filters receive and return the same markup, so overrides port over as-is.

What changed is the delivery: templates are no longer echoed into the page as inline script blocks. They are collected server-side and handed to JS as JSON in wpslTemplateSections.

The map canvas was renamed. #wpsl-gmap became #wpsl-map plus a .wpsl-canvas- class, since the map is no longer always Google. A shim rewrites #wpsl-gmap quickly for un-updated v2 templates, but update your own CSS and JS.

Also note the below_map template id was renamed to horizontal; stored values are remapped automatically.

The JS Side

The frontend is now ES modules bundled with webpack, using wp.hooks for extension points:

There are around 70 filters and actions, covering the map, the markers, geocoding, directions and the search, plus provider-specific ones and a set for the admin.

wpslSettings and wpslLabels are still localized under the same names, though wpslSettings is nested now (wpslSettings.api.provider). Per-map data for [wpsl_map] instances is localized as wpslMap_0, wpslMap_1, and so on.

In short

If your custom code reads $wpsl_settings inside a filter callback, or overrides a template section, it keeps working. If it writes settings, calls wpsl_get_settings(), reaches for global $wpsl outside a template filter, or targets #wpsl-gmap, it needs a small change. Turn on WP_DEBUG after upgrading and the deprecation notices should point you at the rest.

Download the WP Store Locator 3 beta