Skip to main content
GOHUGO
Icons

Icons

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.

Key features

  • 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

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:

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

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

1{{< 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:

    1[dnb]
    2  [dnb.icons]
    3    default = 'custom'
    4    [dnb.icons.custom]
    5      path = 'node_modules/custom-icon-set/icons/%s.svg'
    6      slug = 'custom'
    
    1dnb:
    2  icons:
    3    custom:
    4      path: node_modules/custom-icon-set/icons/%s.svg
    5      slug: custom
    6    default: custom
    
     1{
     2   "dnb": {
     3      "icons": {
     4         "custom": {
     5            "path": "node_modules/custom-icon-set/icons/%s.svg",
     6            "slug": "custom"
     7         },
     8         "default": "custom"
     9      }
    10   }
    11}
    

    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 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., 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.
Back to top
Back Forward