PHPackages zwernemann/magento2-swup - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. zwernemann/magento2-swup ActiveMagento2-module zwernemann/magento2-swup ======================== swup.js page transition integration for Magento 2 00JavaScript Since Mar 9Pushed 2mo agoCompare [ Source](https://github.com/Zwernemann/magento2-swup)[ Packagist](https://packagist.org/packages/zwernemann/magento2-swup)[ RSS](/packages/zwernemann-magento2-swup/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependenciesVersions (1)Used By (0) Zwernemann\_Swup – Page Transitions for Magento 2 ================================================= [](#zwernemann_swup--page-transitions-for-magento-2) Integrates [swup.js](https://swup.js.org) (v4) into Magento 2 to enable smooth, animated page transitions without a full-page reload. Fully configurable from the Magento backend, compatible with Full Page Cache / Varnish, and aware of Magento's customer-section mechanism. --- Features -------- [](#features) - Smooth page transitions (fade, slide in four directions, or none) - Optional loading progress bar (no extra plugin required) - Full Page Cache / Varnish compatible – swup reads the same cached HTML a regular browser request would receive - Automatic CSRF `form_key` update after each transition - Automatic reload of Magento private/customer sections (mini-cart, wishlist, login state) - Automatic re-execution of inline and external `` tags in replaced containers - Configurable container selector, link selector, and ignored paths - `[data-no-swup]` attribute to opt individual links out of swup navigation - Custom `swup:pageView` DOM event for analytics / tag manager integration - Per-store-view configuration --- Requirements ------------ [](#requirements) DependencyVersionPHP>= 8.1Magento Framework>= 103.0 (Magento 2.4.x)--- Installation ------------ [](#installation) ### Via Composer (recommended) [](#via-composer-recommended) ``` composer require zwernemann/magento2-swup bin/magento module:enable Zwernemann_Swup bin/magento setup:upgrade bin/magento cache:flush ``` ### Manual [](#manual) 1. Copy the `app/code/Zwernemann/Swup` directory into your Magento installation at the same path. 2. Run the setup commands: ``` bin/magento module:enable Zwernemann_Swup bin/magento setup:upgrade bin/magento cache:flush ``` --- Configuration ------------- [](#configuration) Navigate to **Stores → Configuration → Zwernemann → Swup – Page Transitions**. ### General [](#general) SettingDefaultDescriptionEnable swup.jsYesMaster switch. Disabling this removes swup completely without touching any other setting.Content Container Selector`main`CSS selector for the element swup replaces on each navigation. Must be unique and present on **every** page.Link Selector`a[href]:not(…)`CSS selector for links intercepted by swup. External links, anchors (`#`), `mailto:`, and `tel:` links are excluded by default.### Appearance & Animation [](#appearance--animation) SettingDefaultDescriptionPage Transition AnimationFadeVisual effect when switching between pages (see [Animations](#animations)).Transition Duration (ms)`400`Duration of the animation in milliseconds. Must match the generated CSS transition time.Show Loading Progress BarYesDisplays a thin progress bar at the top of the screen during page loads.Progress Bar Color`#0099ff`Any valid CSS color value (hex, `rgb()`, named color).Progress Bar Height (px)`3`Height of the progress bar in pixels.Scroll to Top on NavigationYesAutomatically scrolls to the top of the page after each transition.### Advanced & Magento Integration [](#advanced--magento-integration) SettingDefaultDescriptionEnable swup Client-Side CacheNoswup can cache fetched pages in memory for instant back-navigation. **Keep disabled** on stores with session-specific content (cart, customer data) to prevent stale data. Magento's own FPC is unaffected.Ignore Paths`/checkout` `/customer/account` `/admin`One URL path fragment per line. Any link whose `href` contains one of these strings will trigger a normal full-page request instead of a swup transition.--- Animations ---------- [](#animations) ValueEffect`none`Instant switch – no CSS transition`fade`Cross-fade (opacity)`slide-left`Old page slides left, new page enters from right`slide-right`Old page slides right, new page enters from left`slide-up`Old page slides up, new page enters from below`slide-down`Old page slides down, new page enters from aboveThe required CSS is generated inline by the module and automatically uses the configured transition duration. --- Opting out individual links --------------------------- [](#opting-out-individual-links) Add the `data-no-swup` attribute to any link (or a parent element) to force a full-page navigation: ``` Special page Checkout Login ``` --- JavaScript Event – `swup:pageView` ---------------------------------- [](#javascript-event--swuppageview) After every successful page transition the module dispatches a custom DOM event that analytics tools and tag managers can listen to: ``` document.addEventListener('swup:pageView', function (event) { console.log('New page:', event.detail.url, event.detail.title); // Google Analytics 4 example: gtag('event', 'page_view', { page_location: event.detail.url, page_title: event.detail.title }); }); ``` `event.detail` contains: KeyTypeValue`url``string`Full URL of the newly rendered page`title``string``document.title` after content replacement--- Head Synchronisation -------------------- [](#head-synchronisation) Magento generates **per-page-type CSS bundles** (different files for CMS pages, category pages, product pages, etc.). Because swup only replaces the configured container and leaves `` untouched, CSS required by the new page might never be loaded — causing broken styles such as stretched videos or unexpected button appearances. The module bundles the official **[SwupHeadPlugin](https://swup.js.org/plugins/head-plugin/) (`@swup/head-plugin` v2)** as a UMD build — no npm step required. On every navigation it diffs the fetched `` against the current one, removes tags that are gone and adds tags that are new. Browsers do not re-download already-cached stylesheets because matching tags are kept in place. Magento's RequireJS config scripts (``) and the module's own inline `` tag are marked as `persistTags` so they are never removed from `` during navigation. --- Full Page Cache & Varnish Compatibility ------------------------------------------- [](#full-page-cache--varnish-compatibility) swup fetches the target URL via an XHR request with `Accept: text/html`. Magento's FPC (and Varnish in front of it) serves the same cached full-page HTML that a regular browser would receive. swup then extracts only the configured container element from the response on the client side. This means: - The swup request is **served from cache** – no cache bypass. - **No Varnish VCL changes** are required. - The `X-Requested-With: swup` request header is sent so custom server-side logic can detect swup requests if needed. --- Magento Customer Sections (Cart, Wishlist, Login State) ------------------------------------------------------- [](#magento-customer-sections-cart-wishlist-login-state) After each page transition the module calls `customerData.reload([], false)`. This reloads all previously loaded private/customer sections from Magento's section API so personalised blocks (mini-cart counter, wishlist, logged-in greeting, etc.) reflect the current session state without a full page reload. The CSRF `form_key` is also refreshed in the newly inserted content by reading the current `form_key` cookie value. --- Script Re-execution ------------------- [](#script-re-execution) Browsers do not execute `` tags that are injected into the DOM via `innerHTML` — which is exactly how swup replaces container content. Without special handling, any inline or external scripts embedded in the page content would silently do nothing after a swup navigation. After each `content:replace` the module iterates over every `` element in the replaced containers and recreates it as a fresh DOM node, causing the browser to treat it as a newly parsed script and execute it. All attributes (`src`, `async`, `defer`, `data-*`, …) are preserved. **Magento-specific script types are intentionally excluded** from this re-execution: TypeReason`text/x-magento-init`Processed by `mage/apply/main` when `contentUpdated` fires — re-executing them here would initialise widgets twice and cause errors.`text/x-magento-template`Knockout.js template blocks, not executable JavaScript.`text/html` / `text/template`Generic template containers, not executable JavaScript.This means third-party extension scripts, CMS block snippets, and custom inline scripts work automatically, while Magento's own widget bootstrapping path remains unchanged. --- Module Structure ---------------- [](#module-structure) ``` app/code/Zwernemann/Swup/ ├── Block/ │ └── SwupInit.php # Block: renders config JSON for the template ├── Helper/ │ └── Config.php # Reads all backend settings; provides getJsConfig() ├── Model/Config/Source/ │ └── Animation.php # Dropdown options for the animation selector ├── etc/ │ ├── acl.xml # Admin ACL resource │ ├── adminhtml/system.xml # Backend configuration fields │ ├── config.xml # Default configuration values │ └── module.xml # Module declaration ├── registration.php └── view/frontend/ ├── layout/default.xml # Injects the SwupInit block on every frontend page ├── requirejs-config.js # Maps "swup" alias to the bundled UMD build ├── templates/swup_init.phtml # Renders inline CSS + RequireJS bootstrap └── web/js/ ├── swup-init.js # swup initializer (RequireJS module) └── swup.min.js # Bundled swup v4 UMD build (no npm required) ``` --- License ------- [](#license) MIT ### Health Score 19 — LowBetter than 10% of packages Maintenance58 Moderate activity, may be stable Popularity0 Limited adoption so far Community6 Small or concentrated contributor base Maturity11 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Community Maintainers ![](https://www.gravatar.com/avatar/ab806201fa0b72cada23b094f57e8d6e96aca483badab47bf710dfd2f2e19f4b?d=identicon)[Zwernemann](/maintainers/Zwernemann) --- Top Contributors [![Zwernemann](https://avatars.githubusercontent.com/u/52236002?v=4)](https://github.com/Zwernemann "Zwernemann (3 commits)") --- Tags magento2module ### Embed Badge ![Health badge](/badges/zwernemann-magento2-swup/health.svg) ``` [![Health](https://phpackages.com/badges/zwernemann-magento2-swup/health.svg)](https://phpackages.com/packages/zwernemann-magento2-swup) ``` PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)