Icons

This GoHugo module 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 icon sets as an example, but is designed to support any SVG icon set you wish to integrate.

Key features

• Flexible Icon Integration: 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.

Documentation links

• SVG <symbol> Element: MDN Documentation
• SVG <use> Element: MDN Documentation

Included icon sets

• Bootstrap Icons
• Tabler Icons

Usage

Adding 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:

{{- includes.Partial "icon.html" "arrow-right" -}}
{{- includes.Partial "icon.html" (dict "icon" "arrow-right") -}}

Another option is to include the icon as a shortcode from your content files:

{{< icon "arrow-right" >}}

Development mode

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 http://localhost:1313/icons/bootstrap-icons/.

Adding custom icon sets

This module is designed to support any SVG-based icon set. To add a new set:

1. Place your SVG icons in the appropriate directory within your Hugo site.

2. Add a configuration to the config.toml file, specifying the path to your icons and the icon set name:

   • TOML
   • YAML
   • JSON
   • (click to select config format)
   • COPY

   [dnb]
     [dnb.icons]
       default = 'custom'
       [dnb.icons.custom]
         path = 'node_modules/custom-icon-set/icons/%s.svg'
         slug = 'custom'
   

   dnb:
     icons:
       custom:
         path: node_modules/custom-icon-set/icons/%s.svg
         slug: custom
       default: custom
   

   {
      "dnb": {
         "icons": {
            "custom": {
               "path": "node_modules/custom-icon-set/icons/%s.svg",
               "slug": "custom"
            },
            "default": "custom"
         }
      }
   }
   

   Make sure to replace custom with the name of your icon set and node_modules/custom-icon-set/icons/%s.svg with the path to your icons. The %s placeholder is being replaced with the icon name when the icon is called.

   The slug parameter 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 icon--custom and icon--iconname where iconname is the icon loaded.

3. Reference your custom icons using the partials methods preceding.

Migration guide

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 once and then reusing them by reference. To migrate to the latest version:

• There are no breaking changes; update your partials and shortcodes according to the usage guide.
• Replace direct calls to specific icon sets (for example bsicon, 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.