Importing SVG from directory

This function is part of import functions in Iconify Tools.

Functions importDirectory() and importDirectorySync() find and import all SVG files from a directory.

Both functions are identical, the only difference is in how they read files. Function importDirectorySync() reads files synchronously, importDirectory() reads files asynchronously.

Functions create IconSet instance, which can be exported to various formats.

Usage

Function has the following parameters:

• dir, string. Directory to import from.
• options, object. Options (optional).

Function returns IconSet instance.

Options

The options object has the following optional properties:

• prefix, string. Icon set prefix.
• includeSubDirs, boolean. Scans files in subdirectories. Enabled by default.
• keyword, function. Callback that returns keyword for icon based on file name.
• ignoreImportErrors, boolean|"warn". Does not throw an error when an icon fails to load. Enabled by default. Disable for strict error checking. If set to "warn", will log warning, but will not throw an error.
• keepTitles, boolean. If enabled, keeps titles in SVG. Disabled by default.

Keyword callback can be asynchronous in importDirectory(), but must be synchronous in importDirectorySync(). It has 3 parameters: file name, default generated keyword, icon set. It should return string with keyword or undefined if file should be skipped.

Validation

After importing icons, they need to be:

• Cleaned up and validated using cleanupSVG().
• In some cases palette needs to be fixed using parseColors().
• Optimised using runSVGO().

See example below.

Examples

Asynchronous example:

example.ts

tsimport {
   importDirectory,
   cleanupSVG,
   runSVGO,
   parseColors,
   isEmptyColor,
} from '@iconify/tools';

(async () => {
   // Import icons
   const iconSet = await importDirectory('files/svg', {
       prefix: 'test',
   });

   // Validate, clean up, fix palette and optimise
   iconSet.forEach((name, type) => {
       if (type !== 'icon') {
           return;
       }

       const svg = iconSet.toSVG(name);
       if (!svg) {
           // Invalid icon
           iconSet.remove(name);
           return;
       }

       // Clean up and optimise icons
       try {
           // Clean up icon code
           cleanupSVG(svg);

           // Assume icon is monotone: replace color with currentColor, add if missing
           // If icon is not monotone, remove this code
           parseColors(svg, {
               defaultColor: 'currentColor',
               callback: (attr, colorStr, color) => {
                   return !color || isEmptyColor(color)
                       ? colorStr
                       : 'currentColor';
               },
           });

           // Optimise
           runSVGO(svg);
       } catch (err) {
           // Invalid icon
           console.error(`Error parsing ${name}:`, err);
           iconSet.remove(name);
           return;
       }

       // Update icon
       iconSet.fromSVG(name, svg);
   });

   // Export
   console.log(iconSet.export());
})();

Synchronous example:

example.ts

tsimport {
   importDirectorySync,
   cleanupSVG,
   runSVGO,
   parseColors,
   isEmptyColor,
} from '@iconify/tools';

// Import icons
const iconSet = importDirectorySync('files/svg', {
   prefix: 'test',
});

// Validate, clean up, fix palette and optimise
iconSet.forEachSync((name, type) => {
   if (type !== 'icon') {
       return;
   }

   const svg = iconSet.toSVG(name);
   if (!svg) {
       // Invalid icon
       iconSet.remove(name);
       return;
   }

   // Clean up and optimise icons
   try {
       // Clean up icon code
       cleanupSVG(svg);

       // Assume icon is monotone: replace color with currentColor, add if missing
       // If icon is not monotone, remove this code
       parseColors(svg, {
           defaultColor: 'currentColor',
           callback: (attr, colorStr, color) => {
               return !color || isEmptyColor(color)
                   ? colorStr
                   : 'currentColor';
           },
       });

       // Optimise
       runSVGO(svg);
   } catch (err) {
       // Invalid icon
       console.error(`Error parsing ${name}:`, err);
       iconSet.remove(name);
       return;
   }

   // Update icon
   iconSet.fromSVG(name, svg);
});

// Export
console.log(iconSet.export());