# hyva-themes/magento2-theme-module

> Hyva Themes companion module

`composer require hyva-themes/magento2-theme-module`

Canonical URL: https://packagento.com/hyva-themes/magento2-theme-module

## At a glance

- **Vendor**: hyva-themes (https://packagento.com/hyva-themes.md)
- **Latest version**: 1.5.2 — released 2026-07-10
- **Pricing**: Free
- **Package type**: Magento 2 module
- **Status**: active, accepting new buyers

## Installation

Packagento is licence-gated, so even free packages need a licence on a project before Composer can resolve them.

1. **Sign in or create an account** at https://packagento.com/customer/account/.

2. **Add the package to your account.** Open https://packagento.com/hyva-themes/magento2-theme-module and complete the free checkout. A licence is minted automatically.

3. **Create or pick a project, then activate the licence on it.**
   - Projects represent the Magento installs you deploy to. Manage them at https://packagento.com/projects/.
   - Activate the new licence on the project you'll deploy this package to. Activation is what generates the Composer credentials scoped to that project.

4. **Add the project credentials to your Magento codebase.**

   Grab the project's public + private key from https://packagento.com/projects/ (open the project, then its Credentials tab), and add them to `auth.json`:

   ```json
   {
     "http-basic": {
       "packagento.com": {
         "username": "ppk_live_...",
         "password": "psk_live_..."
       }
     }
   }
   ```

   Add the Packagento Composer repository to `composer.json`:

   ```json
   {
     "repositories": [
       { "type": "composer", "url": "https://packagento.com" }
     ]
   }
   ```

5. **Install and apply.**

   ```bash
   composer require hyva-themes/magento2-theme-module:*
   bin/magento setup:upgrade
   bin/magento setup:di:compile
   bin/magento cache:flush
   ```

## What it does

Hyva Themes companion module

## README

[![Hyvä Themes](https://hyva.io/media/wysiwyg/logo-compact.png)](https://hyva.io/)

### hyva-themes/magento2-theme-module

Core Hyvä Themes framework module for Magento 2, providing shared theme infrastructure used by Hyvä storefront themes.

![Supported Magento Versions][ico-compatibility]

### Requirements

Compatible with Magento 2.4.4-p9 and higher.

### Scope

This package provides the Hyvä theme framework module. It does not include a storefront theme; install `hyva-themes/magento2-default-theme` for the default frontend theme assets.
 
### Hyvä Theme Module Installation

The Hyvä Theme module is commonly installed as a dependency of the Hyvä default theme `hyva-themes/magento2-default-theme`.  
The following instructions describe how to install the Hyvä Theme module explicitly.

#### Step 1: Configure composer repositories

The recommended way to install the Hyvä Theme module is with a Hyvä Private Packagist key. This will make related Hyvä packages available.
Alternatively, the module can be installed from GitHub.

Choose one of the following options:

##### Option 1: Installation from Hyvä Private Packagist (Recommended)

Get a free key by registering an account at [www.hyva.io](https://www.hyva.io) and creating one from your account dashboard.

You will receive instructions like the following after creating your Packagist key:

```sh
## this command adds your key to your project's auth.json file
## replace yourLicenseAuthenticationKey with your own key
composer config --auth http-basic.hyva-themes.repo.packagist.com token yourLicenseAuthenticationKey
## replace yourProjectName with your project name
composer config repositories.private-packagist composer https://hyva-themes.repo.packagist.com/yourProjectName/
```

##### Option 2: Installation from GitHub

To install the module directly from GitHub, configure the repository as a composer repository.

```sh
composer config repositories.hyva-themes/magento2-theme-module git https://github.com/hyva-themes/magento2-theme-module.git
composer config repositories.hyva-themes/magento2-mollie-theme-bundle git https://github.com/hyva-themes/magento2-mollie-theme-bundle.git
```

#### Step 2: Install the module

Install the module and its dependencies with composer:

```sh
composer require hyva-themes/magento2-theme-module
```

#### Step 3: Post-install actions

- After installing the module, run the Magento setup command:

  ```sh
  bin/magento setup:upgrade
  ```

### Support / Docs

- Documentation: [https://docs.hyva.io](https://docs.hyva.io)
- Account and downloads: [https://www.hyva.io](https://www.hyva.io)

### License

This package is licensed under the **Open Software License (OSL 3.0)**.

* **Copyright:** Copyright © 2020-present Hyvä Themes. All rights reserved.
* **License Text (OSL 3.0):** The full text of the OSL 3.0 license can be found in the `LICENSE.txt` file within this package, and is also available online at [http://opensource.org/licenses/osl-3.0.php](http://opensource.org/licenses/osl-3.0.php).

#### Additional Licenses for Included Assets

This package also contains Alpine.js and SVG icons under separate licenses:

* **Alpine.js:** Copyright © 2019-2025 Caleb Porzio and contributors and distributed under the MIT license. The full text of this license can be found in `src/view/base/web/js/ALPINE_LICENSE_MIT.txt` or online at [raw.githubusercontent.com/alpinejs/alpine/refs/heads/main/LICENSE.md](https://raw.githubusercontent.com/alpinejs/alpine/refs/heads/main/LICENSE.md)  
* **Heroicons:** SVG icons from [https://heroicons.com/](https://heroicons.com/) are licensed under the MIT license. The full text of this license can be found in `src/view/frontend/web/svg/heroicons/HEROICONS_LICENSE_MIT.txt`.
* **Lucide Icons:** SVG icons from [https://lucide.dev/](https://lucide.dev/) are licensed under the Lucide license. The full text of this license can be found in `src/view/base/web/svg/lucide/LUCIDEICONS_LICENSE.txt` and online at [https://lucide.dev/license](https://lucide.dev/license).
* **AlpineJS Dialog** library from Fylgja (https://github.com/fylgja/alpinejs-dialog) is distributed under the MIT license. The full text of this license can be found in `src/view/base/templates/page/js/plugins/HTMLDIALOG_LICENSE_MIT.txt` or online at [raw.githubusercontent.com/fylgja/alpinejs-dialog/refs/heads/main/LICENSE](https://raw.githubusercontent.com/fylgja/alpinejs-dialog/refs/heads/main/LICENSE)

### Changelog
Please see [The Changelog](CHANGELOG.md).

[ico-compatibility]: https://img.shields.io/badge/magento-%202.4-brightgreen.svg?logo=magento&longCache=true&style=flat-square

## Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).

### [Unreleased]

[Unreleased]: https://gitlab.hyva.io/hyva-themes/magento2-theme-module/-/compare/1.5.2...main

### [1.5.2] - 2026-07-10

[1.5.2]: https://gitlab.hyva.io/hyva-themes/magento2-theme-module/-/compare/1.5.1...1.5.2

This release contains the same changes as [1.4.9].

#### Added

-   Nothing Added

#### Changed

-   **Updated `snap-slider` to v2.2.3**  
    For more information, please refer to [merge request #692](https://gitlab.hyva.io/hyva-themes/magento2-theme-module/-/merge_requests/692).

#### Removed

-   Nothing Removed

### [1.5.1] - 2026-07-01

[1.5.1]: https://gitlab.hyva.io/hyva-themes/magento2-theme-module/-/compare/1.5.0...1.5.1

This release contains the same changes as [1.4.8].

### [1.5.0] - 2026-06-30

[1.5.0]: https://gitlab.hyva.io/hyva-themes/magento2-theme-module/-/compare/1.4.7...1.5.0

#### Added

-   Nothing Added

#### Changed

-   **Modernize modal system to use HTML Dialog element with `x-htmldialog`**  
    The Hyva modal is rebuilt on the HTML Dialog element powered by the `x-htmldialog` plugin introduced in v1.4.0.
    Both the legacy Hyva modal and `x-htmldialog` now share the same foundation, removing a parallel implementation and all the custom logic it required.

    -   Focus trapping, Escape key handling, scroll locking, and backdrop click are now handled by the browser. The JavaScript implementation shrinks by roughly 80 lines as a result.
    -   Backdrop styling moves to Tailwind's `backdrop:*` utilities on the `<dialog>` element, replacing the overlay and container div wrappers and their associated class methods.
    -   A new `withCloseby()` builder method controls close behaviour: `"any"` (ESC or click outside, the default), `"closerequest"` (ESC only), or `"none"` (never auto-close).
    -   Deprecated builder methods (`withOverlayClasses()`, `withContainerClasses()`, `excludeSelectorsFromFocusTrap()`) log a deprecation warning.
        Use `backdrop:*` utilities and native dialog focus management instead.
    -   The HTML Dialog element exposes correct ARIA semantics and manages focus restoration to the trigger element without custom code.

    If you have custom JavaScript implementations of the Hyva modal, refer to the [upgrade guide](https://docs.hyva.io/hyva-themes/upgrading/upgrading-to-1-5-0.html) for details.

    For more information, please refer to [merge request #638](https://gitlab.hyva.io/hyva-themes/magento2-theme-module/-/merge_requests/638).

-   **PageBuilder: Update image size fields to Magento naming**  
    For more information, please refer to [issue #510](https://gitlab.hyva.io/hyva-themes/magento2-theme-module/-/work_items/510#note_84957).

#### Removed

-   Nothing Removed

### [1.4.10] - 2026-07-10

[1.4.10]: https://gitlab.hyva.io/hyva-themes/magento2-theme-module/-/compare/1.4.8...1.4.10

#### Added

-   Nothing Added

#### Changed

-   **Fixed `hyva:sampledata:deploy` not working on Mage-OS**  
    For more information, please refer to [merge request #686](https://gitlab.hyva.io/hyva-themes/magento2-theme-module/-/merge_requests/686).

-   **Fixed `hyva:sampledata:deploy` treating an unverifiable sample data package check as not available**  
    For more information, please refer to [merge request #682](https://gitlab.hyva.io/hyva-themes/magento2-theme-module/-/merge_requests/682).

-   **Fixed a fatal error when the compiled DI cache is stale and `hyvaBaseThemes` compiles as `null`**  
    For more information, please refer to [merge request #684](https://gitlab.hyva.io/hyva-themes/magento2-theme-module/-/merge_requests/684).

_(Changelog truncated for .md surface. Full history on https://packagento.com/hyva-themes/magento2-theme-module.)_

## Recent Versions

| Version | Released |
|---|---|
| 1.5.2 | 2026-07-10 |
| 1.4.10 | 2026-07-10 |
| 1.4.9 | 2026-07-10 |
| 1.5.1 | 2026-07-01 |
| 1.4.8 | 2026-07-01 |
| 1.5.0 | 2026-06-30 |
| 1.4.7 | 2026-06-30 |
| 1.4.6 | 2026-05-12 |
| 1.4.5 | 2026-03-16 |
| 1.3.22 | 2026-03-16 |

Showing 10 of 89 versions. Full release history on https://packagento.com/hyva-themes/magento2-theme-module.

## Dependencies

### Require

| Package | Constraint |
|---|---|
| ext-simplexml | * |
| hyva-themes/magento2-mollie-theme-bundle | ^1.0.1 |
| magento/framework | * |
| magento/module-catalog | >=103.0.0 |
| magento/module-checkout | >=100.3.0 |
| magento/module-cms | >=103.0.0 |
| magento/module-customer | >=102.0.0 |
| magento/module-quote-graph-ql | * |
| magento/module-sample-data | * |
| magento/module-theme | >=101.0.0 |
| magento/module-wishlist | >=101.0.0 |

### Require (dev)

| Package | Constraint |
|---|---|
| hyva-themes/magento2-default-theme | * |
| tddwizard/magento2-fixtures | ^1.0 |

## Quality

Latest release (1.5.2) passes the Packagento QA pipeline. Verdicts below are per-cell (Magento line × PHP version) for the matrixed tools, and run-once for the static / security tiers.


### Compatibility

Each Magento line is installed on its supported PHP versions, then the module is built (DI compile + static-content deploy). Cells show passed / failed / untested; staircase gaps render as `–`.

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | Pass | Pass | – | – |
| 2.4.8 | – | Pass | Pass | – |
| 2.4.9 | – | – | Pass | Pass |


### Code Quality

Advisory checks against the module's source. Never affect the Compatibility verdict — a phpcs finding can't make a module incompatible.

#### Static Analysis

Coding standards (phpcs), mess detection (phpmd), copy-pasted code (cpd), PHP cross-version compatibility, composer.json validity. Each runs once for the whole module.

| Tool | Status | Findings | Summary |
|---|---|---|---|
| PHPCS | Warning | 187 | 187 warnings (ruleset: Magento2), 12 auto-fixable with phpcbf |
| PHPMD | Warning | 86 | 86 rule violations (UnusedFormalParameter:31, IfStatementAssignment:26, MissingImport:8, UnusedPrivateMethod:7, CyclomaticComplexity:4) |
| Cpd | Pass | 0 |  |
| Composer validate | Info | 9 | valid; 9 advisory notes (composer validate --strict) |

#### PHPStan

Type-checks the module against a real Magento install. Re-runs per Magento + PHP version because resolvable symbols differ between releases.

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | Pass | Pass | – | – |
| 2.4.8 | – | Pass | Pass | – |
| 2.4.9 | – | – | Pass | Pass |


### Tests

Unit and integration suites run per Magento + PHP cell. Test failures speak to the module's behaviour, not its compatibility with a line, so they're reported here separately.

#### Unit Tests

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | N/A | N/A | – | – |
| 2.4.8 | – | N/A | N/A | – |
| 2.4.9 | – | – | N/A | N/A |

#### Integration Tests

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | N/A | N/A | – | – |
| 2.4.8 | – | N/A | N/A | – |
| 2.4.9 | – | – | N/A | N/A |


### Security

Dependency-advisory audit (composer audit) plus a source malware scan. A malware detection fails the version outright.

| Tool | Status | Findings | Summary |
|---|---|---|---|
| Composer audit | N/A | 0 | no resolvable dependency tree to audit: Your requirements could not be resolved to an installable set of packages. Problem 1 |
| Malware scan | Pass | 0 |  |

## Licence and pricing

Free. A licence is still minted on checkout and bound to your project for Composer access — no payment step.

Refundable within 14 days of first purchase via https://packagento.com/account/refunds/.

## Install via Claude Code or any MCP client

The Packagento MCP server can run the licence + project + Composer steps above in one tool call:

```
purchase_and_install_packages(
  composer_names=["hyva-themes/magento2-theme-module"],
  project_id="proj_xxx"
)
```

This handles cart, checkout, licence minting, project activation, and writes auth.json credentials. Connect a client with `claude mcp add packagento https://mcp.packagento.com`. Full setup at https://packagento.com/docs/mcp-setup.

## Vendor

hyva-themes is a Magento 2 vendor on Packagento. See https://packagento.com/hyva-themes.md for their full catalogue.