Table of Contents & Menu
On this page
Navigation

Creating a custom SVG Icon View Model

Easily integrate custom SVG icon sets into your Hyvä themes by creating a custom SVG icon view model.

Build these view models within a custom module for easy installation across any Hyvä-themed Magento instance.

Check for existing icon packs

Before starting, check for existing third-party icon packs. They can also serve as excellent examples for your own custom view models.

The SVG icon files

Place your SVG icon files in your module's view/frontend/web/svg directory.
Filenames must be lowercase, using only a-z, numbers, and hyphens, ending with .svg.

Examples for valid icon files

  • view/frontend/web/svg/my-special-icon.svg
  • view/frontend/web/svg/arrow-2.svg

For different icon sets (e.g., light/dark, *solid/outline*), use appropriately named subdirectories:

view/frontend/web/svg/outline/
view/frontend/web/svg/solid/

Create the PHP View Model Class

Create a PHP view model in your module, extending \Hyva\Theme\ViewModel\SvgIcons.

<?php

declare(strict_types=1);

namespace My\Module\ViewModel;

use Hyva\Theme\ViewModel\SvgIcons;

class ExampleIcons extends SvgIcons
{

}

Warning

The SvgIcons class is for external modules (outside magento2-hyva-theme) since Hyvä 1.1.12. Ensure your composer.json includes 'hyva-themes/magento2-theme-module': '>=1.1.12' as a dependency.

Configure the iconPathPrefix

Configure iconPathPrefix in etc/di.xml:

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <type name="My\Module\ViewModel\ExampleIcons">
        <arguments>
            <argument name="iconPathPrefix" xsi:type="string">My_Module::svg/solid</argument>
        </arguments>
    </type>
</config>
Use the primary scope etc/di.xml to set the iconPathPrefix, not the frontend scope.

Setting iconPathPrefix in etc/frontend/di.xml will break PageBuilder CMS content previews with SVG icons.

The iconPathPrefix is prepended to icon names rendered by this class.

$myIcons = $viewModels->require(\My\Module\ViewModel\ExampleIcons::class);
echo $myIcons->renderHtml('bubble-bath');
// -> My_Module::svg/solid/bubble-bath.svg

Providing IDE auto-completion

For IDE auto-completion (e.g., PHPStorm), add @method phpdoc annotations for each icon in your set.

/**
 * @method string bubbleBathHtml(string $classnames = '', ?int $width = 24, ?int $height = 24, array $attributes = [])
 * @method string hotShowerHtml(string $classnames = '', ?int $width = 24, ?int $height = 24, array $attributes = [])
 * @method string oldSinkHtml(string $classnames = '', ?int $width = 24, ?int $height = 24, array $attributes = [])
 * @method string newSinkHtml(string $classnames = '', ?int $width = 24, ?int $height = 24, array $attributes = [])
 */
class ExampleIcons extends SvgIcons
{

}
Generating the method signatures

Heroicon view model annotations in Hyva_Theme are generated via a bash script (Gitlab Access Required). Adjust the script's path to your SVG icon directory.

Making your icons available in CMS content

Embed SVG icons in CMS content using the {{icon "..."}} syntax.

Make custom icon sets available by adding a pathPrefixMapping for your module in etc/frontend/di.xml.

<type name="Hyva\Theme\ViewModel\SvgIcons">
    <arguments>
        <argument name="pathPrefixMapping" xsi:type="array">
            <item name="example" xsi:type="string">My_Module::svg</item>
        </arguments>
    </type>
</config>

With this configured, your module's icons can be used in CMS content:

{{icon "example/hot-shower" classes="w-6 h-6" width=12 height=12}}

The icon path's first part maps to the pathPrefix, resulting in an SVG asset path like My_Module::svg/hot-shower.svg.

Info

The \Hyva\Theme\ViewModel\SvgIcons class phpdoc block offers extensive details on implementation and customization, though most are rarely needed.