Store Locator Widget Setup Types
This article explains the different ways the Store Locator widgets can be installed on your Shopify store, how to identify which setup you currently have, and how to upgrade to the recommended App Embed method.
Overview
Setup Type | Shopify Theme | Status | How it works |
App Embed | OS 1.0 + OS 2.0 | ✅ Recommended | Activated via Theme Editor — no theme code changes |
App Block | OS 2.0 only | ✅ Supported | Drag-and-drop block in Theme Editor sections |
Snippet | OS 2.0 (older installs) | ⚠️ Deprecated | App uploaded Liquid files directly into your theme |
Legacy | Shopify 1.0 (older installs) | ⚠️ Deprecated | App uploaded Liquid files directly into your theme |
Recommendation: If you are on Snippet or Legacy setup, we recommend upgrading to App Embed. App Embed and App Block are the only setup types that receive ongoing support and updates.
App Embed
App Embed uses Shopify's Theme App Extension technology. The widget is activated as a global toggle in the Theme Editor App embeds section, without modifying any of your theme's code files.
Compatible with: Shopify OS 1.0 and OS 2.0 themes.
Available embed blocks:
Store Locator — displays the store locator widget on your designated Store Locator page
Where to Buy — displays the Where to Buy widget
Find Online — displays the Find Online widget
Stockist Form — displays the Stockist/Dealer Form widget
Benefits:
Works with all themes, including after switching themes — no reconfiguration needed
Widget script only loads on the relevant page (not on every page of your store)
Fully supported and regularly updated
How to enable App Embed
Go to Store Locator Admin → Setup.
Click the "Enable App Embed" button — this opens a deep link directly to your Theme Editor.
In the Theme Editor, find the Store Locator entry under App embeds and toggle it on.
Click Save in the Theme Editor.
Return to Store Locator Admin and save your settings once to complete the setup.
Important: Saving your settings (Step 5) is required for the widget to load correctly. Do not skip this step. You can save the settings by changing anything in the settings—for example, turning a toggle on and then off (such as Dynamic Map), which will make the Save button appear at the top.
If your Store Locator page is still using the old page.sca-storelocator template, the widget may appear twice after enabling App Embed. See the Upgrade Guide below for template reassignment instructions.
Note: If you do not see the theme editor you may need to add it to your Sales Channels menu - Click on Sales Channels on the left hand menu and choose Online Store
App Block
App Block also uses Shopify's Theme App Extension technology, but unlike App Embed, it is placed as a draggable block inside a specific section on your page templates.
Compatible with: Shopify OS 2.0 themes only.
Available app blocks:
Store Locator — can be added to any page template as a section block
Stockist Form — can be added to page templates
Find Online — can be added to product page templates
Where to Buy — can be added to product page templates
Use case: App Block is ideal when you want to embed a widget directly within a specific section on a page or product template, with full control over positioning.
How to add an App Block
Go to Store Locator Admin → Setup.
Click the deep link button next to the App Block you want to add (e.g., Find Online).
In the Theme Editor, the block will be added to your product page template.
Reposition the block within the section if needed.
Click Save in the Theme Editor.
Note: App Block requires a Shopify OS 2.0 theme. If you are on a vintage (1.0) theme, use App Embed instead.
How to Identify Your Current Setup
From SL Admin (quickest)
Go to Store Locator Admin → Setup.
If "App Embed is enabled" is shown — you are on App Embed. No action needed.
If a prompt to enable App Embed is shown — you are on Snippet or Legacy setup.
From Shopify Admin (theme files)
Go to Shopify Admin → Online Store → Themes.
On your active theme, click "..." → Edit code.
Look for the following files:
If you find this file | Your setup type |
| Legacy |
| Snippet |
None of the above | App Embed |
Snippet Setup (Deprecated)
The Snippet setup was used for Shopify OS 2.0 themes installed before October 2023. The app uploaded files directly into your theme:
templates/page.sca-storelocator.jsonsections/sca-storelocator.liquidsnippets/sca.storelocator.liquid
It also inserted a line into layout/theme.liquid to load configuration data on every storefront page.
Important notes:
Snippet setup is no longer supported for new installs.
If you switch to a new theme, the widget will stop working because the uploaded files are not carried over.
We recommend upgrading to App Embed (see upgrade guide below).
Legacy Setup (Deprecated)
The Legacy setup was used for Shopify 1.0 (vintage) themes installed before October 2023. The app uploaded files into your theme including templates/page.sca-storelocator.liquid.
Important notes:
Legacy setup is no longer supported for new installs.
Legacy merchants can still upgrade to App Embed — App Embed is compatible with Shopify 1.0 themes.
We recommend upgrading to App Embed (see upgrade guide below).
Upgrade Guide: Snippet or Legacy → App Embed
App Embed is compatible with both Shopify OS 1.0 and OS 2.0 themes — you do not need to switch themes to use it.
Steps
Step 1: Enable App Embed
Go to Store Locator Admin → Setup.
Click the "Enable App Embed" deep link button.
In the Theme Editor, toggle on Store Locator under App embeds.
Click Save in the Theme Editor.
Step 2: Save your settings
Return to Store Locator Admin.
Go to your settings page and click Save (even without making changes).
This step is required — it syncs the widget configuration so the App Embed initializes correctly
Step 3: Test the widget
Visit your Store Locator page on your storefront.
Confirm the widget displays correctly.
Test search and filter functionality.
Step 4: Reassign your Store Locator page template
If your Store Locator page was previously using the old page.sca-storelocator template, you need to reassign it. If this is not done, both the old widget and the new App Embed will load on the same page simultaneously.
Go to Shopify Admin → Online Store → Pages.
Click on your Store Locator page.
Under "Theme template", change from
page.sca-storelocatorto any regular page template (for example: Default page or your preferred custom page template).Click Save.
Why this matters:
App Embed injects the widget onto any page whose template name contains the word "page" — including page.sca-storelocator. If you do not reassign the template, both the old section and the new App Embed will render on the same page, causing:
duplicate widgets
duplicate script loading
duplicate API calls
slower page performance
unpredictable frontend behavior
Step 5 (Optional): Clean up old theme files
After confirming the App Embed widget works, we strongly recommend duplicating your theme as a backup before removing old files. Files involved:
snippets/sca.storelocator.liquidsections/sca-storelocator.liquidtemplates/page.sca-storelocator.json(Snippet) ortemplates/page.sca-storelocator.liquid(Legacy)
You can also remove the following line from layout/theme.liquid if present:
{% include 'sca.storelocator' %}
⚠️ Important — If you have customized CSS or JS in these files:
Minor customizations: Copy your custom CSS/JS into your theme's CSS file (e.g.,
assets/theme.css) before deleting. Note that App Embed may use a different HTML structure, so some selectors may need to be adjusted.Heavy customizations: Do not delete the files yet. Instead of deleting, rename the files with an
old-prefix (e.g.,old-sca.storelocator.liquid) to disable them without losing your code. Contact our support team to review your customizations before removing any files.
Recommended Final Setup
Recommended production setup:
App Embed enabled
Store Locator page using a regular
page.*templateOld Snippet/Legacy files removed
No
{% include 'sca.storelocator' %}remaining intheme.liquid
Quick Troubleshooting Checklist
App Embed enabled?
Correct theme selected?
Settings saved after enabling?
Store Locator page reassigned from
page.sca-storelocator?Old Snippet/Legacy files removed?
Cache/CDN cleared?
FAQ
Q: I am on a vintage Shopify 1.0 theme. Can I use App Embed?
A: Yes. App Embed is compatible with both Shopify OS 1.0 and OS 2.0 themes. You do not need to switch themes.
Q: What is the difference between App Embed and App Block?
A: App Embed is a global toggle — it injects the widget into your Store Locator page automatically. App Block is a drag-and-drop block you place inside a specific section on a page template (e.g., Find Online on a product page). App Embed works on all themes; App Block requires OS 2.0.
Q: My widget stopped working after switching themes. What should I do?
A: If you were on Snippet or Legacy setup, switching themes removes the uploaded widget files. Enable App Embed from the Store Locator Admin Setup page and follow the upgrade guide above.
Q: I enabled App Embed but the widget does not appear on my page.
A: Make sure you completed Step 2 of the upgrade guide — saving your settings after enabling App Embed. If the issue persists, contact our support team.
Q: Can I have both Snippet/Legacy and App Embed active at the same time?
A: Technically yes, but it is not recommended — the widget may appear twice on the same page and scripts may load twice, which can cause display issues, duplicate API calls, and slower page performance.
Q: Will upgrading to App Embed affect my widget data or settings?
A: No. Your store locations, filters, and settings are stored in the app, not in your theme. Switching to App Embed only changes how the widget is loaded — all your data remains intact.
Q: I enabled App Embed but the widget appears twice on my Store Locator page?
A: This happens when App Embed is active but your Store Locator page is still assigned to the old page.sca-storelocator template — both the old section and the new App Embed are rendering on the same page.
Follow Step 4 of the upgrade guide to reassign your page template to a regular page template.
Important:
App Embed must be enabled on the same theme you are previewing or publishing. If enabled on a different theme, the widget may not appear on your storefront.
Need help? Contact our support team and let us know which setup type you are on.