Create Your First Store Locator
Install, activate, and go live in 6 simple steps. No code required.
Read guide →How to Create Your First Store Locator
No code required · 10 minutes
Getting Started · No code required
From zero to live store locator in 6 steps
Follow these 6 steps to set up a working store locator on your WordPress site. By the end you’ll have a live, searchable map your customers can use to find your retailers.
1
Install and activate the plugin
Go to Plugins → Add New, search for Retailers Management for WooCommerce, click Install Now then Activate. A new Retailers menu will appear in your dashboard.
2
Create your first retailer
Go to Retailers → Add New Retailer. Fill in the store name, address, phone, and website. Click Geocode address — the plugin will find the map coordinates automatically. Save and publish.
3
Create a store locator page
Go to Pages → Add New. Give it a name like “Find a Store”. In the block editor, click +, search for Store Locator, and insert the block. You’ll see a placeholder — the live map appears on the frontend.
4
Choose a layout and template
Click the Store Locator block to open the Block settings sidebar. Pick a Template (e.g. Dark Rail or Grid) and a Layout (split map+list, map-only, or list-only). Set a default center city so the map opens in the right location.
5
Enable search and filters
In the Block settings, turn on Show search bar and Use my location. If you have retailer categories (types), enable the Type filter so visitors can filter by store type.
6
Publish the page
Click Publish. Visit the live page to see your store locator in action. Share the page URL in your footer, navigation, or product pages.
No API key? The plugin works out of the box with OpenStreetMap — free, no setup. Switch to Google Maps later in Retailers → Settings → Maps to unlock Place Autocomplete.
Choose the Right Template
9 built-in styles — pick one to match your site
Dark Rail
Dark sidebar on the left for search and results; light map on the right. Clean, app-like feel.
Use when: Your site has a dark or modern design, or you want a professional look without extra setup.
Grid
Two-column card layout with search on top. Great for pages with many retailers.
Use when: You have 10+ retailers and want visitors to browse a card list without a map in the way.
Overlay
Floating card list over a full-bleed map — Google Maps style. Maximum map visibility.
Use when: The map is the hero of the page and you want store cards to feel like an overlay, not a sidebar.
Distance Board
Groups retailers into tabs: Nearest / Nearby / Further. Ideal for dense urban areas.
Use when: You’re in a city with many stores and visitors care most about “how close” rather than “which store”.
Dark Mode
Slate-black background with high-contrast cards. Pairs with the dark map preset.
Use when: Your site has a dark theme and you want the locator to blend in seamlessly.
Custom CSS tokens
Override accent color, radius, shadows, and spacing with a simple JSON attribute. No PHP required.
Use when: None of the built-in styles match your brand exactly and you want fine-grained control.
Using Shortcodes
Paste a shortcode into any page, widget, or theme template
Shortcodes · Copy-paste examples
Common shortcode examples
Start with the simplest shortcode and add options as needed. All parameters are optional — defaults come from Retailers → Settings.
Basic store locator
[rmfw_store_locator]
List-only layout — no map
[rmfw_store_locator layout="list-only"]
Map + list with search bar
[rmfw_store_locator layout="split" height="600px" show_search_bar="1" show_use_my_location="1"]
With type filter and clustering
[rmfw_store_locator show_type_filter="1" clustering="yes" radius="20"]
Using a saved configuration
Build your settings once in the Locator Builder, then reference the slug here. Any attribute you add in the shortcode overrides the saved config.
// Load a saved Locator Configuration
[rmfw_store_locator config="your-slug"]
// Override a single option on top of the config
[rmfw_store_locator config="homepage" height="400px" layout="map-only"]
For the full list of every shortcode attribute and its possible values, see Full Shortcode Reference in the Advanced section below.
Use Gutenberg Blocks
Add the locator visually without any code
The Store Locator block is the easiest way to add a locator. All settings are available directly in the Block sidebar — no shortcode needed.
1
Open the block editor
Edit any page. Click the + button in the toolbar or in the content area.
2
Search for “Store Locator”
Type Store Locator in the search box and click the block with the map pin icon. A preview placeholder appears in the editor.
3
Configure in the Inspector panel
Click the block. The Block settings panel on the right shows all options: template, layout, height, search bar, filters, map center, and more.
4
Publish and check the frontend
The editor shows a placeholder — the real interactive map only loads on the published page. Click Preview to see it before publishing.
You can also select a Locator Configuration slug in the block settings to load all your saved options at once. This is the easiest way to reuse the same locator on multiple pages.
Manage Retailers
Add, edit, and organize your store list
Each retailer is a WordPress post with address, contact details, opening hours, categories, and a map pin. Here’s how to manage them effectively.
Adding a retailer
- Go to Retailers → Add New Retailer
- Fill in the Store name, Address, Phone, and Website
- Click Geocode address to auto-fill the map coordinates from the address
- Optionally upload a Logo and assign a Retailer Type (category)
- Click Publish — the store appears on the map immediately
Opening Hours
Show open/closed status automatically
Open any retailer and scroll to the Opening Hours panel. Toggle each day on or off and set the opening and closing time. The locator automatically shows Open now or Closed labels based on the visitor’s local time.
Opening hours use your WordPress site timezone (Settings → General → Timezone). This applies to all retailers — there is no per-retailer timezone override. Make sure your site timezone matches the timezone where your stores are located.
Filters & Search
Let visitors filter by category and location
Visitors can filter retailers by category using the type filter. To enable it, add show_type_filter="1" to your shortcode, or toggle it in the Block settings.
- Create retailer types at Retailers → Retailer Types
- Assign types when editing each retailer
- The filter appears as tabs or a dropdown above the results list
Styling & Branding
Match the locator to your brand without editing PHP
Every visual detail — colors, spacing, card radius, shadows — is controlled by CSS custom properties (--rmfw-sl-*). Override only what you need using the custom_tokens shortcode attribute.
Quick brand color override
[rmfw_store_locator template="dark-rail"
custom_tokens='{"--rmfw-sl-accent":"#e11d48","--rmfw-sl-card-radius":"20px"}']
Common tokens to customize
| Token | What it controls | Example value |
|---|---|---|
--rmfw-sl-accent | Buttons, pins, active states | #e11d48 |
--rmfw-sl-card-bg | Store card background | #0f172a |
--rmfw-sl-card-radius | Card corner radius | 20px |
--rmfw-sl-sidebar-bg | Search sidebar background | #1e293b |
--rmfw-sl-marker-color | Map marker / pin color | #0ea5e9 |
You can also set tokens globally via Retailers → Settings → Templates so every locator on your site inherits your brand colors without repeating the
custom_tokens attribute.
Configure the Locator Builder
Build once, embed on any page
The Locator Builder lets you save a named configuration — template, layout, search settings, map center — and then embed it anywhere with a single slug. No repeating shortcode attributes.
Create a configuration
- Go to Retailers → Locator Builder → Create New
- Click Start from a template to inherit defaults, or Start from scratch
- Work through the 7 wizard steps: Basics → Layout → Search → Map → Results → Template → Publish
- A live preview on the right updates as you type — no API calls, uses sample retailers
- Give it a slug (e.g.
homepage-map) and click Publish
Embed the saved configuration
// Shortcode — simplest
[rmfw_store_locator config="homepage-map"]
// Gutenberg block (raw block markup)
<!– wp:rmfw/store-locator {“configSlug”:“homepage-map”} /–>
Set one config as the site default in Locator Builder settings. Then a bare
[rmfw_store_locator] on any page will automatically load that config’s options.
Troubleshooting
Quick fixes for common problems
Map is not showing
Grey box, blank area, or just the search bar with no map visibleProblem
The map renders blank or as a grey area.
Cause
Usually a missing or invalid Google Maps API key, or the wrong APIs enabled in Google Cloud Console.
Quick fix
Go to Retailers → Settings → Maps. Switch to OpenStreetMap (free, no key needed) to confirm the plugin works. If it does, the issue is your API key. In Google Cloud Console, enable the Maps JavaScript API and Geocoding API, then paste the key back in settings.
Retailers are not appearing on the map
Map loads but shows no markers or resultsProblem
The map loads but the pins and results list are empty.
Cause
Retailer posts are not geocoded (no coordinates), or the search radius is too small for your area.
Quick fix
Edit any retailer and click Geocode address to add coordinates. Also try setting
initial_results="all" in the shortcode so stores appear without a visitor search. Increase the default radius in Settings if needed.Search does not return results
Visitor types an address but the list stays emptyProblem
Address autocomplete works but no retailers appear in the results.
Cause
The default search radius is too small, or retailer addresses were not geocoded so they have no coordinates to match against.
Quick fix
Increase
radius in the shortcode (e.g. radius="100") and ensure all retailers have been geocoded. Add radius_choices="10,25,50,100" so visitors can also expand the search themselves.Shortcode is not working
The shortcode text appears as plain text on the pageProblem
The page shows
[rmfw_store_locator] as literal text instead of rendering the map.Cause
The plugin is deactivated, or shortcodes are disabled in the template or page builder you’re using.
Quick fix
Confirm the plugin is active at Plugins → Installed Plugins. If using a page builder, use the plugin’s native block or widget instead of pasting raw shortcode into a text field.
Layout looks broken or unstyled
Cards overlap, map is too tall, or sidebar doesn’t appearProblem
The locator renders but the layout is broken — columns stack incorrectly or the map overflows.
Cause
Theme CSS is overriding the locator’s layout rules, or you’re using a template that expects a specific
height that wasn’t set.Quick fix
Set an explicit height:
height="600px". Try the default template first to rule out a template-specific issue. Check your browser DevTools for CSS rules overriding display:flex or height on .rmfw-sl-container.Best Practices
Tips for a fast, user-friendly store locator
Use split layout for many locations
Map + list side-by-side helps visitors orient themselves spatially. Use Grid or List-only when you have 30+ retailers.
Keep filters simple
Limit retailer types to 3–5 categories. Too many filter options overwhelm visitors. Use clear, short labels.
Use clear retailer categories
Name types after what the customer calls them — “Authorized Dealer” not “Type A Reseller”. Visitors should self-filter without guessing.
Set a proper map height
Aim for 500–650px on desktop. 100vh works for full-page locator sections. Avoid fixed heights that break on mobile.
Optimize for mobile
Test the locator on a phone. Use the Overlay or Dark Rail template — both are responsive by default. Avoid list-only on mobile unless the map adds no value.
Test opening hours and status
Manually set a store’s hours to a time in the past to confirm the Closed label shows correctly. Verify across time zones if you have international stores.
Advanced Tools
For developers, CI pipelines, and power users
WP-CLI commands
Run these from your server terminal
# Seed 10 demo retailers (default center)
wp rmfw demo seed
# 25 retailers within 30 km of a city
wp rmfw demo seed –count=25 –center=saigon –radius=30
# Full wipe — requires typed confirmation
wp rmfw demo reset –confirm=RESET
# Full integrity check — run before every release
wp rmfw template validate
# List all templates
wp rmfw template list
# Inspect merged tokens for the dark template
wp rmfw template tokens dark –format=json
# Export all configs (staging → production)
wp –ssh=staging rmfw config export –all > configs.json
wp –ssh=production rmfw config import configs.json –publish
# Find stale shortcode references after deleting a config
wp rmfw config audit
Full shortcode reference
Every [rmfw_store_locator] parameter
Template & appearance
| Attribute | Values | Default |
|---|---|---|
template | default · dark · grid · overlay · distance-board · dark-rail · minimal · corporate · vibrant | default |
custom_tokens | JSON object of --rmfw-sl-* overrides | — |
card_variant | horizontal · vertical · compact · minimal | template default |
map_style | standard · silver · dark | template default |
distance_unit | km · miles | km |
Layout & size
| Attribute | Values | Default |
|---|---|---|
layout | split · map-only · list-only | split |
height | CSS value (px, vh) | 600px |
Search & results
| Attribute | Values | Default |
|---|---|---|
show_search_bar | 1 · 0 | 1 |
show_use_my_location | 1 · 0 | 1 |
radius | number (km) | 20 |
radius_choices | comma-separated km values | 5,10,20,50 |
initial_results | none · all · by-type | none |
show_type_filter | 1 · 0 | 0 |
clustering | yes · no | no |
config | slug or numeric ID | — |