Utility for using SVG images as icons on the web with pure CSS and/or DOM injection
npm install iconify
iconify lets you use SVG images as icons on the web with pure CSS and/or DOM injection.
It runs on both the server/command-line and in the browser. On the server it helps you generate static CSS files. In the browser it helps you dynamically generate CSS rules from SVG images for monochromatic icons, as well as inject SVG content into the DOM for richer customization (multiple colors, animations, etc.).
iconify takes an SVG file like this one (for the "thumb-up" icon from open-iconic):
``xml`
which looks like:
and creates CSS rules like these:
`css`
.icon {
display: inline-block;
}
.inline.icon {
background-color: transparent;
-webkit-mask-box-image: none !important;
}
.inline.icon svg {
display: block;
}
.icon.thumb-up {
-webkit-mask-box-image: url(data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSI4IiBoZWlnaHQ9IjgiIHZpZXdib3g9IjAgMCA4IDgiPjxwYXRoIGQ9Im00LjQ3IDBjLS4xOS4wMi0uMzcuMTUtLjQ3LjM0LS4xMy4yNi0xLjA5IDIuMTktMS4yOCAyLjM4LS4xOS4xOS0uNDQuMjgtLjcyLjI4djRoMy41Yy4yMSAwIC4zOS0uMTMuNDctLjMxIDAgMCAxLjAzLTIuOTEgMS4wMy0zLjE5IDAtLjI4LS4yMi0uNS0uNS0uNWgtMS41Yy0uMjggMC0uNS0uMjUtLjUtLjVzLjM5LTEuNTguNDctMS44NGMuMDgtLjI2LS4wNS0uNTQtLjMxLS42My0uMDctLjAyLS4xMi0uMDQtLjE5LS4wM3ptLTQuNDcgM3Y0aDF2LTRoLTF6Ii8+PC9zdmc+);
}
The last rule there for .icon.thumb-up is the really important one. Its -webkit-mask-box-image property value is a base64-encoded data URI that represents the contents of the original SVG image.
Using SVG images as masks allows re-use of single rules to render icons with any color you want by setting the CSS background-color of a particular icon element. For example, in addition to the above CSS, if your document contains this:
`html`
and you add this to your page's CSS:
`css`
.icon {
background-color: hotpink;
width: 5em;
height: 5em;
}
then you will get this:
If you need fancier icons -- e.g. with more colors, clever animations, or other pretty effects -- then iconify can help as well. If you start with the monochromatic example above and then do this:
`javascript`
iconify($('.thumb-up.icon'));
with some extra CSS:
`css`
.inline.icon {
fill: hotpink;
}
then your page will look the same as above, but the icon element's DOM will now look like this:
`html`
You can then manipulate the inlined SVG content as you wish. For example, change it to an outline:
`css`
.inline.icon {
fill: none;
stroke: black;
stroke-width: .1;
}
.inline.icon path {
transform: translate(.05px, .05px);
}
npm install iconify [-g]
Note - as of iconify@1.0.0, NodeJS version 4.x or newer is required due to jsdom@>=7.0.0's requirement as such (read why here). iconify@0 maintains compatibility with NodeJS versions as early as 0.10.x, but should be considered deprecated.
iconify icons.svg > icons.css
`javascript`
require('iconify').load('icons.svg', {
output: process.stdout // or any stream.Writable
});
`html`
`html`
See examples/ for more...examples.
Injects SVG content inline into icon_element.
Returns jQuery-wrapped icon_element for chaining.
* _icon_element_ can be either a plain old DOM element, or already wrapped with jQuery, and should have classes specifying both the icon family (default: .icon) and icon name (e.g. .thumb-up) as defined by some pre-existing static CSS, or use of iconify.load().
Generates CSS rules for icons from source_image.
Returns a jQuery.Deferred "promise" that resolves when CSS rules are successfully generated, or is rejected if there's a problem.
* _source_image_ can be either the path/URL (server-/client-side, respectively) to an SVG file, or a string containing the SVG content itself
* _options_ (optional) used to customize the resulting CSS; defaults:
`javascript`
{
dataUriFormat: 'base64',
family: 'icon'
}
See source for more details...
Outputs CSS rules to stdout for icons from as if those files were given to iconify.load().
* _[--options]_ can be specified to customize a particular command's behavior. All of the options that can be provided to iconify.load() can be specified this way, with their names dash-ed rather than camelCased -- e.g. --data-uri-format base64 would be equivalent to { dataUriFormat: 'base64' }
* __: at least one path to an input file () is required, which will be converted into CSS rules for the icon(s) defined therein. If a file contains a single icon then the file's name, minus the extension, will be the default name for that icon, unless one is already given via the --name option.
An additional --transform option is available to allow arbitrary customization of how file contents are processed, and with which options. The s given will be resolved and loaded as NodeJS modules defining appropriate transformer functions.
A transformer function is any function accepting two arguments, i.e. function(input, output) { ... }, where input is a readable stream and output is a writable stream, both in object mode. Objects read from or written to these streams should contain source and options properties, which will ultimately be used as the first and second arguments to iconify.load(), respectively.
For example, here's a contrived transformer function that will set the icon family to magicon:
`javascript`
// set-family.js
module.exports = function(input, output) {
input.on('data', function(item) {
item.options.family = 'magicon';
output.write(item);
});
};
which could be used like so:
`
iconify --transform ./set-family my-icons.svg
(Of course in this case you could also just use the global --family option: iconify --family magicon my-icons.svg.)
When multiple comma-separated paths are given to the --transform option then the corresponding transformer functions are chained together, with the input of one being the output` from the one before it.
Much inspiration taken from Iconic.