Exporting 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 exporters available in Iconify Tools.

Exporting as SVG

Function ExportSVG exports one icon to file.

Parameters:

  1. SVG instance.
  2. File name.
tools
   .ExportSVG(svg, 'filename.svg')
   .then(() => {
       console.log('Exported!');
   })
   .catch((err) => {
       console.error(err);
   });

Exporting collection to directory

Function ExportDir exports collection to directory as individual SVG files.

Parameters:

  1. Collection instance.
  2. Directory name.
  3. Optional options object.
tools
   .ExportDir(collection, 'output')
   .then((count) => {
       console.log('Exported ' + count + ' files');
   })
   .catch((err) => {
       console.error(err);
   });

Available options (third parameter):

  • includePrefix, boolean. If true, exported files will include icon set prefix. The default value is true.
  • prefixAsDirectory, boolean. If true, icon name will have this format: "prefix/icon.svg". If false, icon name will have this format: "prefix-icon.svg". Only works if includePrefix is enabled. The default value is false.
  • customPrefix, string (or false if disabled). Overrides prefix. Only works if includePrefix is enabled.
  • exportFilename, function. Callback function to get filename for exported icon. See src/export/dir.js for example.

Exporting to Iconify JSON

Iconify JSON format is used to store icon sets in Iconify. It is used everywhere in Iconify: in Iconify API, in Iconify SVG framework, various components.

Why JSON format? Because it is easy to read and parse, it can contain many icons, it can contain custom metadata such as tags and categories, it is easy to store multiple variations or aliases of the same icon.

Function ExportJSON exports collection to JSON file. This is the main export function in Iconify Tools, entire package was designed to import various formats and export them as JSON icon sets.

Parameters:

  1. Collection instance.
  2. Target filename.
  3. Optional options object.
tools
   .ExportJSON(collection, 'filename.json')
   .then((json) => {
       console.log('Exported collection. JSON data: ' + JSON.stringify(json));
   })
   .catch((err) => {
       console.error(err);
   });

Some of available options (third parameter):

  • optimize, boolean. If enabled, JSON data will be optimized to reduce file size. The default value is false.
  • minify, boolean. If disabled, output will be pretty, making it easy to read. The default value is false.

There are other options, but they are very specific to importers. See source code for details.

Exporting as components

Function ExportComponent creates single files for all icons, which can be used with various Iconify icon components, such as Iconify for React, Iconify for Vue and Iconify for Svelte.

This function is currently unstable, it will be rewritten, so documentation is not available yet.

Exporting to PNG

Function ExportPNG export collection to PNG files.

Important: this function requires PhantomJS to be installed and accessible from command line! PhantomJS has been deprecated for a while, but you can still install it using HomeBrew. It is also not optimal because it sometimes creates rough edges.

  1. SVG or Collection instance.
  2. Target filename (for SVG instance) or directory (for Collection instance).
  3. Optional options object.
tools
   .ExportPNG(svg, 'filename.png', {
       // options object here
   })
   .then(() => {
       console.log('Exported filename.png');
   })
   .catch((err) => {
       console.error(err);
   });

Options object (third parameter) has following properties:

  • width, height: dimensions of PNG image. Default = same as SVG dimensions.
  • color: color for monotone images that use "currentColor" (see ChangePalette function). Default = "#000".
  • background: background color, default = "transparent".

When exporting big collections, this function will take a while to export everything.

ImportJSON and ExportDir example

This example imports Iconify JSON file and exports icons as individual files:

export.js
'use strict';

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

// Source file
const sourceFile = __dirname + '/mdi.json';

// Target directory
const targetDir = __dirname + '/output';

// Create directory for export
try {
   fs.mkdirSync(targetDir);
} catch (err) {
   // Do nothing. Assume directory has been created
}

// Import source file
tools
   .ImportJSON(sourceFile)
   .then((collection) => {
       // Export collection to target directory
       return tools.ExportDir(collection, targetDir, {
           includePrefix: false, // Set to true to include 'mdi-' prefix in icon names
           includeAliases: true,
       });
   })
   .then((result) => {
       console.log('Exported ' + result + ' icons.');
   })
   .catch((err) => {
       console.error(err);
   });

This code will convert mdi.json to individual SVG files that will be saved in directory output.

In addition to Iconify Tools, JSON icon set can be exported to SVG using Iconify JSON Tools.