Hyvä-Based Magento 2 Themes by MageSpark

Prerequisites & System Requirements

Before beginning the installation, ensure your environment meets the following requirements:

Hyvä Theme Setup (If Not Already Installed)

MageSpark Themes require Hyvä as their base. Install and validate Hyvä before proceeding. Official requirements are documented at Hyvä docs.

Register at hyva.io, generate your package key, and configure Composer authentication.

composer config --auth http-basic.hyva-themes.repo.packagist.com token yourLicenseAuthenticationKey
composer config repositories.private-packagist composer https://hyva-themes.repo.packagist.com/yourProjectName/

Install Hyvä and required dependencies:

composer require hyva-themes/magento2-default-theme
composer require hyva-themes/magento2-cms-tailwind-jit
composer require hyva-themes/magento2-heroicons2

# Confirm analysis-phonetic plugin is active before running setup:
# curl -X GET "http://<your-search-host>:<your-search-port>/_cat/plugins?v"

php bin/magento setup:upgrade
php bin/magento config:set customer/captcha/enable 0
php bin/magento config:set dev/template/minify_html 0
php bin/magento config:set dev/js/merge_files 0
php bin/magento config:set dev/js/enable_js_bundling 0
php bin/magento config:set dev/js/minify_files 0
php bin/magento config:set dev/js/move_script_to_bottom 0
php bin/magento config:set dev/css/merge_css_files 0
php bin/magento config:set dev/css/minify_files 0
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f
php bin/magento cache:flush

Verify Hyvä is active at Content > Design > Configuration and set theme to hyva/default before installing MageSpark themes.

Upload MageSpark Themes (ZIP Distribution)

