Updating to Venta Theme 1.7.0 (Hyvä 1.5.2) ​

1.7.0 upgrades the underlying Hyvä theme from 1.4.6 to 1.5.2. This is the platform jump the release is built around: product swatches and the product gallery are now PHP-rendered (in the initial HTML instead of client-side JS), the modal system moves to the native HTML <dialog> element, and Tailwind CSS moves to v4.3.

This page covers the Hyvä 1.5.2 platform upgrade. 1.7.0 also ships other changes that are documented in their own sections below.

Three things need manual action on an existing project: the Hyvä composer versions must be aligned, the bundle imports change, and any templates you override in the reworked areas (swatches, gallery, modals) must be re-based. Legacy modal markup keeps working through a deprecated compatibility layer, but its removal is already scheduled; plan the migration now.

Recommended reading:

• Updating to 1.6.4 (the JS bundle and CSP stack this builds on)
• Hyvä's own upgrade notes for every version this jump spans: 1.4.7, 1.4.8, 1.4.10, 1.5.1 and 1.5.2

Prerequisites ​

• Project on Venta Theme 1.6.4 with the JS bundle configured in the project theme. If not, do Updating to 1.6.4 first.
• Node.js 20+.

Pre-flight checklist ​

Run this while the project is still on the current version. It produces the rebase worklist and catches the two things that silently break the build (legacy modal markup, a project view.xml).

1. Prerequisites ​

• Project on the Venta Theme release that 1.7.0 supersedes, with the JS bundle already configured in the project theme. If the bundle is not set up, do the earlier bundle guides first (1.6.3, 1.6.4).
• Node.js 20+ and Composer 2. Confirm the Node version the theme build runs under, not just the host default:

node -v   # must be 20.x or newer
composer --version

• Align the Hyvä packages with 1.7.0 in the same composer update as the theme (see the Composer step). 1.7.0 is a full Hyvä platform jump; the theme and Hyvä versions move together or neither installs.

2. Inventory your template overrides in the reworked areas ​

1.7.0 reworks swatches (Magento_Swatches), the product gallery (Magento_Catalog product view), and the modal chrome (Hyva_Theme/templates/modal). List what your theme overrides in exactly those areas:

git -C app/design/frontend/<Vendor>/<ProjectTheme> ls-files \
  'Magento_Swatches/**' \
  'Magento_Catalog/templates/product/view/gallery*.phtml' \
  'Magento_Catalog/templates/product/list/**' \
  'Hyva_Theme/templates/modal/**' \
  '*hyva_catalog_category_view.xml'

Cross-check that list against the files the release actually changed. Run the diff against a Venta clone at the two tags (Composer installs under vendor/ carry no .git, so diff the source repo, not the vendor copy):

git -C /path/to/magento2-venta-theme fetch --tags
git -C /path/to/magento2-venta-theme diff --name-only <old-tag>..1.7.0 -- \
  Magento_Swatches Magento_Catalog Hyva_Theme

The intersection of the two lists is your rebase worklist. Every file that appears in both must be re-based onto the 1.7.0 version before you judge the storefront.

3. Check for a project view.xml ​

If your project ships its own view.xml, it shadows Venta's 1.7.0 file entirely, including the new swatch image roles and gallery toggles.

find app/design/frontend/<Vendor>/<ProjectTheme> -name view.xml

If that prints a path, add "reconcile view.xml" to the worklist. If it prints nothing, the project inherits Venta's file and no action is needed.

4. Grep for legacy modal markup ​

The div-based modal markup (x-bind="overlay(...)" paired with x-bind="popupContainer") is superseded by the native <dialog> system. A compatibility layer keeps it working, but you need to know where it lives before you upgrade. Scan your overrides, your own modules, and any third-party extension templates:

grep -rEn "x-bind=[\"']overlay|popupContainer" \
  app/design app/code vendor --include='*.phtml'

What changed across the modules ​

1. Update Composer dependencies ​

The Hyvä packages must move together with the theme. 1.7.0 requires Hyvä 1.5.2, and the release line also bumps hyva-themes/magento2-hyva-checkout to 1.3.12:

{
  "require": {
    "hyva-themes/magento2-default-theme": "1.5.2",
    "hyva-themes/magento2-theme-module": "1.5.2",
    "hyva-themes/magento2-hyva-checkout": "1.3.12",
    "magebitcom/magento2-venta-theme": "1.7.0",
    "magebitcom/magento2-venta-theme-module": "1.7.0",
    "magebitcom/magento2-venta-theme-smile-elasticsuite-module": "1.7.0",
    "magebitcom/magento2-venta-theme-back-in-stock-module": "1.1.0"
  }
}

