Using the Alpine Plugins x-intersect and x-collapse in the Hyva Theme

1. When plain x-data code is enough, and when a plugin pays off

For simple, one off interactions like toggling a CSS class on click, plain x-data code remains the right choice, an extra plugin would just be overhead there. But once browser APIs like the IntersectionObserver, or recurring, easily mishandled animation logic come into play, reaching for an official Alpine plugin pays off, because the core team's implementation covers edge cases that are easy to miss in a hand rolled version.

Typical edge cases in hand rolled IntersectionObserver code are missing cleanup when a component is removed from the DOM, which leads to memory leaks, or miscalculated root margin values with nested scroll containers. x-intersect encapsulates these pitfalls, and x-collapse solves the problem of smoothly animating dynamic heights without fixed pixel values, something plain CSS transition: height only handles with awkward workarounds.

2. x-intersect basics: syntax and modifiers

x-intersect runs an expression exactly when the element the directive is attached to enters the visible viewport, implemented internally through a managed IntersectionObserver. The .once modifier makes the expression fire only on the first entry, after which the observer automatically unsubscribes, ideal for one off actions like lazy loading.

The .threshold modifier controls what percentage of the element must be visible before the expression fires, and .margin adds extra buffer, for instance to start preloading an image just before it actually becomes visible. Together, both modifiers replace manually configuring a rootMargin and threshold object that you would otherwise have to write by hand when calling IntersectionObserver directly.

<div x-data
     x-intersect.threshold.50.margin.200px="visible = true"
     x-data="{ visible: false }">
  <img :src="visible ? '/media/catalog/product/img.jpg' : placeholderSrc"
       loading="lazy" alt="Product image">
</div>

3. Practical example: lazy loading images and components

For product images below the initial viewport, the native loading="lazy" attribute, evaluated by the browser itself, is often enough on its own. x-intersect becomes relevant once accompanying logic needs to fire alongside the image, for instance loading a heavier comparison widget or initializing star rating rendering only once the component is actually in view.

In the following example, an entire product review component is loaded via Ajax only once it enters the viewport, instead of being loaded during the initial page build. That noticeably reduces the number of Ajax calls needed for the first render, especially on long category pages with many product tiles.

function reviewWidget(productId) {
  return {
    loaded: false,
    reviews: [],
    init() {
      // x-intersect calls loadReviews() only once actually visible
    },
    loadReviews() {
      if (this.loaded) return;
      this.loaded = true;
      fetch(`/rest/V1/products/${productId}/reviews`)
        .then((response) => response.json())
        .then((data) => { this.reviews = data; });
    },
  };
}

4. Infinite scroll on the category page with x-intersect

A sentinel element at the end of the product list, bound to x-intersect.half, triggers loading the next product page once it becomes half visible. It is important to move the sentinel to the new end of the list after every load, otherwise the directive only fires once and infinite scroll stops after the second page.

For Magento category pages it is worth adding a server side limit on how many pages get loaded, plus a clearly visible loading indicator, since customers otherwise cannot tell whether more products are actually coming or the end of the list has already been reached. Silent, invisible loading with no feedback is especially confusing on a slow connection.

function categoryInfiniteScroll(baseUrl) {
  return {
    page: 1,
    loading: false,
    finished: false,
    loadNextPage() {
      if (this.loading || this.finished) return;
      this.loading = true;
      fetch(`${baseUrl}&p=${this.page + 1}`)
        .then((response) => response.json())
        .then((data) => {
          this.page += 1;
          this.finished = data.items.length === 0;
          this.loading = false;
        });
    },
  };
}

5. x-collapse basics: smooth height transitions

x-collapse animates showing and hiding an element based on its actual height, instead of abruptly toggling display: none. The plugin measures the element's current scrollHeight at runtime and animates cleanly between values, which is noticeably more robust for variable, dynamically generated content, such as product descriptions of differing length, than a hard coded max-height in Tailwind.

The difference from a plain x-show solution with a CSS transition lies exactly in this height calculation: x-show with an opacity or transform transition visually hides content but, depending on configuration, still occupies space or jumps abruptly, while x-collapse animates the space itself smoothly and then correctly removes the element from document flow.

<div x-data="{ expanded: false }">
  <button type="button" @click="expanded = !expanded" :aria-expanded="expanded">
    Product description
  </button>
  <div x-show="expanded" x-collapse.duration.300ms>
    <p><?= $block->escapeHtml($product->getDescription()) ?></p>
  </div>
</div>

6. Use cases: faceted filters, FAQ accordions, mobile submenus

In faceted navigation, x-collapse makes long attribute lists like size or color expand and collapse cleanly, without the rest of the filter area jumping abruptly when a section opens. For an FAQ accordion on a category page or in additional product information, the same plugin solves exactly the same problem, with the same attribute written once.

Nested mobile navigation menus benefit too, since submenus correctly push the surrounding container's height when opening, instead of overlapping content below. Because x-collapse measures the actual content height at runtime, it also works reliably across translations with substantially different text length, without maintaining a separate height per language.

7. CSP compliant integration: no CDN, bundled locally

Alpine plugins must never be loaded from a CDN via a script tag in Hyva, since that would violate both the Content Security Policy and the principle of not pulling in extra external dependencies. Instead, @alpinejs/intersect and @alpinejs/collapse are added as npm packages in package.json and folded into the theme's bundled JavaScript through the existing build process.

After installation, the plugins are imported ahead of the Alpine core and registered via Alpine.plugin() before Alpine.start() is called. That order matters: if a plugin is registered only after start, x-intersect or x-collapse attributes already present in the DOM will not take effect, because Alpine does not know their directives during its initial scan.

import Alpine from 'alpinejs';
import intersect from '@alpinejs/intersect';
import collapse from '@alpinejs/collapse';

Alpine.plugin(intersect);
Alpine.plugin(collapse);

document.addEventListener('alpine:init', () => {
  // Store and component registrations go here
});

window.Alpine = Alpine;
Alpine.start();

8. CSP compatibility: what to watch for in plugins generally

The official Alpine core plugins such as intersect, collapse, focus, and persist use only standard browser APIs and no eval() or new Function() whatsoever, which lets them run without issue under a strict CSP with no unsafe-eval, exactly what Hyva requires. For third party plugins outside the official Alpine ecosystem, it is always worth checking the source for dynamic code evaluation before adopting them.

A simple practical test is opening the theme in a browser with the CSP active and watching the console for Content Security Policy violations while deliberately triggering every newly added plugin feature once. If the console stays clean, the plugin is fit for production use in a CSP hardened Hyva theme.

9. A custom Alpine.directive() when no plugin fits

Not every use case has a matching official plugin. For recurring, project specific logic needed identically in several places across the theme, such as automatically focusing a field when a modal appears, a custom directive registered through Alpine.directive() is worth writing, instead of copying the same x-data logic in ten different places.

A custom directive is registered exactly like a core plugin before Alpine.start() and gets access to the element as well as the expression, modifiers, and reactive effects through the same API the official plugins use. That is the right middle ground between copied x-data code and a fully maintained, standalone npm package for a single, small piece of functionality.

Alpine.directive('autofocus-on-show', (el, { expression }, { effect, evaluate }) => {
  effect(() => {
    if (evaluate(expression)) {
      requestAnimationFrame(() => el.focus());
    }
  });
});
// Usage: <input x-show="modalOpen" x-autofocus-on-show="modalOpen">

10. Summary

11. FAQ: Alpine Plugins in Hyva