Hydra-svg-js NPM

Hydra-SVG-JS

This package allows you to use and manage your favorite svg icon libraries within your project.

Find your favorite icon package already made in our hydra-packs package!

Actions	Descriptions
hydrate`function`	merge attributes and append child elements to create an icon.
observe`function`	attach a `MutationObserver` to rehydrate with the new icon selections.
purge`function` `command`	create a custom file of only the icons used in your project.
generate`function` `command`	create your own package of icons to use in your own projects or share with others.
inject`function` `command`	hard code your svg elements into your project files
eject`function` `command`	remove your hard coded svg elements

Installation
Usage
Functions
Functions with Commands
Credits
License (MIT)

Installation

Install the package with npm or yarn:

npm install hydra-svg-js

yarn add hydra-svg-js

And you're done!

Usage

Actions can be used as functions in a file, or a command on the command line unless they are meant for the DOM.

These actions will be performed on any svg element that has both the pack and icon attribute, assuming that they name an icon that exists in the pack named.

Functions

Hydrate

Hydrate merge attributes and append child elements to create an icon. As opposed to other packages that replace tags, this starts with and keeps your svg tag which prevents flickering and makes it easier to handle icon attributes together with added custom attributes.

hydrate( packs, svgs, options = { observe: false })


packs	`object`	`{ pack-name:{ icon-name: { icon-object }}}`
svgs	`array`	`[SVGElement]`
options	`object`	`{ observe: false }`
	observe	`boolean`

Observe option is a builtin call to the observe function below, after the icons have been hydrated.

Observe

observe( packs, svgs)


packs	`object`	`{ pack-name: { icon-name: { icon-object }}}`
svgs	`array`	`[SVGElement]`

Functions with Commands

Purge

command

hydra purge [packs...] [-i, --input]=src [-o, --output]=dist


packs	`array`	path: `./pack.json` module: `hydra-pack`
input	`string`	`glob` `'src/*/.{js,html}'`
output	`string`	`src/purged` will output `src/purged.json`

function

purge( packs, input, output, overrides = {includes: {}, excludes: {}, extends: {}})


packs	`object`	`{ pack-name:{ icon-name: { icon-object }}}`
input	`string`	`glob` `'src/*/.{js,html}'`
output	`string`	`src/purged` will output `src/purged.json`
overrides	`object`	`{ includes: {}, excludes: {}, extends: {}}`
	includes	`object` `{ pack-name: [ icon-name ]}`
	excludes	`object` `{ pack-name: [ icon-name ]}`
	extends	`object` `{ pack-name: { icon-name: { icon-object }}}`

Generate

Generate provides a way create your own package of icons to use in your own projects or share with others. For the intended outcome, you must name the directory after the name of your package, and each svg file after the name of the svg icon within. The generator determines the name of the package and icon accordingly.

Example: 1. input: src/packs/bootstrap/alarm.svg 2. output: dist/packs/bootstrap.json 3. contents: { "alarm": ...iconObject }

SVGO is already builtin and enabled to optimize your svg icons before they are generated into json.

SVGO default settings are used except that removeViewbox is disabled, and removeDimensions is enabled.

command

hydra generate [packs] [-i, --input]=src [-o, --output]=dist [-p, --optimize] [-n, --no-optimize]


packs	`string` `array`	Name of pack and folder within the input directory. E.g. `bootstrap` for `src/packs/bootstrap`
input	`string`	`glob` `'src/*/.{js,html}'`
output	`string`	To output the json file within the named directoy. E.g. the `bootstrap` pack with the output `src/packs` will result in `src/packs/bootstrap.json`
optimize	`boolean`	Use the default settings to optimize your svg element with `SVGO`
no-optimize	`boolean`	Disable svg icon optimization

function

generate( packs, input, output, options = {
	optimize: {},
	hook: {folder: null, object: null, file: null}
})


packs	`string` `array`	Name of the pack and folder within the input directory. E.g. `bootstrap` for `src/packs/bootstrap`. Name multiple with an array for more than one. *Use an empty array as the symbol for all within the directory.*
input	`string`	`glob` `'src/*/.{js,html}'`
output	`string`	To output the json file within the named directoy. E.g. the `bootstrap` pack with the output `src/packs` will result in `src/packs/bootstrap.json`
optimize	`boolean` `object`	Set to false in order to disable optimization or override the configuration defaults.
hook	`object`	`{ folder: () => {}, object: () => {} file: () => {} }`
	folder	`null` `function` `callback({ total, input, output,path.parse(input)})` This hook is called for each folder right before each icon object is generated and output file is written.
	object	`null` `function` `callback({ count, total, name })` This hook is right after each icon object is generated and before the output file is written.
	file	`null` `function` `callback({ total, input, output,path.parse(output)})` This hook is called after the output file is written.

Inject

Make sure to run eject each time before running inject to ensure that your svg starts from a clean slate. Otherwise attributes from a prior injection may remain. Inject merges with the attributes already written so that any user made customizations are not lost. A record of the old icon attributes are not kept in memory to be removed. Therefore, those old icon attributes are assumed to also be user made customizations.

command