If you're building with React, Next.js, Vue, Angular, or any JavaScript framework, the SPA widget gives you programmatic control over when and how the store locator loads.

What's the SPA widget?

The standard embed (Option 1 and 2) loads automatically when the page renders. The SPA widget (Option 3) lets you control initialization through JavaScript. This is useful when:

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

Getting the SPA embed code

Go to Widget > Install
Select Option 3 (SPA/Programmatic)
Copy the code

The SPA widget uses a different script (widget.js) that exposes a global StoreRocket object you can call in your code.

Basic usage

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

React example

import { useEffect, useRef } from 'react';function StoreLocator() {
  const containerRef = useRef(null);  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://cdn.storerocket.io/widget.js';
    script.onload = () => {
      window.StoreRocket.init({
        account: 'YOUR_ACCOUNT_ID',
        element: containerRef.current
      });
    };
    document.body.appendChild(script);    return () => {
      document.body.removeChild(script);
    };
  }, []);  return <div ref={containerRef} />;
}

Next.js example

For Next.js, use dynamic imports or load the script in useEffect to avoid server-side rendering issues. The widget requires the browser DOM, so it can't run during SSR.

import dynamic from 'next/dynamic';const StoreLocator = dynamic(() => import('../components/StoreLocator'), {
  ssr: false
});

Configuration options

You can pass these options to StoreRocket.init():

Option	Description
`account`	Your account ID (required)
`element`	CSS selector or DOM element for the widget container
`filter`	Pre-select a filter (e.g., `"Organic"`)
`lang`	Language name to use (must match a language in your Languages settings)
`location`	Open a specific location by ID

Troubleshooting

Widget not appearing

Make sure the container element exists in the DOM before calling StoreRocket.init(). In React/Next.js, use useEffect to wait for the component to mount.

Widget loads but shows a blank white area

Check that the container has a defined height. Unlike the standard embed, the SPA widget may need you to set a minimum height on the container:

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

"StoreRocket is not defined" error

The widget script hasn't loaded yet. Make sure you're calling init() in the script's onload callback, not immediately after adding the script tag.

Questions? Hit us up on live chat.

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