Table of Contents & Menu
On this page
Navigation

The window.hyva object

When a Hyvä theme is active, the window.hyva JavaScript object provides several helper functions available on every page.

These functions are primarily defined in vendor/hyva-themes/magento2-theme-module/src/view/frontend/templates/page/js/hyva.phtml.

hyva.getCookie(name)

Retrieves the value of a specified cookie.

hyva.setCookie(name, value, days, skipSetDomain)

Sets a cookie. The name and value arguments are required. days and skipSetDomain are optional.

The skipSetDomain argument prevents setting the cookie's domain. Magento's backend behavior is inconsistent, sometimes not setting the domain (e.g., for `mage-messages` in `Magento\Theme\Controller\Result\MessagePlugin::setCookie`). Setting a cookie without `skipSetDomain` to `true` in such cases can result in duplicate cookies.

Cookie consent

By default, cookies are only saved after the visitor has given consent.
To force a cookie to be stored regardless of consent, add its name to the window.cookie_consent_groups.necessary array.

window.addEventListener('load', () => {
  window.cookie_consent_config = window.cookie_consent_config || {};
  window.cookie_consent_config.necessary = window.cookie_consent_config.necessary || [];
  window.cookie_consent_config.necessary.push('my-new-cookie')
})

hyva.setSessionCookie(name, value, skipSetDomain)

Available since Hyvä 1.2.9 and 1.3.5

Sets a session cookie. The name and value arguments are required; skipSetDomain is optional.

This method is identical to hyva.setCookie, but the cookie has no expiry and will be deleted when all browser windows or tabs for the site are closed.

hyva.getBrowserStorage()

Returns the native localStorage if available, otherwise falls back to sessionStorage.

If neither is available (common in iOS Safari private mode), a warning is logged to the console, and false is returned.

Example usage:

const browserStorage = hyva.getBrowserStorage();
if (browserStorage) {
    const private_content_expire_key = 'mage-cache-timeout';
    const cacheTimeout = browserStorage.getItem(private_content_expire_key);
    browserStorage.removeItem(private_content_expire_key);
    browserStorage.setItem(private_content_expire_key, 3600);
}

hyva.postForm(postParams)

Creates a hidden `

` element, populates it with data from `postParams`, and submits it. It automatically includes `uenc` (for Magento redirects) and `form_key` parameters.

The postParams argument is an object for form configuration:

{
  action: "the form action url to post to",
  data: {
    field_a: "value A",
    field_b: "value B"
  },
  skipUenc: false,
}

The optional skipUenc option is available since Hyvä 1.2.4

Example: post form data by clicking a link (using Alpine.js)

<button @click.prevent="hyva.postForm({
  action: 'https://example.test/custom_quote/move/inQuote/',
  data: { id: '<?= $escaper->escapeJs($block->getQuoteId()) ?>' }
})">Request a Quote</button>

hyva.getFormKey()

Returns the current form key value, fetched from the form_key cookie or generated if the cookie doesn't exist.

hyva.trapFocus(Element rootElement)

Available since Hyvä 1.2.6

Restricts keyboard tab navigation to focusable elements within the `rootElement`. The first focusable element is automatically selected.

To release the focus, use hyva.releaseFocus(rootElement), or hide/remove the `rootElement` from the page.

hyva.releaseFocus(Element rootElement)

Available since Hyvä 1.2.6

Removes the focus trap previously initiated by hyva.trapFocus.

hyva.formatPrice(value, showSign, options = {})

Formats the given value using the current currency. The optional showSign argument, if true, always renders a + or - symbol. By default, only - is rendered for negative values.

Available since Hyvä 1.3.6: options

Since Hyvä 1.3.6, an optional options = {} parameter can be passed to the NumberFormat constructor. This allows enforcing minimum/maximum fraction digits, among other settings.

Example of overriding in a custom theme to remove fractions:

<script>
  (() => {
    const origFormatPrice = hyva.formatPrice;
    hyva.formatPrice = function (value, showSign, options = {}) {
      options.maximumFractionDigits = 0; // remove fractions
      return origFormatPrice.call(null, value, showSign, options);
    }
  })()
</script>

Available since Hyvä 1.3.10: options.groupSeparator and options.decimalSeparator

Since Hyvä 1.3.10, the non-standard options groupSeparator and decimalSeparator are also available.

hyva.formatPrice(price, false, {groupSeparator: '-', decimalSeparator: ' .oOo.: '})

For a more in-depth example, see the Overriding JavaScript docs.

hyva.str(string, ...args)

Available since Hyvä 1.1.17

Replaces positional parameters like %1 in the `string` with corresponding additional arguments. The first argument replaces %1, the second %2, and so on.

Example: 

hyva.str('%2 %1 %3', 'a', 'b', 'c') // => "b a c"
To insert a literal % followed by a number, duplicate the % (e.g., %%2 becomes %2).

hyva.str behaves similarly to the Magento PHP function __() for positional parameters, allowing reuse of translation phrases between PHP and JavaScript.

// JavaScript
hyva.str('Welcome %1', customer.firstName);

// PHP
__('Welcome %1', $customer->getFirstname())

hyva.strf(string, ...args)

Available since Hyvä 1.1.14

Replaces positional parameters like %0 in the `string` with corresponding additional arguments. The first argument replaces %0, the second %1, and so on.

Example: 

hyva.strf('%1 %0 %2', 'a', 'b', 'c') // => "b a c"
To insert a literal % followed by a number, duplicate the % (e.g., %%2 becomes %2).

hyva.str vs hyva.strf

hyva.strf is almost identical to hyva.str, but hyva.strf uses %0 for the first argument, while hyva.str uses %1.

hyva.str is generally preferred as its behavior aligns with the Magento PHP function __(), which also uses %1 for the first argument. This allows for consistent reuse of translation phrases.

hyva.replaceDomElement(targetSelector, content)

Available since Hyvä 1.1.14

Replaces the DOM element identified by targetSelector with the innerHTML of the same selector found within the `content` string.

This is useful for updating parts of a page with HTML received from an Ajax request. The function extracts and adds any `