Building a Hyvä Child Theme
A Hyvä child theme inherits all templates, layouts, and styles from the parent Hyvä Default Theme while allowing you to customize specific components for your store. Child themes are the recommended approach for Hyvä customization because they preserve upgrade compatibility and separate your customizations from vendor code.
This guide covers creating a child theme in app/design/frontend/, configuring Tailwind CSS to include parent theme sources, and generating the production stylesheet.
Creating a Child Theme
Follow the official Magento theme creation guide to create a new theme directory structure in app/design/frontend/Vendor/ThemeName/.
In your theme's theme.xml, set the parent to Hyva/default for the standard Hyvä theme or Hyva/default-csp for the Content Security Policy compliant version.
Theme Preview Image
The Hyvä Default Theme includes preview.png rather than preview.jpg. Reference this filename in your child theme's theme.xml.
Setting Up the Tailwind Build Directory
Child themes require a complete copy of the Tailwind build configuration from the parent theme. This includes the package.json, Tailwind configuration files, and source CSS files needed to generate your theme's stylesheet.
Step 1: Copy the Web Directory
Copy the entire web directory from the parent Hyvä Default Theme to your child theme:
Step 2: Configure the Parent Theme Path
Tailwind must scan the parent theme's templates to include their CSS classes in the production build. Configure the parent theme path in your child theme's web/tailwind/hyva.config.json file.
Add the tailwind.include array with a src entry pointing to the parent theme in the vendor directory:
Hyvä 1.3.x and Tailwind v3
Tailwind 3 used a tailwind.config.js file instead of the current hyva.config.json and tailwind-source.css.
Tailwind v3 was used in Hyvä themes release 1.2.x and 1.3.x.
The path to the parent theme needed to be enabled in the config:
```js
module.exports = {
...
// Examples for excluding patterns from purge
content: [
// this theme's phtml and layout XML files
'../../**/*.phtml',
'../../*/layout/*.xml',
'../../*/page_layout/override/base/*.xml',
// parent theme in Vendor (if this is a child-theme)
//'../../../../../../../vendor/hyva-themes/magento2-default-theme/**/*.phtml',
//'../../../../../../../vendor/hyva-themes/magento2-default-theme/*/layout/*.xml',
//'../../../../../../../vendor/hyva-themes/magento2-default-theme/*/page_layout/override/base/*.xml',
// app/code phtml files (if need tailwind classes from app/code modules)
//'../../../../../../../app/code/**/*.phtml',
]
}
...
```
If your theme is based on hyva-themes/magento2-default-theme-csp, adjust the path to include the -csp suffix:
Hyvä 1.1.x and Tailwind v2
Older Hyvä versions 1.1.x use Tailwind v2. In the configuration for that version, the path to the content section is slightly different.
If your theme is based on an older 1.1.x version of Hyvä and you haven't upgraded it to Tailwind v3, you need to use that structure,
where content is nested inside a purge parent object:
module.exports = {
...
// keep the original settings from tailwind.config.js
// only add the path below to the purge > content settings
...
purge: {
content: [
// this theme's phtml and layout XML files
'../../**/*.phtml',
'../../*/layout/*.xml',
// parent theme in Vendor
'../../../../../../../vendor/hyva-themes/magento2-default-theme/**/*.phtml',
...
]
}
}
...
Customizing Your Theme
Hyvä child themes use the same extension mechanisms as standard Magento themes. Override .phtml template files by placing them in the same relative path within your child theme. Extend layout XML files using Magento's standard layout XML merging behavior.
All Tailwind CSS utility classes used in your custom templates will be automatically included in the stylesheet when you regenerate the CSS.
Generating the Production Stylesheet
After making changes to your child theme, regenerate the styles.css file to include any new Tailwind classes. Run the Tailwind build command from your theme's web/tailwind directory:
For detailed information on Tailwind CSS configuration and stylesheet generation, see: