If you're building with React, Next.js, Vue, Angular, or any JavaScript framework, or you can only add scripts through Google Tag Manager, the SPA widget gives you programmatic control over when and how the store locator loads.

What's the SPA widget?

The standard embed loads automatically when the page renders. The SPA widget lets you start the locator from your own JavaScript. This is useful when:

Your page loads dynamically (single-page apps, client-side routing)
You want to start the locator after a user action
You need to pass configuration options programmatically
Your framework re-renders the page and the standard embed doesn't survive

Getting the SPA code

Open Store Locator > Install
Under Developer options, set Embed type to Web app (SPA)
Copy the generated StoreRocket.init() code

The page also lists every option and event the SPA widget supports.

Basic usage

<div id="storerocket-locator"></div>
<script src="https://cdn.storerocket.io/widget.js"></script>
<script>
  StoreRocket.init({
    selector: "#storerocket-locator",
    account: "YOUR_ACCOUNT_ID"
  });
</script>

selector and account are required. The selector must point to an element that is already on the page. Any id works except #storerocket-widget, which the locator uses internally.

React example

import { useEffect } from 'react';

const WIDGET_SRC = 'https://cdn.storerocket.io/widget.js';

export default function StoreLocator() {
  useEffect(() => {
    const start = () => {
      window.StoreRocket.init({
        selector: '#storerocket-locator',
        account: 'YOUR_ACCOUNT_ID'
      });
    };

    // Load widget.js once, then reuse it every time this component mounts.
    let script = document.querySelector(`script[src="${WIDGET_SRC}"]`);

    if (window.StoreRocket) {
      start();
    } else {
      if (!script) {
        script = document.createElement('script');
        script.src = WIDGET_SRC;
        document.body.appendChild(script);
      }
      script.addEventListener('load', start);
    }

    return () => {
      script?.removeEventListener('load', start);
      window.StoreRocket?.destroy('#storerocket-locator');
    };
  }, []);

  return <div id="storerocket-locator" />;
}

The script loads once and stays on the page. Each time the component mounts it starts the locator, and each time it unmounts it removes it. This also works with React's Strict Mode, which mounts components twice in development.

Next.js example

Use the React component above. With the App Router, add 'use client'; as the first line of the component file. The locator starts inside useEffect, which only runs in the browser, so server rendering is fine.

Google Tag Manager

If your site only allows scripts through Google Tag Manager:

Put <div id="storerocket-locator"></div> in the page content where the locator should appear.
In Tag Manager, create a Custom HTML tag with only the two script lines from Basic usage (not the div).
Give the tag a DOM Ready trigger that fires on Some DOM Ready Events, where Page Path contains the path of your locator page.
Save and publish.

Don't add the div inside the tag, and don't fire the tag on all pages. Otherwise Tag Manager places the locator at the top of every page of your site.

Common options

Option	Description
`selector`	CSS selector of the element the locator goes in (required)
`account`	Your account ID (required)
`lang`	Open in one of your saved languages, by code or name (for example `"sv"`)
`location`	Open a specific location by its location ID
`filters`	Preselect group IDs as a comma-separated string
`geolocate`	`true` starts near the visitor's area, `false` shows all eligible locations

The full list is on the Install page under Developer options, once Embed type is Web app (SPA).

Troubleshooting

Locator not appearing

Make sure the element named in selector exists before calling StoreRocket.init(). In React or Next.js, call it in useEffect. With Tag Manager, use a DOM Ready trigger.

Locator loads but shows a blank white area

Check that the container has a height. The SPA widget may need a minimum height on its container:

#storerocket-locator {
  min-height: 600px;
}

"StoreRocket is not defined" error

The script hasn't loaded yet. Call init() once the script has loaded (its load event or onload callback), not right after adding the script tag.

Questions? Message us on live chat.

Using the SPA Widget (Option 3) for React, Next.js, and Custom Apps