# Shopware store locator: Shopping Experiences and the HTML sanitizer

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

How to add a store locator to Shopware 6 with a Shopping Experiences HTML element, why the HTML sanitizer may strip it, and what differs between self-hosted shops and Shopware cloud.

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

## In short

In Shopware 6, a store locator goes into a Shopping Experiences layout through the HTML element. Shopware's own documentation warns that the HTML sanitizer may delete certain tags or attributes unless it is configured for them, and a locator embed is a script tag.

On a self-hosted shop, the sanitizer's allowed tags are set in a z-shopware.yaml file, or the embed can live in a theme template. Shopware's developer documentation says that sanitizer configuration is for self-hosted shops only and not available for cloud stores.

So on Shopware cloud, test whether the HTML element keeps the script before you plan around it. If it does not, the route is a theme change or an extension that outputs raw HTML, not disabling protection.

## Add the locator in Shopping Experiences

Try the editor route first. It works wherever the sanitizer keeps the script.

1. Import your locations and style the widget in the locator dashboard, then copy the snippet from Embed & Install.
2. In the Shopware administration, open Content, then Shopping Experiences, and create a landing page or shop page layout for your stores page.
3. Add a full-width section, then add the HTML block to it.
4. Paste the snippet into the HTML element and save the layout.
5. Assign the layout to a landing page or category with its own URL, and add that page to your navigation.
6. Open it in the storefront. If the locator is missing, the sanitizer removed the script: read the next section.

## The HTML sanitizer, self-hosted and cloud

Shopware's sanitizer removes potentially unsafe HTML from editor content. Its documentation shows the shape of the fix for self-hosted shops: copy shopware.yaml to z-shopware.yaml under config/packages and add the tags and attributes you need to an html_sanitizer set. It also shows how to disable the sanitizer entirely, with a warning that doing so allows unsafe code.

Do the narrow version. Allow the script tag only where you must, or better, skip the editor and put the two-line embed in the storefront theme template for that one page, which is a normal Shopware theme change.

On Shopware cloud the sanitizer settings are not available, per the same documentation, so the editor route works only if the HTML element keeps the snippet as pasted. Test it on a draft layout first. If it is stripped, a theme change or a Shopware Store extension that renders raw HTML is the way through.

## Shopware-specific quirks

None of these stop an install; they explain what you will see.

- The widget renders in its own shadow root, so your storefront theme cannot restyle it and its styles cannot leak out.
- Shopware's HTTP cache does not freeze the locator's data. Locations and hours load in the visitor's browser on every visit.
- Sales channels: one layout can be assigned per sales channel. If channels differ by language, use the locator's interface languages rather than separate locators.

## Checks before you call it done

In the storefront, logged out.

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

On Shopware, Handled Locator is the embed described above: an HTML element in Shopping Experiences where the sanitizer allows it, or a theme template where it does not. 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.

It does not connect to Shopware stock or click and collect. For a dealer, stockist or branch list kept by people outside the Shopware administration, keeping the list in the locator is the simpler arrangement.

## Sources

Shopware documentation, [Shopping Experiences](https://docs.shopware.com/en/shopware-6-en/content/ShoppingExperiences) (HTML block) and Shopware developer documentation, [HTML sanitizer](https://developer.shopware.com/docs/guides/hosting/configurations/shopware/html-sanitizer.html). Both read on 15 November 2026.

## Frequently asked questions

### Why does Shopware remove my embed code?

The HTML sanitizer strips tags it considers unsafe, and a script tag is one of them. On a self-hosted shop, allow it narrowly in z-shopware.yaml or put the embed in a theme template.

### Can I change the HTML sanitizer on Shopware cloud?

Shopware's documentation says the sanitizer configuration is for self-hosted shops and not available for cloud stores. Test the HTML element first; if it strips the script, use a theme change or an extension.

### Does Shopware have a built-in store locator?

Not in the Shopping Experiences documentation we read. A searchable list of many locations with filters is added from outside, through the HTML element or the theme.