composer update \
  hyva-themes/magento2-default-theme \
  hyva-themes/magento2-theme-module \
  hyva-themes/magento2-hyva-checkout \
  magebitcom/magento2-venta-theme \
  magebitcom/magento2-venta-theme-module \
  magebitcom/magento2-venta-theme-smile-elasticsuite-module \
  magebitcom/magento2-venta-theme-back-in-stock-module \
  --with-dependencies

2. Update your bundle imports ​

Venta's own venta-bundle.js changed in three places. Your project theme maintains its own venta-bundle.js, so mirror all three:

• Remove the modal.js import. The legacy overlay modal implementation is deleted; modals run on the theme-module's native dialog system.
• Add swatch-options.js, directly after configurable-options.js. The swatch component logic moved from phtml JS templates into the bundle.
• Add modal-legacy-compat.js last, after all other imports and before the extension bundle, so window.hyva.modal is augmented before extension JS runs. This is the deprecated compatibility layer for legacy modal markup.

In app/design/frontend/<Vendor>/<ProjectTheme>/web/tailwind/venta-bundle.js:

// remove:
import '../../../../../../../vendor/magebitcom/magento2-venta-theme/web/tailwind/js/bundle/modal.js';

// add, directly after the configurable-options.js import:
import '../../../../../../../vendor/magebitcom/magento2-venta-theme/web/tailwind/js/bundle/swatch-options.js';

// add last, before the extension bundle import:
/* DEPRECATED: keeps legacy modal markup working on the native dialog system.
   Import after all other bundle code and before extension JS. */
import '../../../../../../../vendor/magebitcom/magento2-venta-theme/web/tailwind/js/bundle/modal-legacy-compat.js';

The resulting import block matches Venta's vendor venta-bundle.js:

import '../../../../../../../vendor/magebitcom/magento2-venta-theme/web/tailwind/js/bundle/snap-slider.js';
import '../../../../../../../vendor/magebitcom/magento2-venta-theme/web/tailwind/js/bundle/configurable-options.js';
import '../../../../../../../vendor/magebitcom/magento2-venta-theme/web/tailwind/js/bundle/swatch-options.js';
import '../../../../../../../vendor/magebitcom/magento2-venta-theme/web/tailwind/js/bundle/messages.js';
import '../../../../../../../vendor/magebitcom/magento2-venta-theme/web/tailwind/js/bundle/cart-drawer.js';
import '../../../../../../../vendor/magebitcom/magento2-venta-theme/web/tailwind/js/bundle/header.js';
import '../../../../../../../vendor/magebitcom/magento2-venta-theme/web/tailwind/js/bundle/menu.js';

import '../../../../../../../vendor/magebitcom/magento2-venta-theme/web/tailwind/js/bundle/modal-legacy-compat.js';

import './generated/extension-bundle.js';

3. Migrate legacy modal markup (deprecated) ​

The div-based modal markup with x-bind="overlay" / x-bind="popupContainer" is deprecated. It keeps working through modal-legacy-compat.js, which re-attaches those bindings on top of the native dialog state. The layer will be removed once the Venta extensions have migrated, and your project templates should migrate on the same schedule.

Native dialog markup replaces the overlay container pair with a <dialog> element driven by x-htmldialog:

<!-- legacy (works through the compat layer, scheduled for removal) -->
<div x-bind="overlay('my-dialog')">
    <div x-bind="popupContainer">...</div>
</div>

<!-- native -->
<dialog x-ref="my-dialog" x-bind="dialogConfig" x-htmldialog.noscroll="hide" class="...">
    ...
</dialog>

Use the theme's modal templates as the reference implementations: Hyva_Theme/templates/modal/modal-container.phtml (standard modal) and Magebit_VentaTheme::modal/confirm-container.phtml (confirm popup). The hyva.modal PHP builder API (ModalBuilder) is unchanged; only the markup contract moved.

4. Review your template overrides ​

The File Review step applies as usual. The areas that changed most:

