JavaScript API

The plugin’s front-end script, switcher.js, adds a small JavaScript API on window.wccs and sends a browser event whenever the page shows a new currency. Use it to open the currency popup from your own button, to update your own widgets when the currency changes, or to read the visitor’s currency in a script. For example, a header icon can open the switcher, and a shipping banner can redraw itself in EUR when the visitor switches to EUR.

When the API is there#

switcher.js loads on any front-end page that carries price data for several currencies (see The currency cookie and price data), a [wccs_switcher], the nav menu switcher or a [wccs_rate] without a to attribute. It loads in the footer, so use the API after the page has loaded (for example inside a DOMContentLoaded listener or in a click handler).

Some methods only exist when a [wccs_switcher] popup switcher is on the page:

Method	Available	What it does
wccs.open(), wccs.close(), wccs.toggle()	When a switcher is on the page	Open, close or toggle the currency popup. With several switchers on a page, these control the last one.
wccs.current()	When a switcher is on the page	Returns the value of the currency cookie, for example "EUR", or an empty string.
wccs.isRTL()	When a switcher is on the page	Returns true when the page is right to left.
wccs.applyCurrency( 'EUR' )	Always	Shows every embedded price, rate text, switcher label and nav menu item on the page in that currency. It does not write the cookie, so the next page load uses the cookie again.
wccs.geoSwitch()	Always	Reads the cookie and applies its currency to the page. Use it after you set the cookie yourself.

On cart, checkout and order pay pages with Lock currency at checkout turned on, the switcher is locked and does not set up these methods.

The wccs:currency event#

Each time the page starts showing a different currency, the script fires a wccs:currency event on document. The new code is in event.detail.currency. It fires:

• when the page loads and the script applies the cookie currency (in both Reload and Instant mode),
• after first-visit geo detection sets the currency,
• in Instant mode (beta), right after the prices are swapped,
• when the visitor comes back to a tab after switching currency in another tab (not on cart, checkout or account pages).

It does not fire again for the currency the page already shows.

The page config#

window.wccsInstant is printed on every front-end page: active (the currency the page shows), cookie (the cookie name), days (the cookie lifetime), mode (reload or instant) and wc_page (true on cart, checkout and account pages).

Examples#

A custom button that opens the switcher:

<button type="button" onclick="window.wccs && wccs.open && wccs.open()">Change currency</button>

Redraw your own widget when the currency changes:

document.addEventListener('wccs:currency', function (event) {
  var code = event.detail.currency; // for example "KWD"
  document.querySelectorAll('.my-currency-label').forEach(function (el) {
    el.textContent = code;
  });
});

Switch the currency from your own link, the same way the switcher does in Reload mode (write the cookie, then reload the same URL):

function switchCurrency(code) {
  var cfg = window.wccsInstant || {};
  var name = cfg.cookie || 'wccs_currency';
  var days = cfg.days || 30;
  var expires = new Date(Date.now() + days * 86400000).toUTCString();
  document.cookie = name + '=' + encodeURIComponent(code) + ';expires=' + expires + ';path=/';
  location.reload();
}

The code must be one of your enabled currencies; any other value is ignored. For links in emails or on other sites, use a ?wccs_cur=CODE link instead (see Developer overview and PHP functions).

Good to know#

• wccs.applyCurrency() only changes what the page shows. Totals worked out by the server, such as shipping and the cart, change only after the cookie is set and the page is loaded again.
• Prices added after the page loads (load more, infinite scroll, quick view, AJAX filters) and the price of a chosen variation are swapped to the cookie currency automatically.
• The [wccs_converter] widget listens to wccs:currency too.

Related docs#

• Reload vs Instant switching
• The currency cookie and price data
• Filters and actions
• Adding the currency switcher