Table of Contents & Menu
On this page
Navigation

Supporting older versions of Safari on iOS

The Alpine.js 3.12.3 version bundled with Hyvä 1.3.0 supports iOS Safari 12.2+ (released 2019-03-25). However, Hyvä's Tailwind CSS classes require iOS Safari 14.5+ (released 2021-04-21).

This guide explains how to extend support for older iOS Safari versions.

Native Alpine.js 3.12.3 vs the Hyvä Bundle

Native Alpine.js 3.12.3 supports iOS Safari 13.4+ (released 2020-03-24) due to its use of the Nullish coalescing operator (??).

Hyvä 1.2.6+ includes a patched Alpine.js version, extending support to iOS Safari 12.2+.

Supporting older versions requires polyfilling JavaScript methods and updating some Tailwind classes in templates.

Option 1: Use Hyvä with Alpine.js v2 & Tailwind CSS v2

For the broadest older browser support, consider building your theme on a Hyvä version that uses Alpine.js v2 and Tailwind CSS v2. The latest such release is 1.1.25.

No Support

Please be aware that we no longer support 1.1.x releases of Hyvä.
New features are developed only for releases based on Alpine v3 and Tailwind v3.

That said, building a theme based on an older Hyvä release can be a good choice, if support for older browsers is required and the existing feature set is sufficient.

Option 2: Polyfill JavaScript Methods

To extend support to iOS Safari 12.0+, add a polyfill for queueMicrotask.

For example:

<script>
if (typeof window.queueMicrotask !== 'function') {
    window.queueMicrotask = function(callback) {
        Promise.resolve()
            .then(callback)
            .catch(e => setTimeout(() => {
                throw e;
            }));
    };
}
</script>

Array.prototype.flat() and flatMap()

For even older iOS Safari versions, polyfill Array.prototype.flat() and Array.prototype.flatMap().

For example:

<script>
if (!Array.prototype.flat) {
    Object.defineProperty(Array.prototype, 'flat', {
        configurable: true,
        value: function flat () {
            var depth = isNaN(arguments[0]) ? 1 : Number(arguments[0]);

            return depth ? Array.prototype.reduce.call(this, function (acc, cur) {
                if (Array.isArray(cur)) {
                    acc.push.apply(acc, flat.call(cur, depth - 1));
                } else {
                    acc.push(cur);
                }

                return acc;
            }, []) : Array.prototype.slice.call(this);
        },
        writable: true
    });
}
if (!Array.prototype.flatMap) {
    Object.defineProperty(Array.prototype, 'flatMap', {
        configurable: true,
        value: function flatMap (callback) {
            return Array.prototype.map.apply(this, arguments).flat();
        },
        writable: true
    });
}
</script>

Option 3: Update Tailwind CSS Classes

Beyond JavaScript polyfills, you'll need to adjust some Tailwind CSS classes. Hyvä themes frequently use the gap property for flexbox styling (e.g., gap-x-2, gap-x-4, gap-y-0, gap-y-1, gap-y-2, gap-y-16).

However, flexbox gap is only supported by iOS Safari 14.5+ (released April 26, 2021).

class="flex gap-x-2"

For older iOS Safari versions, replace gap-* classes with space-* classes when used with flex (e.g., space-x-2, space-y-2).

class="flex space-x-2"

The space-* classes use margin properties, which are universally supported by iOS Safari. Always verify the layout after making changes, as further adjustments may be necessary.

Implementing Polyfills in the <head>

We recommend placing polyfill code directly within the page's <head>. To achieve this, declare a child block for the head.additional block in your layout XML.

For example:

<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd"
>
    <body>
        <referenceContainer name="head.additional">
            <block name="head.alpinejs.polyfills" 
                   template="Magento_Theme::page/js/alpinejs-polyfills.phtml"/>
        </referenceContainer>
    </body>
</page>

Credits

Thanks to Regis Machado (sqli) for the help with the content of this page!

The polyfill implementations on this page were copied from jonathantneal/array-flat-polyfill, where they were released under the CC0 1.0 Universal (CC0 1.0) Public Domain Dedication license.