• Swatches. PDP and product-card swatches render server-side through a single shared block, Magento_Swatches/templates/product/swatch-item.phtml. The client-rendered swatch templates are gone: Magento_Swatches/templates/product/js/swatch-options.phtml, .../js/init-configurable-swatch-options.phtml, the PLP product/list/swatch-item.phtml, swatch-item-grid.phtml and swatch-item-list.phtml set, and Magento_Swatches/layout/hyva_catalog_category_view.xml. The Back In Stock oos-swatch-item.phtml and the theme-module sticky-bar/swatch-item.phtml are removed too, both folded into the shared block. If you override any swatch template, re-base onto the shared block; per-render context is passed via block data (is_listing, is_list_mode, is_preselected, attribute_salable_options, render_prefix).
• PLP list view swatches. The list view now renders PDP-style swatches: 48px on desktop and 44px on mobile, with attribute labels and the full option set. The grid view keeps compact 32px swatches. If your project overrides the listing renderer (Magento_Swatches/templates/product/listing/renderer.phtml) or the shared swatch-item.phtml, re-base against the new size and layout branches (is_list_mode drives the PDP-style path; is_listing drives the compact grid path).
• Gallery. The gallery is PHP-rendered with a native dialog lightbox (Magento_Catalog/templates/product/view/gallery.phtml). gallery-slider-image.phtml and its layout block are removed; thumbnails render inline in the gallery pager. gallery_switch_strategy is append.
• Modals. All modal chrome templates moved to the native dialog system (Hyva_Theme/templates/modal/*, checkout magewire and confirmation dialogs). If you override any of them, re-base; the old markup will not close correctly on the new state model.
• Out-of-stock swatches. With the Back In Stock module enabled, out-of-stock options stay selectable and engage the notify flow; all-combination OOS state is server-rendered via data-oos. The visual treatment lives in components/swatches.css: image swatches get a diagonal strike-through line plus a translucent wash that fades the image, and text swatches get a line-through in gray on unselected options. If your project hard-disables OOS options or restyles them in an override, re-base against that file.

5. Reconcile view.xml ​

If your project theme ships its own view.xml, reconcile it with Venta's 1.7.0 file:

• New required entries: the swatch image roles (product_swatch_image_large / _medium / _small) and the swatch_thumb 90x90 size. The PHP-rendered swatches request them.
• Feature toggles, all off by default: swatch hover tooltip (Magento_Swatches / tooltip_enabled), gallery captions (gallery/caption), fullscreen loop (gallery/loop), and prev/next arrows (gallery/nav = none/end/start/center). Absent vars mean off, so a project view.xml that omits them keeps the default look; set a var to opt in.
• gallery_switch_strategy (under the Magento_Swatches vars) must be append for the variant-image behaviour described above.

6. Rebuild and deploy ​

bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush

Before installing, bump the Tailwind toolchain in the project theme's own package.json. This release moves the vendor theme to TailwindCSS 4.3 and @hyva-themes/hyva-modules 1.4, but npm ci installs from the project's lockfile, so without this step the project stays on the old versions:

"@hyva-themes/hyva-modules": "^1.4.0",
"@tailwindcss/cli": "^4.3.0",
"tailwindcss": "^4.3.0"

Run npm install once to refresh package-lock.json (or re-copy package.json and package-lock.json from vendor/magebitcom/magento2-venta-theme/web/tailwind/ and re-apply project-specific script entries, as in Updating to 1.6.3). Then:

cd app/design/frontend/<Vendor>/<ProjectTheme>/web/tailwind
npm ci
npm run build-prod

7. Other changes in 1.7.0 ​

The Hyvä upgrade is the bulk of this release, but not all of it. The rest, by what they ask of you:

Admin widget containers (PDP and PLP) ​

Widget placement on the product page is reworked:

• New labeled containers around the reviews section (product.review.section.before / .after) and a labeled product.info.additional ("Product Additional Info").
• product.info.extrahint moved to directly below the price; product-info.phtml renders it via getChildHtml('extrahint') - keep this slot when re-basing that template.
• The admin widget chooser is filtered through a new CleanWidgetContainerList plugin (etc/adminhtml/di.xml): eleven never-rendering Luma-era containers are hidden and two ambiguous PageBuilder entries relabeled. Child themes wanting different chooser visibility override the plugin's hiddenContainers / relabeledContainers di.xml arguments.
• The PDP buy-button row is now flex flex-wrap gap-3 so widgets added next to the actions no longer overflow on mobile.

Responsive widget images ​

The image grid, image text, team member, quote, category list, brands and image widgets now emit responsive <picture> markup (WebP, 2x retina) through the image resizer, backed by new etc/view.xml image definitions. The image widget's mobile/desktop breakpoint moved to 1024px with a 310x162 mobile size. If you override these widget templates, re-base to the <picture> output; if you ship your own view.xml, add the new image entries or the widgets fall back to unresized files.

Behaviour changes ​

• Out-of-stock products no longer appear in the mini-cart cross-sells slider and are not addable from the Recently Viewed slider.
• AJAX pagination scrolls to the product-list toolbar instead of the page top, in both directions.
• Checkout address list: the selected address stays visible when the list collapses, and the "Show All" toggle works on the first click.
• The mini-search input no longer causes a slight horizontal scroll on mobile.
• Product-page breadcrumbs render client-side via Hyvä's built-in breadcrumb feature, with the Venta styling applied, so the PDP is no longer tied to the navigated category path and can be fully page-cached. The breadcrumb bar reserves its height before the client render to avoid layout shift. If you override Magento_Catalog/templates/product/view/breadcrumbs.phtml, re-base it onto the 1.7.0 version.
• The theme's breadcrumb JSON-LD is skipped when the Magebit SEO schema is active, so the page no longer emits duplicate BreadcrumbList structured data; the product-page trail uses the product's canonical category. Product names stored with HTML entities (for example ®) now render the decoded symbol in the breadcrumb instead of the raw entity, on every page that uses the breadcrumb template.
• The "Remove white bars from product gallery" setting no longer forces cover mode on widget and CMS images; it now affects the PDP gallery only. Retina (2x) variants are clamped to the source image dimensions, so a source smaller than twice the target size no longer renders half-size on high-DPR screens. See Background adjustments.

Composer constraints ​

Besides the Hyvä packages, the release pins mollie/magento2 to ~3.0.2 and hyva-themes/magento2-hyva-checkout to 1.3.12 (security release). Reconcile these when your project's composer constraints differ.

8. Behaviour notes ​

No action required, but worth knowing after the upgrade:

• Preselect URLs (?color=…&size=…) now render the checked swatches, selected labels and the notify state server-side, cached per URL, so there is no hydration layout shift. A preselect-aware block cache key keeps preselect and parameter-less pages from poisoning each other.
• Swatch tooltips (when enabled) are suppressed on touch devices, since hover tooltips have no dismiss affordance there.
• PageBuilder sliders run on the bundled snap-slider; the bundle exposes window.SnapSlider for Hyvä's PageBuilder DOM widgets.
• Product cards and the PDP gallery are in the initial HTML, which improves SEO and LCP compared with the previous client-rendered variants.

Post-upgrade verification ​

Walk this after the local deploy (setup:upgrade, di:compile, static-content:deploy -f, cache:flush, and the theme build-prod). Each item maps to a surface this release changed and a way it is known to break.

1. JS build completed. npm run build-prod exits clean. If it fails with a missing-file error, the removed modal.js import is still in venta-bundle.js. Remove it and rebuild.
2. Bundle loads on the checkout success page. Place a test order through to the success page and confirm venta-bundle.min.js loads with no CSP integrity error in the console. On Magento 2.4.8+ a stale sri-hashes.json blocks it, and the success page is the first place that shows. If it is blocked, re-run setup:static-content:deploy -f after the JS rebuild so the hashes match.
3. Caches flushed before judging. block_html full-page caching serves stale template output. If a template change is not visible, run bin/magento cache:flush before concluding anything is wrong.
4. PDP swatches react to selection. On a configurable product, clicking a swatch updates price, gallery, and add-to-cart state. Dead swatches mean swatch-options.js is not in the bundle. Add the import and rebuild.
5. PLP grid swatches react. On a category page in grid view, swatches on the product cards respond to hover and selection.
6. PLP list swatches react. Switch the same category to list view. List view has its own swatch rendering distinct from grid; verify it separately, since an override rebased only for grid leaves list dead.
7. Gallery updates on swatch change, no stuck placeholder. Selecting a size or colour swaps the gallery to the variant image. The placeholder must not stay pinned after the switch (this was fixed in the theme; if you see it, the build is stale, so rebuild and re-deploy static content).
8. Preselect URL renders state server-side. Open a PDP with ?color=<value>&size=<value>. View source (not the hydrated DOM) and confirm the matching swatches are already checked and the labels selected in the raw HTML. This state is server-rendered and cached per URL.
9. view.xml toggles behave. If the project ships its own view.xml, confirm the swatch image roles resolve (swatches show images, not broken thumbnails) and that any gallery toggle you did not add is off - an absent variable means off, not inherited.
10. Modals open and close. Open a modal that uses the native system (for example a confirm dialog) and one that still uses legacy markup if any remain. Both must close correctly on the new dialog state model.
11. Login state is correct in the account menu and back-in-stock block. Log in, then confirm the account menu and the back-in-stock subscribe block show the logged-in state. Both derive from customer section data; if they show logged-out while you are logged in, the section data is stale.
12. PageBuilder CMS sliders render as sliders. Open a CMS page with a PageBuilder slider and confirm it slides rather than stacking as static columns. The bundle exposes window.SnapSlider for Hyvä's PageBuilder widgets.

Troubleshooting ​

Symptoms observed during the 1.7.0 upgrade, with cause and fix.