This Hugo theme component streamlines the addition of SVG-based icon sets to your Hugo website, utilizing the efficient method of defining icons once using
<symbol> and reusing them with
<use>. By default, the module includes the Bootstrap Icons set as an example, but it is designed to support any SVG icon set you wish to integrate.
- Flexible Icon Integration: Easily add any SVG-based icon set to your website.
- Efficient Caching Mechanism: Icons are defined once and reused, improving performance.
- Bootstrap Icons Included: The Bootstrap Icons set is provided by default for immediate use and as an example for integrating other icon sets.
Included icon sets
- Bootstrap Icons: Integrated by default for easy use and demonstration. Bootstrap Icons
To use an icon in your layout, call it as a partial in your templates. The example below demonstrates how to include a Bootstrap icon, but the same method applies to any SVG icon you add to the module:
Another option is to include the icon as a shortcode from your content files:
When running your Hugo site in development mode, the module provides sample pages listing all available icons from the included sets:
- Access Bootstrap Icons at
Adding custom icon sets
This module is designed to support any SVG-based icon set. To add a new set:
Place your SVG icons in the appropriate directory within your Hugo site.
Add a configuration to the
config.tomlfile, specifying the path to your icons and the icon set name:
Make sure to replace
customwith the name of your icon set and
node_modules/custom-icon-set/icons/%s.svgwith the path to your icons. The
%splaceholder is being replaced with the icon name when the icon is called.
slugparameter is used to reference the icon set in your layouts and shortcodes and add classes to format them. The classes created in the preceding sample would be
iconnameis the icon loaded.
Reference your custom icons using the partials methods preceding.
From versions 1.2024.0 and below
Older versions of this module may have added icons directly each time a shortcode or partial was called, leading to performance issues. The current version improves upon this by including icons only once and then reusing them. To migrate to the latest version:
- There are no breaking changes; however, you should update your partials and shortcodes according to the usage guide.
- Replace direct calls to specific icon sets (e.g.,
heroicon) with calls to
icon.html, passing the icon name or setting a global icon type.
- Do not cache the icon-partial calls in your layouts; the module handles this for you.