@ads-medienmanufaktur/easy-sprite

Merge your SVG files or raw SVG code into one concise and minimal sprite sheet and build your own SVG library :)

Usage no npm install needed!

<script type="module">
  import adsMedienmanufakturEasySprite from 'https://cdn.skypack.dev/@ads-medienmanufaktur/easy-sprite';
</script>

README

view on npm

Easy Sprite by ADS Medienmanufaktur

Merge your SVG files or raw SVG code into one concise and minimal sprite sheet and build your own SVG library :)


Overview

This package allows you to edit a sprite sheet without even opening it... All right from within your code! You only have to provide a sprite sheet to use. If the sprite does not exist it will be created.

Usage

As a global CLI

npm i -g @ads-medienmanufaktur/easy-sprite

From anywhere you can now use one of 2 commands:

svg-sprite <command> or sprite <command>

The commands of the CLI respond to the exported functions of the API:

  • --version,-v: Display version
  • --help,-h: Display help
  • --add,-a: Add SVG(s) to a sprite sheet (or initialize a new sprite sheet)
  • --get,-g: Get all IDs in current sprite sheet
  • --remove,-r: Remove an ID from the sprite sheet You will be prompted to provide the parameters for the API functions in a step-by-step process. All functions are chainable like:
sprite --add --get

Chained commands are executed after all parameters for each command have been provided.

As an API

To use this package in a project install and require it. Then you can call each function as you would using any other module. For more details, see the API Reference below. If you intend to use the Easy Sprite API inside a VueJS project: don't! VueJS cannot handle importing NPM modules without them being a Vue plugin. At some point in the future, this will also be provided as a Vue plugin. In the meantime: Use the modules API in a NodeJS Server and simply link the generated sprite sheet in he vueJS template as shown in the HTML below.

Using the generated sprite sheet

In any HTML document create an SVG tag and inside it a USE tag. Using xlink:href attribute on the USE tag link to the external sprite sheet and require a specific icon using the ID (#) selector. Example:

<svg class="icon" width="25" height="25">
    <use xlink:href="sprite#iconId"></use>
</svg>

Notes on generated sprite sheet

All SVG code (including the code extracted from SVG files) will be optimized using SVGO. By default all Fills are remove to allow styling the icon with CSS. This results in unicolor icons (if the individual paths are not styled separately from the main SVG element). To have multicolored icons, in the original SVG use a stroke to fill the shape.

API Reference

Simplify SVG  sprite handling

Example

const svgSprite = require('easy-sprite');

svgSprite.add(location, name, svgSource, isCode) ⇒ Promise.<String>

Adds the given SVG(s) (either files or codes) to a provided sprite sheet. If the sprite sheet does not exist, it will be created. The path to the sprite sheet will be returned

Kind: static method of easy-sprite

Param Type Description
location The directory to save the sprite sheet in
name The name to save the sprite sheet as (.svg will be appended if not present)
svgSource String The source of the SVG as a path string. This can either point to a single .svg file or a directory of SVG files
isCode Boolean A boolean which has to be provided when the SVG source is raw SVG code

Example

const svgSprite = require('easy-sprite')
let msg;
//adding SVG file(s)
msg=await svgSprite.add(PATH.join(path,to,spriteDir),name,PATH.join(path,to,SVG,files),false);
//adding raw SVG Code
msg=await svgSprite.add(PATH.join(path,to,sprite),code,true);
console.log(msg);

svgSprite.get(location, name) ⇒ Promise.<Array.<String>>

Extracts all symbols from the SVG object {@see objectifySvg} and returns a map of their id attribute

Kind: static method of easy-sprite

Param Description
location The directory to save the sprite sheet in
name The name to save the sprite sheet as (.svg will be appended if not present)

Example

const svgSprite = require('easy-sprite')

const msg=await svgSprite.get(PATH.join(path,to,sprite));
console.log(msg);

svgSprite.remove(location, name, id) ⇒ Promise.<String>

Deletes a specific ID from the given sprite sheet

Kind: static method of easy-sprite

Param Type Description
location The directory to save the sprite sheet in
name The name to save the sprite sheet as (.svg will be appended if not present)
id String The id to be removed

Example

const svgSprite = require('easy-sprite')

const msg=await svgSprite.remove(PATH.join(path,to,sprite),iconId);
console.log(msg);

easy-sprite~makeSVG(ids, file, isCode) ⇒ Promise.<Object>

Generates an object representation of the SVG sprite sheet and returns it. {@see objectifySvg}

Kind: inner method of easy-sprite

Param Type Description
ids Array.<String> An array of existing IDs in the sprite {@see get}
file String The path to an SVG source
isCode Boolean A boolean indicating whether the SVG source is raw svg code or contained in a file

easy-sprite~objectifySvg(file, isCode, optimize) ⇒ Promise.<Object>

Parses an SVG string (either from file or from raw SVG code) and returns the SVG as an object to {@see makeSVG}. Module used for SVG parsing: https://www.npmjs.com/package/svgson

Kind: inner method of easy-sprite

Param Type Description
file String The path to the SVG file or raw SVG code
isCode Boolean Indicates whether the file is raw SVG code or not
optimize Boolean Whether to optimize the SVG data. Needed because symbol elements are stripped when parsing whole sprite sheet.

easy-sprite~nameToID(name) ⇒ string

Used to generate symbol IDs. IDs are derived from the lowercase filenames, which are hyphenated. E.g: Add User becomes add-user

Kind: inner method of easy-sprite

Param Type Description
name String The name to convert

© 2020 ADS Medienmanufaktur <info@ads-medienmanufaktur.de>.

Documented by jsdoc-to-markdown.

Easy Sprite is licensed under the MIT license.