1. Download and extract the ZIP package locally.
2. Copy extracted app/code/MageSpark/* modules into Magento root app/code/MageSpark/.
3. Copy the extracted theme folder:
   • From ZIP: app/design/frontend/MageSpark/<ThemeName>/
   • To Magento: app/design/frontend/MageSpark/<ThemeName>/
4. If included, copy media assets:
   • From ZIP: pub/media/wysiwyg/ms-fashion/
   • To Magento: pub/media/wysiwyg/ms-fashion/
5. Run Magento setup commands:

php bin/magento setup:upgrade
php bin/magento setup:static-content:deploy -f
php bin/magento cache:flush
php bin/magento indexer:reindex

Assign MageSpark Themes

Go to Content > Design > Configuration and assign MageSpark/<ThemeName> to the target website or store view.

Tailwind CSS Compilation

Run the following from app/design/frontend/MageSpark/<ThemeName>/web/tailwind:

1. Install packages: npm ci
2. Generate Hyvä sources and tokens: npm run generate
3. Generate CSS from design tokens (required after saving Theme Configuration settings): npx hyva-tokens
4. Build CSS: npm run build
5. For local development watch mode: npm run watch

Demo Content Import

Import CMS pages and static blocks provided by supported data extensions (for example, MageSpark_Fashion).

Prerequisites

1. Enable required modules: MageSpark_SampleDataImport and a data provider module such as MageSpark_Fashion.
2. Ensure admin user access to Stores > Configuration > MageSpark Theme > Sample Data Import.

Import CMS Pages

1. Go to Stores > Configuration > MageSpark Theme > Sample Data Import.
2. Choose Import CMS Pages from Select Data.
3. Click Import and wait for success confirmation.
4. Re-save each imported page from Content > Pages so hyvä detects Tailwind CSS classes used in imported CMS content.
5. Verify pages in Content > Pages.

Import CMS Static Blocks

1. Go to Stores > Configuration > MageSpark Theme > Sample Data Import.
2. Choose Import CMS Blocks from Select Data.
3. Click Import and wait for success confirmation.
4. Re-save each imported block from Content > Blocks so hyvä detects Tailwind CSS classes used in imported CMS content.
5. Verify blocks in Content > Blocks.

Troubleshooting

1. If the Import button does nothing, verify ACL permissions and check browser console/network responses.
2. If no providers are configured, confirm the fixture provider extension is installed and enabled (for example, MageSpark_Fashion).

Theme Configurations

Theme Utilities

• Adds configurable design tokens (colors, spacing, typography, header, footer, product card).
• On save, observer MageSpark\ThemeConfiguration\Observer\UpdateHyvaConfigOnSave updates app/design/frontend/<active_theme>/web/tailwind/hyva.config.json.
• Shows a success prompt to rebuild and redeploy frontend assets after updates.
• Includes admin color picker renderer (Block/Colorpicker.php).

Configuration Groups

1. Color: controls primary and secondary palettes, button text colors, and global text and heading colors.
2. Form: controls border radius, border color, and active field color.
3. Font: controls base typography, heading sizes across devices, font styles, weights, and letter spacing.
4. Header: controls menu colors, category level text colors, counters, and announcement bar tokens.
5. Footer: controls background, text, and link hover colors.
6. Product Card: controls border radius, title clamp, and rating summary color.

Mega Menu

Mega Menu can be enabled per category.

1. Go to Catalog > Categories.
2. Open a category shown in main navigation.
3. Set Show Mega Menu to Yes in General Information.
4. Click Save and run bin/magento cache:flush.
5. Verify output in storefront navigation.

Mega Menu Left/Right Images

1. Identify category ID from admin category URL or entity details.
2. Use block identifier patterns:
   • ms-megamenu-left-cat-<categoryId>
   • ms-megamenu-right-cat-<categoryId>
3. Create or edit the CMS block in Content > Blocks.
4. Add banner image in block content using Page Builder or HTML.
5. Flush cache and verify in desktop top navigation.

Header

Navigation: Stores > Configuration > MageSpark Theme > Sticky Header > General

Field Guide

1. Enable Sticky Header: enables sticky mode globally for selected website scope.
2. Show Top Promotion Bar: controls top bar visibility.
3. Top Promotion Bar Content: defines the announcement strip text.

Product Slider Widget (CMS)

Product Slider lets you show a product carousel inside CMS pages or CMS blocks. This is useful for sections like What's Hot, Best Sellers, or Featured Products.

Where to Add It

1. Go to Content > Pages or Content > Blocks.
2. Open the page/block where you want the slider.
3. Use Insert Widget and select Product Slider.
4. Fill in the settings and click Save.
5. Flush cache with bin/magento cache:flush and check storefront output.

Important Settings (Simple Guide)

• Title: Heading shown above the slider.
• Show Heading: Show or hide the title line.
• Heading Tag: Choose H1-H6. Recommended: H2 or H3 for normal content sections.
• Number of slides to show: Number of product cards visible at once (default: 4).
• Show Pager: Shows pagination dots below slider.
• Page Size: Total products to load into slider (default: 8).
• Category IDs: Comma-separated category IDs (example: 5,6,7).
• Include Child Category Products: Includes products from child categories when using one parent category.
• Product SKUs: Comma-separated SKU list for exact product selection.
• Price From / Price To: Filters products by price range.
• Sort Attribute: Sort by attribute such as price, name, or created_at.
• Sort Direction: Ascending (ASC) or descending (DESC).

Slider Type

Use Generic for normal CMS content sliders. Other options are Related, Upsell, and Crosssell.

Recommended Starter Setup

1. Title: What's Hot
2. Show Heading: Yes
3. Heading Tag: H3
4. Slider Type: Generic
5. Number of slides to show: 4
6. Page Size: 8
7. Set either Category IDs or Product SKUs for predictable results
8. Sort Direction: ASC

Troubleshooting

1. If no products appear, recheck category IDs/SKUs and store view scope.
2. If slider does not update, flush Magento cache and refresh storefront.
3. If output layout looks crowded, reduce visible slides or add spacing CSS classes.

Magento Catalog Products List Widget Extension

The theme also extends Magento's default Catalog Products List widget to support Hyvä slider layouts.

1. Go to Content > Pages or Content > Blocks.
2. Insert the Catalog Products List widget.
3. In Template, choose:
   • Products Grid Template for the default grid.
   • Products Slider Template for the Hyvä slider layout.
4. Configure the widget conditions and save, then flush cache.

Sub Category Block

This feature shows child categories in a grid on category pages. It is controlled strictly at the category level.

Where to Enable It for a Specific Category

Go to: Catalog > Categories > Select Category > General Information > Enable Sub Category Block

When the Grid Appears

• The category option "Enable Sub Category Block" is set to Yes
• The category has child categories

Quick Setup Steps

1. Open your category and set "Enable Sub Category Block" to Yes.
2. Save changes.
3. Run cache flush (bin/magento cache:flush).
4. Open the category page on storefront and check the sub-category block.

Ajax Add to Cart

Ajax Add to Cart lets shoppers add products without a full page reload and displays success feedback in a modal or mini cart.

1. Go to Stores > Configuration > MageSpark Theme > Ajax Add To Cart.
2. Set Enable Ajax Add To Cart to Yes.
3. Set Delay (in milliseconds) (recommended start: 500).
4. Set Show SKU in popup as needed.
5. Choose Display on Success:
   • Modal for explicit confirmation popup.
   • Mini Cart for cart-focused flow.
6. Click Save Config, flush cache, and test on category/product pages.

Cart Drawer

Enhances storefront cart interactions by adding a native Hyvä cart drawer layout. It includes templates for drawer content, quantity controls, and cross-sell items, providing a seamless checkout flow without full page reloads.

ElasticSuite Integration

MageSpark themes extend Smile ElasticSuite and the Hyvä ElasticSuite bridge for advanced catalog search, layered navigation, and tooltip behavior.

• Adds Hyvä-compatible layered navigation and product list overrides.
• Adds configuration for advanced catalog behavior, infinite scroll buttons, and slider direct modes.
• Reindex catalog search data whenever ElasticSuite behavior or indexed attributes change.

Child Theme Customization

Always implement storefront customizations in a child theme to maintain upgrade compatibility with future releases of MageSpark themes.

FAQ

Do I need Hyvä before installing MageSpark themes?

Yes. MageSpark themes depend on Hyvä and should be installed only after Hyvä is configured and active.

When should I run Tailwind build commands?

Run them after theme setup and whenever design tokens or Tailwind sources are changed.

Why are imported demo pages or blocks not visible?

Check module status, admin ACL permissions, store scope, and flush Magento caches.

Why do imported demo pages or blocks look unstyled after import?

Imported CMS content may include Tailwind CSS classes. Re-save the imported pages and static blocks once from Magento admin so hyvä can detect those classes and apply the required styles.