@shgysk8zer0/svg-use-symbols

An npm package for use with <svg><use xlink:href=""></use></svg>

• Code of Conduct
• Contributing

Installation

npm i @shgysk8zer0/svg-use-symbols

Supports

• Parsing from JSON and YAML files
  • Creating multiple outputs by using an array of objects with output and icons
  • Creating a single output file by using simple id and path object
• Creating from directories
• Fetching SVGs from URLs
• Migrating from svg-sprite-generate (converts CSV to JSON or YAML)

Usage

In HTML

This generates a series of <symbol>s, which have the counterpart of <use> for using the icons on a webiste:

<svg>
  <use xlink:href="/path/to/icons.svg#id"></use>
</svg>

CLI

Usage: @shgysk8zer0/svg-use-symbols [options]

An npm package for use with `<svg><use xlink:href=""></use></svg>`

Options:
  -V, --version                output the version number
  -c, --config [config]        JSON or YAML config file
  -d, --directory [directory]  path to directory of SVGs
  -e, --encoding [encoding]    encoding (default: "utf8")
  -f, --format [format]        output format for migrating from CSV (default: "json")
  -l, --list [list]            comma separated list of SVGs
  -m, --migrate [migrate]      path to deprecated CSV config file
  -o, --output [output]        output file
  -h, --help                   display help for command

svg-use-symbols -c path/to/config.yml -o img/icons.svg
svg use-symbols -d path/to/svgs/ -o img/icons.svg
svg-use-symbols -l icons/1.svg,icons/2.svg -o img/icons.svg

Node

Simple usage

import { generateSymbols } from '@shgysk8zer0/svg-use-symbols';

await generateSymbols('config.json');

Using require()

const { generateSymbols } = require('@shgysk8zer0/svg-use-symbols');

// Top-level await not allowed
generateSymbols('config.json').catch(console.error);

Advanced usage

import { generateSymbol, writeSVG } from '@shgysk8zer0/svg-use-symbols';
const controller = new AbortController();

const config = {
  "file-media": "octicons/file-media.svg",
  "external": "https://example.com/external.svg",
};

const symbols = await Promise.all(
  Object.entries(config).map(async ([id, path]) => {
    try {
      const symbol = await generateSymbol(id, path, { encoding: 'utf8', signal });
      // Mutate symbol, perhaps?
      return symbol;
    } catch(err) {
      console.error(err);
      controller.abort();
    }
  })
);

await writeSVG('output.svg', symbols, { encoding: 'utf8' });

Config files

This supports YAML, JSON, and to a limited extent, CSV. CSV is temporarily offered for those migrating from svg-sprite-generator and will be removed in v2. Please see the section on migrating.

For JSON and YAML, two different formats are supported:

{
  "id": "path/to/icon.svg",
  "another": "https://example.com/path/to/icon.svg"
}

This will create <symbol id=":id">s with id taken from the key and contents from the SVG file at the given path/URL. This MUST have output (-o or --output) set. This also applies for the temporarily supported CSV config files.

It may also use:

[
  {
    "output": "path/to/output.svg",
    "icons": {
      "id": "path/to/icon.svg",
      "another": "https://example.com/path/to/icon.svg"
    }
  },
  {
    "output": "path/to/output2.svg",
    "icons": {
      "id": "path/to/another-icon.svg",
      "another": "https://example.com/path/to/another-icon.svg"
    }
  }
]

This will create output files output.svg and output2.svg, each containing there respective <symbol>s.

Migrating from svg-sprite-generator

svg-use-symbols -m path/to/config.csv -o path/to/config.json
# Or
svg-use-symbols --migrate path/to/config.csv --format json --output /path/to/config.json
# Or
svg-use-symbols --migrate path/to/config.csv --format yaml --output /path/to/config.yaml