Table of Contents & Menu
On this page
Navigation

Hyvä SVG Icons

Hyvä Themes include a customized version of Lucide Icons by default, featuring a slightly finer stroke width of 1.5 (instead of the standard 2).

For legacy themes, HeroIcons v1 is also included, but it's being phased out and will not be updated to HeroIcons v2.

All icons are managed via the SvgIcons module, which also supports adding custom SVG icons.

Using Icons

Icons can be rendered in two main ways: directly in .phtml templates or within CMS content.

In PHTML Templates

To use icons in your template files, first instantiate the LucideIcons ViewModel:

<?php

use Hyva\Theme\Model\ViewModelRegistry;
use Hyva\Theme\ViewModel\LucideIcons;

/** @var ViewModelRegistry $viewModels */

/** @var LucideIcons $lucideIcons */
$lucideIcons = $viewModels->require(LucideIcons::class);

Render an icon using its camel-cased name, suffixed with Html. For example, to render the scale icon:

<?= $lucideIcons->scaleHtml('text-gray-500', 24, 24, ['aria-hidden' => 'true']) ?>

All icon methods share the signature: (string $classnames = '', ?int $width = 24, ?int $height = 24, array $attributes = []). This allows you to customize CSS classes, dimensions, and other HTML attributes. For accessibility, use aria-hidden="true" for decorative icons.

In CMS Content

Use the icon directive to render SVG icons in CMS blocks, pages, and other filtered content:

{{icon "heroicons/solid/shopping-cart" classes="text-primary" width=24 height=24}}

For custom icons in your theme's web/svg/ directory (e.g., web/svg/my-icon.svg), use their filename:

{{icon "my-icon"}}

This directive is processed by Hyva\Theme\Model\Template\IconProcessor.

Tip

To allow users to paste raw SVG code into the WYSIWYG editor, install the Hyvä WysiwygSvg module. This serves a different purpose than the SvgIcon view model.

Extending Your Icon Library

Easily add custom or pre-built icons to your project.

Adding Your Own Icons

Expand and customize Hyvä's icon system by adding your own SVG icons or overriding defaults for a unique storefront:

  • Add new, theme-specific icons: Place .svg files in your theme's web/svg directory.
  • Override default icons: Place an SVG file with the same name in your theme's web/svg/lucideicons/ directory.

For a complete guide, see using custom SVG icons in your theme.

Additional Hyvä Icon Packs

Official modules are available for other popular icon sets:

Third-Party Icon Packs

The Hyvä community has shared various icon packs:

Created your own icon pack? Share it with the community!

Discover more community-built icon packs on GitHub under the #hyva-icons topic.