How to add and manage icons in web projects using svg symbols

In this article, we'll go through the main steps of using SVG symbols, from creating to importing them into a web project, providing a comprehensive guide that will help you use them with ease.

Additionally, we will analyze the advantages and disadvantages of this technique.

Before diving into SVG symbols, here're some different icon integration methods you could use:

• Add and manage icons in web projects using icon font
• Add and manage icons in web projects using SVG sprites

How SVG symbols work #

SVG symbols are based on the use of two elements: <symbol> and <use>.

The <symbol> element stores an SVG icon as a graphical template object; when inserted inside an HTML file, its content (the icon) is not displayed.

<!-- this element won't be visible inside an HTML file -->
<symbol id="icon-expand" viewBox="0 0 16 16">
  <path d="M2.854,8.146a.5.5,0,0,0-.847.272l-1,6A.5.5,0,0,0,1.5,15a.454.454,0,0,0,.082-.007l6-1a.5.5,0,0,0,.272-.847Z"></path>

  <path d="M14.854,1.146a.51.51,0,0,0-.436-.139l-6,1a.5.5,0,0,0-.272.847l5,5A.5.5,0,0,0,13.5,8a.5.5,0,0,0,.493-.418l1-6A.5.5,0,0,0,14.854,1.146Z"></path>
</symbol>

The SVG icon stored inside the <symbol> can then be rendered using the <use> element.

<svg><use href="#icon-expand"/></svg>

How to create SVG symbols #

Manually managing SVG symbols can be cumbersome. You need to create a <symbol> element for each of your icons and make sure the code inside each <symbol> is in sync with the latest version of the icon.

Alternatively, you can use tools like Nucleo to automatically generate the symbol file for you: import your SVG icons by dragging them over the app, select them and press the 'Export' button.

In the export window, select the 'SVG <symbol>' option under the 'SVG' tab, and press 'Export Icons'. The app will generate a .svg file (e.g., icons.svg) containing the <symbol>s list.

Make sure to check the 'Use external reference for <use> element' option, and update the 'Assets path' field with your project assets folder (e.g., 'assets/img').

How to use SVG symbols in an HTML file #

Save the icons.svg file created by the symbol generator into your project assets folder (e.g., 'assets/img/icons.svg').

In HTML, display an icon using the <use> element.

<svg><use href="assets/img/icons.svg#icon-cake"/></svg>

The href attribute is equal to the symbol file path (in our example, 'assets/img/icons.svg') plus the id of the icon you want to display.

Since finding the id of the icons inside the symbol file is impractical, the symbol generators generally give you an HTML demo file where you can view the icons and copy their ids.

Nucleo offers an elegant alternative to the demo file: the Nucleo projects.

If you add the icons to a project (select the icons > right-click > add to project) and then export it as SVG symbols, you can copy the <use> for each icon directly within the app.

CSS Customizations #

One of the downsides of using svg symbols is that the icon elements are not directly accessible using CSS selectors.

For this reason, if you want to modify the color of a symbol, you need to remove the inline fill/stroke color values and replace it with the currentColor value.

<symbol id="icon-horseshoe" viewBox="0 0 16 16">
  <path fill="currentColor" d="M8,16A7.008,7.008,0,0,1,1,9,23.3,23.3,0,0,1,2.026,2.732q.069-.261.139-.532L1.553,1.9A1,1,0,0,1,2.447.105L3.78.772A1,1,0,0,1,4.3,1.909,21.34,21.34,0,0,0,3.25,8,4.8,4.8,0,0,0,8,13a4.8,4.8,0,0,0,4.75-5A21.34,21.34,0,0,0,11.7,1.909,1,1,0,0,1,12.22.772L13.553.105a1,1,0,1,1,.894,1.79l-.612.305q.07.271.139.532A23.3,23.3,0,0,1,15,9,7.008,7.008,0,0,1,8,16Z"></path>
</symbol>

Once this is done, use the color property to change the icon color.

svg {
  color: navy;
}

Nucleo automatically removes colors to ease icon customizations.

For icons with strokes, check the 'Remove stroke-width values' option during the export if you need to control the stroke width. Then customize it in CSS.

svg {
  stroke-width: 1px;
}

If you wish to deeper customize your icons (e.g., use different colors for different elements), you can use CSS custom properties.

<!-- fill values are set equal to var(--fill-color-1) and var(--fill-color-2)  -->
<symbol id="icon-pineapple" viewBox="0 0 16 16">
  <path fill="var(--fill-color-1)" d="M8.993,3.916C8.922,3.179,8,0,8,0s-.922,3.179-.993,3.916C6,3.272,4,2.172,4,2.172S5.731,5.317,6.121,5.707A1.043,1.043,0,0,0,7,6H9a1.043,1.043,0,0,0,.879-.293C10.269,5.317,12,2.172,12,2.172S10,3.272,8.993,3.916Z"></path> 
  <rect fill="var(--fill-color-2)" x="4" y="7" width="8" height="9" rx="2" ry="2"></rect>
</symbol>

In CSS you can assign two different fill values.

svg {
  --fill-color-1: navy;
  --fill-color-2: blue;
}

This applies to the other SVG attributes as well (e.g., stroke-width).

To change the icon size, you can either create some utility classes or specify height/width in CSS.

/* utility classes */ 
.icon-sm {
  width: 16px;
  height: 16px;
} 

.icon-md {
  width: 24px;
  height: 24px;
}

.icon-lg {
  width: 32px;
  height: 32px;
} 

/* setting the icon size on an element */ 
.component-icon {
  width: 20px;
  height: 20px;
}

Adding/removing icons #

When using symbol generators like Nucleo, updating your symbol file to include new icons or remove old ones becomes pretty straightforward.

If you have created a project in Nucleo, you can add new icons by adding them to a project (right-click to open the icon context menu > select 'Add to Project'). You can delete icons by removing them from a project. You can also replace an icon if you want to preserve the id value (right-click > select 'Replace Icon').

Once you have updated a project, you will need to re-export it as SVG symbol, and replace the old icons.svg file with the new file the app created.

Accessibility #

For meaningful icons (e.g., icons that need alternative text), make sure to add the <title> element, as you would do with inline SVG icons.

<svg>
  <title>Search items</title>
  <use href="assets/img/icons.svg#icon-search"/>
</svg>

For decorative icons (e.g., an icon next to an explicit label), hide them from screen readers using the aria-hidden attribute.

<p>
  <svg aria-hidden="true"><use href="assets/img/icons.svg#icon-search"/></svg>
  Search items
</p>

For additional tips on icon accessibility, check our guide to creating accessible icons.

Pros and cons of using SVG symbols #

Pros:

• Easy to use
• Use the same icon multiple times without repeating the SVG code
• Icons can be customized (if <symbol> content is properly optimized)
• The icons are scalable vectors

Cons:

• Fewer customization options compared to inline SVGs (but better than icon font)
• Unlike inline SVG, you can't animate individual icon elements
• To add/remove icons, you need to generate a new .svg symbol file

The end! Check our documentation tutorials page for more articles on working with icons.