Iconify Tools

Iconify Tools is a NPM package for manipulating icons.

This library is a collection of tools for importing, exporting and processing SVG images.

Its main purpose is to convert icon sets and fonts to Iconify JSON collections, but it can be used for other purposes.

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. Iconify Tools are currently being rewritten using TypeScript with ES modules support.

Installation and import

To install Iconify Tools run this:

npm install @iconify/tools --save

Then you can use it in your Node.js files:

const tools = require('@iconify/tools');

What tools are available?

  • Import SVG from various sources.
  • Export SVG to various formats.
  • Optimize SVG.
  • Crop SVG.
  • Clean up SVG.
  • Get/change color palette.
  • Find shapes, get lengths of shapes.
  • Convert shapes to paths.

Core

Core of tools are SVG and Collections classes. All tools create or manipulate instances of SVG or Collection classes.

All tools are based on Promise instances. If you are not familiar with JavaScript Promises, do read up. There are many tutorials available online. Make sure you are reading something from 2016 or newer, not tutorials for old implementations.

SVG class

SVG class represents one SVG image. It is a simple class, it does not manipulate anything, except for cleaning up junk code that could otherwise cause XML parser to fail.

You can find code in src/svg.js

Creating SVG instance is easy:

let svg = new tools.SVG('<svg ...></svg>');

That code will load SVG from string, extract image dimensions and clean up a bit, removing all junk image editors left behind.

SVG instance has multiple methods to get SVG as string:

  • toString() returns SVG as string.
  • toMinifiedString() the same as toString(), but without white spaces.
  • getBody() returns body as string: child elements of <svg> element.

Then you can get dimensions:

  • getDimensions() returns object containing width and height properties.
  • width contains width, read-only property.
  • height contains height, read-only property.

Last method replaces content of SVG instance:

  • load(content) the same as constructor, but instead of making new instance it changes existing instance.

You can see usage examples in unit tests: tests/core/svg_test.js

Collection class

Collection is a set of SVG instances.

You can find code in src/collection.js

To create Collection instance use this:

let collection = new tools.Collection();

That will create empty collection.

To clone another collection add collection as parameter to constructor:

let newCollection = new tools.Collection(oldCollection);

To add/remove items there are several methods:

  • add('icon-name', svg) add new item to the collection.
  • remove('icon-name') remove item from the collection.
  • rename('old-name', 'new-name') rename item.

To access any item use this: collection.items['item-name']

There are other helpful functions:

  • length() returns number of items in the collection.
  • keys() returns list of all icon names.

Then there are main functions that are used to manipulate SVG instances in the collection:

  • forEach(callback) iterates through all SVG instances in the collection. Callback function arguments: (svg, name), where svg is SVG instance, name is the icon name.
  • promiseAll(promise) runs Promise on all items in the collection. See example below.
  • promiseEach(promise, stopOnError) runs Promise on all items in the collection, but only one at a time.

How to use forEach():

collection.forEach((svg, name) {
   console.log('Found icon ' + name + ': ' + svg.toString());
});

How to use promiseAll() and promiseEach():

collection.promiseAll((svg, name) => {
   return new Promise((fulfill, reject) {
       // do stuff to "svg" variable
       fulfill('Result for icon ' + name);
   });
}).then(results => {
   // Results of all promises as object. Key = icon name, value = result for that icon

   Object.keys(results).forEach(name => {
       console.log('Result for icon ' + name + ':', results[name]);
   });
}).catch(err => {
   console.error('Promise failed:', err);
});

promiseAll() and promiseEach() are almost identical. First argument is callback that returns Promise for one icon.

The only difference between function is: promiseAll() runs all promises at the same time using Promise.all() function, promiseEach() runs promises one after another. It is better to use promiseEach() when dealing with large collections.

You can find examples throughout this library and unit tests. Everything in this library is based on promises.

Importing

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

See import functions.

Manipulating

Most functions require SVG to be optimized. Therefore, before doing anything else, you should optimize icon.

See icon manipulation functions.

Exporting

There are several exporters available that work with Collection or SVG instances.

See export functions.

Examples

Few examples that show how to import, optimize and export icons: