# Magento store locator: adding one to Adobe Commerce with Page Builder

Source: https://locator.handledlocal.com/resources/store-locator-for-magento

How to add a store locator to Magento Open Source or Adobe Commerce with the Page Builder HTML Code element, what the 2.4.7 content security policy changes, and when an extension is the better route.

Platform guide. Published 2026-11-15. 9 min read.

## In short

On Magento Open Source and Adobe Commerce, a hosted store locator goes into a CMS page through Page Builder's HTML Code element, which accepts HTML, CSS and JavaScript. Create a page such as /stores, drag an HTML Code element onto it, paste the embed, and save.

The one Magento-specific trap is the content security policy. From version 2.4.7, Adobe enforces a strict policy on payment pages and runs every other page in report-only mode by default, so a locator on a CMS page loads. If your team has switched the storefront to restrict mode, add the widget host to the module's csp_whitelist.xml first.

A Magento extension stores locations in your Magento database and can tie them to inventory sources. A hosted locator keeps them outside Magento, which is better if the list is maintained by people who never log into the Magento admin, or if you might replatform.

## Two ways to run a Magento store locator

Magento merchants usually choose between an extension from the Commerce Marketplace and a hosted locator embedded in a page. The choice follows from where the locations should live.

|  | Magento extension | Hosted locator in a CMS page |
| --- | --- | --- |
| Where locations live | Your Magento database | The locator's dashboard, exported as CSV whenever you want |
| Who can edit them | Anyone with Magento admin access | Anyone you invite to the locator, without Magento access |
| Upgrades | Tested against each Magento release you install | Nothing installed, so nothing to upgrade |
| Inventory and pickup | Some extensions connect to inventory sources | Not connected to Magento stock or checkout |
| Moves with you if you replatform | No | Yes, the same embed works anywhere |

## Add the Magento store locator with Page Builder

Adobe's documentation describes the HTML Code content type as the place for snippets of HTML, CSS and JavaScript, including code received from a third-party provider. That is exactly what the locator embed is: one div and one script tag.

1. In the locator dashboard, import your locations and style the widget, then copy the snippet from Embed & Install.
2. In the Magento admin, go to Content, then Elements, then Pages, and add a new page (for example "Find a store" at the URL key stores).
3. Expand the Content section, open Elements in the Page Builder panel, and drag an HTML Code element onto a full-width row.
4. Open the element's settings, paste the snippet into the text box, and save.
5. Set Enable Page to Yes, save and close, then open the page from the grid with View.
6. Add the page to your main menu or footer so shoppers and crawlers can reach it.

## The content security policy since 2.4.7

Adobe's developer documentation states that from 2.4.7 the policy runs in restrict mode by default on payment pages in the storefront and admin, and in report-only mode on all other pages. Before 2.4.7 every page was report-only. A locator on a CMS page is therefore not blocked on a default install.

Some stores tighten the storefront to restrict mode as part of PCI work. If yours has, the locator's script and its map provider must be allowed in a csp_whitelist.xml file in a custom module, for script-src, connect-src and img-src. The symptom of a missing entry is an empty space where the locator should be and a refused-to-load message in the browser console.

Never put the locator on a checkout or payment page. It has no business there, and those pages are the ones Adobe locks down hardest.

## Magento-specific quirks

None of these is a blocker; each is a check worth doing once. For a headless storefront, the [React guide](https://locator.handledlocal.com/react-store-locator) covers where the script goes.

- Full page cache: the locator loads its data in the visitor's browser, so a cached CMS page still shows current locations and hours.
- Multiple store views: one CMS page per store view is normal in Magento. The same snippet works in each; use the locator's interface languages if store views differ by language.
- Theme CSS: the widget renders in its own shadow root, so Luma or a custom theme cannot restyle it by accident, and its styles cannot leak into your theme.
- Hyvä and headless storefronts: in a PWA or headless build, put the script in the page component rather than a CMS block.

## Checks before you call it done

Do these on the storefront, not in the Page Builder stage, which does not run third-party scripts the way a visitor's browser does.

- Open the published page in a private window, not the editor. Most builders do not run third-party scripts while you edit.
- Search your busiest town and a town you do not serve, and read both results.
- Open it at phone width and use it one-handed.
- Tap a phone link and a directions link on a real phone.
- Run Check installation in the Handled dashboard against the public URL. Setup completes when the locator has loaded on that page.

## Where Handled Locator fits on Magento

On Magento, Handled Locator is the embed described above: one HTML Code element on a CMS page, with nothing installed into Magento and nothing to retest at each upgrade. Locations come from CSV, the dashboard, or a sync from Google Sheets, Airtable, Webflow CMS or HubSpot. The map runs on your own Mapbox or Google Maps key, billed by the provider with nothing added. Plans are $19, $39 and $79 a month for 200, 2,000 and 10,000 locations, after a 7-day trial with no card. You can also run it from ChatGPT or Claude: add locations, restyle the widget and get the embed code by describing what you want, with every design change shown before it goes live.

What it does not do on Magento: it does not read your Magento inventory sources, and it does not offer store pickup at checkout. If shoppers need to reserve stock at a branch, an extension built on Magento's inventory is the right tool. For a list of shops, dealers or stockists that marketing or sales maintains, the hosted route is simpler to keep current.

## Sources

Adobe Experience League, [Page Builder: HTML Code](https://experienceleague.adobe.com/en/docs/commerce-admin/page-builder/elements/html-code), and Adobe Developer, [Content security policies](https://developer.adobe.com/commerce/php/development/security/content-security-policies). Both read on 15 November 2026.

## Frequently asked questions

### How do I add a store locator to Magento 2?

Create a CMS page, drag a Page Builder HTML Code element onto it, paste the locator's embed code and save. Then link the page from your navigation. No extension is needed for a hosted locator.

### Will Magento's content security policy block a store locator?

Not on a default install. From 2.4.7, Adobe enforces the policy on payment pages and runs other pages in report-only mode. If your storefront has been switched to restrict mode, allow the widget and map hosts in csp_whitelist.xml.

### Can a store locator use Magento inventory?

Only an extension that reads Magento's inventory sources can. A hosted locator shows your locations, hours and filters but does not know what each branch has in stock.

### Does the locator work with Adobe Commerce Cloud?

Yes. Page Builder and its HTML Code element are part of Adobe Commerce, and the embed is a script the visitor's browser loads, so the hosting model makes no difference.
