Skip to main content

Single-Page Application (SPA) Behavior

If your site is a single-page application (React, Vue, Next.js, Salesforce Commerce Cloud PWA, etc.), route transitions happen client-side without a full page reload. This page explains how polaris.js behaves across those "soft" navigations.

No re-initialization is needed​

polaris.js initializes once per full page load. The consent state it establishes — and everything built on it — persists across client-side route changes for the life of the page:

  • Consent state and events. The visitor's consent settings remain in effect, and consentChanged events continue to fire on the same window whenever the visitor updates their choice. Listeners you attach at startup keep working across navigations.
  • Google Consent Mode / GTM signals. Consent signals set through the TrueVault CMP template persist in the page session. Tags that fire on history-change triggers (SPA "page view" tags) are still evaluated against the current consent state.
  • Script blocking. Blocking of directly installed scripts uses a document-wide watcher that stays active for the whole page session. Scripts your app injects during a route transition with a data-polaris-consent attribute are controlled the same way as scripts present at initial load.

There is no API you need to call on navigation.

Two behaviors help Polaris coexist with frameworks that re-render large parts of the page:

  • The banner re-attaches itself. The consent banner is mounted as a direct child of <body>. If a framework hydration or render pass detaches it, Polaris detects the removal and re-attaches it automatically.
  • Privacy links are re-scanned. Polaris periodically re-scans the page for privacy links (such as elements with the truevault-polaris-optout class), so links in a footer that your app re-renders after a route change are still shown or hidden correctly for the visitor's region. Keep the classes from your Developer Instructions on these links wherever they are rendered.

Requirements that still apply​

  • Include the polaris.js script tag in the initial HTML document (in the <head>, synchronously) — not injected later by your application code. The consent state must be established before consent-gated scripts run.
  • Because polaris.js only initializes on a full page load, a hard navigation (or refresh) re-runs initialization normally; no special handling is needed for mixed hard/soft navigation patterns.
Last updated on