Fantasticon

By default, icon names and CSS class names are generated from a slug of the relative path + basename of each .svg file found in the input directory. This allows you to organize icons into namespaces using folders.

Example Structure:

icons
├── logo.svg
└── social
    └── facebook.svg

Resulting Mapping:

• Icon ID: logo $\rightarrow$ CSS Selector: .icon-logo (assuming prefix icon and tag i)
• Icon ID: social-facebook $\rightarrow$ CSS Selector: .icon-social-facebook

You can override this behavior by providing a getIconId function in your configuration file. The function receives an object containing:

• basename: The filename without extension (e.g., 'foo').
• relativeDirPath: The path relative to the input directory (e.g., 'sub/dir').
• absoluteFilePath: The full absolute path.
• relativeFilePath: The path relative to the input directory including filename (e.g., 'sub/dir/foo.svg').
• index: The zero-based index of the icon.

For advanced control (e.g., formatOptions, pathOptions, getIconId, templates), use a configuration file. Fantasticon searches for the following files in the working directory:

.fantasticonrc, fantasticonrc, .fantasticonrc.json, fantasticonrc.json, .fantasticonrc.js, fantasticonrc.js.

You can specify a custom path using the --config CLI flag.

module.exports = {
  inputDir: './icons', // (required)
  outputDir: './dist', // (required)
  fontTypes: ['ttf', 'woff', 'woff2'],
  assetTypes: ['ts', 'css', 'json', 'html'],
  fontsUrl: '/static/fonts',
  formatOptions: {
    woff: {
      metadata: '...'
    },
    json: {
      indent: 2
    },
    ts: {
      types: ['constant', 'literalId'],
      singleQuotes: true,
      enumName: 'MyIconType',
      constantName: 'MY_CODEPOINTS'
    }
  },
  templates: {
    css: './my-custom-tp.css.hbs'
  },
  pathOptions: {
    ts: './src/types/icon-types.ts',
    json: './misc/icon-codepoints.json'
  },
  codepoints: {
    'chevron-left': 57344,
    'chevron-right': 57345
  },
  getIconId: ({ basename, relativeDirPath, absoluteFilePath, relativeFilePath, index }) => [
    index, 
    basename
  ].join('_')
};

When using Fantasticon via the API, the following default options are applied if not explicitly provided in the RunnerOptions object. Note that inputDir and outputDir must always be provided as they are omitted from the defaults.

Default Values

• name: 'icons'
• fontTypes: ['eot', 'woff2', 'woff'] (via FontAssetType)
• assetTypes: ['css', 'html', 'json', 'ts'] (via OtherAssetType)
• formatOptions: { json: { indent: 4 } }
• fontHeight: 300
• tag: 'i'
• prefix: 'icon'
• getIconId: Uses the internal getIconId utility.

Other keys like pathOptions, templates, codepoints, round, descent, normalize, selector, and fontsUrl are also available for configuration.

// Example of how these defaults might look when passed to a runner
const options = {
  inputDir: 'src/icons',
  outputDir: 'dist/fonts',
  name: 'my-custom-icons',
  // ... other overrides
};

The CLI allows you to customize the generation process. Note that some advanced options like formatOptions, pathOptions, getIconId, and templates must be configured via a configuration file or the JavaScript API.

Available CLI Options:

If you need to customize how icon IDs are generated, you can provide a function matching the GetIconIdFn signature. This function receives a GetIconIdOptions object containing metadata about the icon being processed.

Options object (GetIconIdOptions):

• basename: The filename without extension.
• relativeDirPath: The directory path relative to the project root.
• absoluteFilePath: The full absolute path to the file.
• relativeFilePath: The path to the file relative to the project root.
• index: The index of the icon (useful for handling duplicate names).

Example implementation:

import { GetIconIdFn } from 'fantasticon';

const myCustomIdGenerator: GetIconIdFn = (options) => {
  return `icon-${options.basename}`;
};

export interface GetIconIdOptions {
  basename: string;
  relativeDirPath: string;
  absoluteFilePath: string;
  relativeFilePath: string;
  index: number;
}

export type GetIconIdFn = (options: GetIconIdOptions) => string;