Skip to content


This function is part of Iconify Tools package.

Function mergeIconSets() merges to icon sets, creating new IconSet instance.

Why merge icon sets?

When you update an icon set, often old icons are lost. If someone is using an old icon, which no longer exists or was renamed, removing that icon will result in a broken UI. This is why icons should never be removed.

Merging new icon set and old icon set ensures that icons are never removed. Merge process adds missing icons, but marks them as hidden, so they are not shown in icons list, but are available to anyone using old icons.

This function attempts to detect renamed icons, creating aliases for those icons.


Function has the following parameters:

  • oldIcons, IconSet. Old version of icon set.
  • newIcons, IconSet. New version of icon set.

Function does not modify icon sets passed in parameters, it creates new IconSet instance and returns it.


tsimport { IconSet, mergeIconSets } from '@iconify/tools';

// Merge 2 icon sets
const merged = mergeIconSets(
   new IconSet({
       // Prefix, info, categories, characters are not copied from old icon set
       prefix: 'foo',
       icons: {
           'chrome-maximize': {
               body: '<g fill="currentColor"><path d="M3 3v10h10V3H3zm9 9H4V4h8v8z"/></g>',
           'chrome-minimize': {
               body: '<g fill="currentColor"><path d="M14 8v1H3V8h11z"/></g>',
       width: 24,
       height: 24,
   new IconSet({
       prefix: 'bar',
       icons: {
           remove: {
               body: '<g fill="currentColor"><path d="M15 8H1V7h14v1z"/></g>',

// Log merged icon set
   "prefix": "bar",
   "icons": {
       "remove": {
           "body": "<g fill=\"currentColor\"><path d=\"M15 8H1V7h14v1z\"/></g>",
           "width": 16,
           "height": 16
       "chrome-maximize": {
           "body": "<g fill=\"currentColor\"><path d=\"M3 3v10h10V3H3zm9 9H4V4h8v8z\"/></g>",
           "hidden": true
       "chrome-minimize": {
           "body": "<g fill=\"currentColor\"><path d=\"M14 8v1H3V8h11z\"/></g>",
           "hidden": true
   "width": 24,
   "height": 24

Released under the Apache 2.0 License.