Importing icons with Iconify Tools

Iconify Tools is a NPM package for manipulating icons. See Iconify Tools documentation.

This documentation is for version 1 of Iconify Tools. It was developed during early Iconify development, before Iconify development switched to TypeScript, so it is not fully compatible with TypeScript.

Documentation for updated Iconify Tools is available here.

There are several importers available in Iconify Tools. Some import one file, some import collections.

Importing one SVG file

tools
   .ImportSVG('path-to-file.svg')
   .then((svg) => {
       // SVG was imported
       // Variable 'svg' is an instance of SVG class
       console.log(svg.toString());
   })
   .catch((err) => {
       console.error(err);
   });

Importing directory

tools
   .ImportDir('directory')
   .then((collection) => {
       // Collection was imported
       // Variable 'collection' is an instance of Collection class
       console.log('Found icons: ' + collection.keys().join(', '));
   })
   .catch((err) => {
       console.error(err);
   });

There are several options available for importing directory, options should be passed as second parameter to ImportDir() function:

  • 'include-subdirs' check subdirectories, boolean. Default = true.
  • keywordCallback custom callback to get image name from file. It is a function with 2 arguments: function(file_without_extension, filename). Function should return string. See default function in src/import/dir.js for example.
  • ignoreDuplicates if true, when files with duplicate keywords are found script will log an error message.
  • ignoreFiles array of files to ignore. Values are keywords, not file names.
  • contentCallback callback to change content. Use it if content contains some weird stuff you need to remove before importing SVG. function(content). Function should return modified content as string.
tools
   .ImportDir('directory', {
       'include-subdirs': false,
       'ignoreFiles': ['bad-icon'],
       'keywordCallback': (file, filename) => 'prefix-' + file,
   })
   .then((collection) => {
       // Collection was imported
       // Variable 'collection' is instance of Collection class
       console.log('Found icons: ' + collection.keys().join(', '));
   })
   .catch((err) => {
       console.error(err);
   });

Importing WebIcon

WebIcon format is one big SVG image that contains multiple images.

tools
   .ImportWebIcon('path-to-file.svg')
   .then((collection) => {
       // Collection was imported
       // Variable 'collection' is an instance of Collection class
       console.log('Found icons: ' + collection.keys().join(', '));
   })
   .catch((err) => {
       console.error(err);
   });

Importing SVG font

There are many popular glyph fonts that are not available as individual files. This importer will import SVG font as collection. It will not import keywords though for each icon because that is different for every collection and should be done separately.

tools
   .ImportFont('path-to-file.svg')
   .then((collection) => {
       // Collection was imported
       // Variable 'collection' is an instance of Collection class
       console.log('Found icons: ' + collection.keys().join(', '));
   })
   .catch((err) => {
       console.error(err);
   });

There are several options available for importing SVG font, options should be passed as second parameter to ImportFont function:

  • ignoreCharacters list of characters to ignore, string[].
  • characterChanges changes for each character, object. Object key is character's hexadecimal code, value is list of changes for that character.
  • fontChanges changes for all characters.

Keys for characterChanges and fontChanges objects are similar:

  • height, width are custom height and width.
  • left, bottom are custom left and bottom indexes. Why bottom instead of top? SVG fonts flip icons vertically, so height is counted from bottom.

Each value can be a number or a function(oldValue) that should return new value.

Example:

tools.ImportFont('path-to-file.svg', {
   fontChanges: {
       height = height => Math.ceil(height / 16) * 16 // Round up height to 16px grid
   },
   characterChanges: {
       f19c: { width: 1920 },
       f0fc: { left: 64, width: 1600 },
   }
}).then(collection => {
   // Collection was imported
   // Variable 'collection' is instance of Collection class
   console.log('Found icons: ' + collection.keys().join(', '));
}).catch(err => {
   console.error(err);
});

If you are going to crop images after import, there is no point in worrying about fixing characters. Crop will fix it (unless font is really badly messed up).

Examples

Few examples that show how to import and optimize icons: