Features

SVGMaster allows you to streamline the usage of SVG in a web project.
It is more than a library, it is a whole high efficient and maintainable workflow based on SVG.

SVGMaster delivers an amount of unique features:

One single SVG library

Be careful, we said "library", not "sprite sheet".

sprite sheets are so 2008. They are a breeze to use but a pain to create and maintain. There are a good number of tools that will help you during the creation of a sprite sheet but if this is true for PNGs, it is not so true when it comes to SVGs.

What SVGMaster promotes is the usage of a single SVG file containing a symbol definition for every icon or background you need.

Forget about coordinates or stage size.

Load EVERY graphical asset you gonna need in 1 single HTTP request without the hassle of maintaining a sprite sheet.

It heavily makes use of the <use /> SVG tag to use instances of symbols when it comes to icons (and this was the easy part since reference to external library symbols is well supported across modern browsers) and when it comes to backgrounds it extracts the markup of the symbol in the library, build it in a base64 representation and inlines it in the style attribute of the DOM element to maximize compatibility.

Manages both icons and backgrounds

They have a very different approach and browser support when it comes use references from a single library.

SVGMaster takes care of all the verbose and boring stuff.

Super easy setup

Include the library, use custom attributes or class names on elements… Et voila! That's it.

By default, the default selector for icons is "i.icon" for icons and "*.iconBg" for backgrounds so the library will search for elements like <i class="icon icon-calendar" /> and <div class="iconBg icon-calendar">I am a div</div> but it is customizable.

It is a manager

No instances to maintain, just call SVGMaster.update() and all the unparsed instances will be rendered.

SVGMaster doesn't implement any kind of polling, you are responsible for triggering the update method whenever you replace elements or add new ones.

It lets you build your library

Via svgstore as a dev dependency. Everything is already packed.

Debug / showcase your library in page with a single command

Just call SVGMaster.showcase() to preview all icons in your library on the page itself. Do it programmatically or via the console.

When your are done just call SVGMaster.hideShowcase(). Check the full API.

This demo page is loading a big library (103 icons) to better present the showcase feature. Most of the icons are not used elsewhere in the page, so typically the library file could be 10x smaller.

A few demo icons

In an h1 sample element

In an h2 sample element

In an h3 sample element

In an h4 sample element

In an h5 sample element

In an h6 sample element

In a paragraph. By default, they simply have inline behavior, just like images .

Using this simple CSS rule:


.icon {
	width: 1em;
	height: 1em;
}

you can easily have icons that resize according to the font-size of the parent element.

If you want to have an icon twice as big, simply define it as 2em wide/high. Or use pixels if you really want to.

If you have any specific icon that has different aspect ratio (not square), simply specify a more specific rule:


.icon.icon-whatever {
	width: 2em;
	height: 1em;
}

A few backgrounds

This is a div with an SVG background.

Background vector designed by Freepik

This is another div with an SVG background.

SVG > Dingbat fonts

Dingbat/icon fonts are cool, but:

they are monochromatic
they consist of one single layer/element
they are confusing and need a lot of CSS rules to assign glyphs code to something meaningful
All glyphs share the same aspect ratio
Elements can be resized ONLY via font-size

SVGs on the other side:

consist in structured markup that let you have different parts in a single icon/background
parts and symbol can have meaningful class names/ids
can be animated via CSS transitions or animations
can be animated via SMIL

Dingbat/icon fonts had the advantage to contain multiple elements in one single resource file and have many tools that help to streamline the process… until now.

Now you have no excuses anymore :)

Styling/animating parts with CSS

By default, SVGMaster instantiates a symbol using the <use /> tag. It creates a shadow DOM element that you cannot simply style via CSS unless the SVG itself is written for that purpose (using inherit as value for fills/strokes).

Instantiating saves memory and most of the times you don't need to recolor/transition/animate a part of a single instance of an icon via CSS. When needed simply add a svgmaster-clone attribute to the element and instead of instantiating SVGMaster will clone the symbol, keeping the content in the main DOM so that you can easily style it.

Styling icon parts via CSS heavily depends on how the SVG is written. An SVG is not your usual graphical asset. It is a markup language and offers a lot of customization.

A visual property of an SVG element can be defined i nthree ways:

Presentation attributes (lowest priority)
External stylesheet
Inline stylesheet (highest priority)

When cloning a symbol you will be able to override a property unless it is using inline style. In that case you will need the !important directive (which is not a good practice but inlining styles isn't either).

standard icon

CSS recolored icon (no clone / not working)

CSS recolored icon

CSS transition on hover

CSS animation

Just to recap:

Restyling not needed: nothing needed
Restyling for every instance: Just define a CSS rule (i.e.: .graduate-dress {fill: yellow;} (add !important if the original SVG uses inline styles))
Restyling a single instance: cloning needed (add svgmaster-clone attribute, write your CSS rule with or without !important)

Usage / Workflow recap

As a dev tool:

Install via npm install svgmaster --save
Customize Gruntfile.js, task "svgstore" to add folders for libraries to be built
Build libraries with grunt libraries
If needed build changes to the library with grunt
If needed run tests with tape test/SVGMaster.js or npm test

As a client side library:

Include dist/svgmaster.min.js in your markup
Define in your CSS a basic rule for icons: .icon {width: 1em; height: 1em;}
(Optional) If you have some icon that are not square add specific rule for the aspect ratio: .icon.icon-pen, .icon.icon-key {width: 2em;}
(Optional) If you need the showcase functionality (aka debugging) and you want it to look pretty include dist/svgmaster.min.css in your page
Use <i class="icon icon-calendar"></i> for icons or <div class="iconBg icon-calendar"></div> for backgrounds
(Optional) You can override the default selector to be able to use something like: <span data-icon="icon-calendar"></span>. Check the API
Call SVGMaster.update()

API

getIconElements: Retrieves the matching icon elements, without performing any operation
@param {jQuery} [target] A jquery element to limit the search. If not provided defaults to the body element
@return {jQuery} A jQuery collection of matching elements
getBackgroundElements: Retrieves the matching background elements, without performing any operation
@param {jQuery} [target] A jquery element to limit the search. If not provided defaults to the body element
@return {jQuery} A jQuery collection of matching elements
replaceIcons: Replace elements matching IconsSelector selector with the SVG item while keeping the classes
@param {jQuery} target Narrows the search to descendants of this element
replaceBackgrounds: Parses elements matching BgsSelectors inlining the SVG content as (base64 encoded) background-url property
@param {jQuery} target Narrows the search to descendants of this element
update: Parses icons and background (only if not already parsed)
@param {jQuery} [target] Set it to narrow the search to descendants of this element. If falsy defaults to the body element
loadLibrary: Load library and invoke the update method when done
@param {String} [url] The url of the library to load. If falsy the default library specified via will be used
setIconSelector: Sets the icons selector pattern to match in jQuery selector format
@param {String} selector The selector string
getIconSelector: Gets the icons selector pattern to match in jQuery selector format
@return {String} The selector string
setBackgroundSelector: Sets the backgrounds selector pattern to match in jQuery selector format
@param {String} selector The selector string
getBackgroundSelector: Gets the backgrounds selector pattern to match in jQuery selector format
@return {String} The selector string
showcase: Opens the library showcase dialog
hideShowcase: Hides the showcase dialog
getDefaultLibraryURL: Gets the url of the library specified in the href attribute
@return {String} The url of the default library