:warning: This project is archived and the repository is no longer maintained.

Grunticon

         /'
        //
    .  //
    |\//7
   /' " \
  .   . .
  | (    \
  |  '._  '
  /    \'-'

A mystical CSS icon solution

grunticon is a Grunt.js task that makes it easy to manage icons and background images for all devices, preferring HD (retina) SVG icons but also provides fallback support for standard definition browsers, and old browsers alike. From a CSS perspective, it's easy to use, as it generates a class referencing each icon, and doesn't use CSS sprites.

grunticon takes a folder of SVG/PNG files (typically, icons that you've drawn in an application like Adobe Illustrator), and outputs them to CSS in 3 formats: svg data urls, png data urls, and a third fallback CSS file with references to regular png images, which are also automatically generated and placed in a folder.

grunticon also generates a small bit of JavaScript to drop into your site, which asynchronously loads the appropriate icon CSS depending on a browser's capabilities, and a preview HTML file with that loader script in place.

You can see a demonstration of the output here.

Version 2.0 updates

With Grunticon version 2.0, we've added the enhanceSVG option which allows you to easily style and animate your SVGs with CSS or add interactivity with JavaScript. Standard Grunticons are static background images that can't be styled or scripted because SVG only supports this ability if the SVG data is in the HTML document. In 2.0, you can now choose which icons you want to "enhance" and the new loader script will copy the icon SVG paths from the cached Grunticon stylesheet and inject them as an embedded SVG element for you to script and style as needed. This allows us to offer the best of both worlds: the full power of embedded SVGs but with none the wasted bandwidth of including SVGs in your page markup.

Remember that only browsers that support SVGs will see these effects so use them only for "enhancements" that don't break the experience when not present. Embedding icons also has some degree of execution overhead so we recommend using this feature sparingly: only embed an icon if you need to apply style or scripting, otherwise use the classic background-image icon.

To start - in your Gruntfile.js, set the value for enhanceSVG to true so the loader will parse the markup for icons that should be embedded at runtime:

grunticon: {
  foo: {
    files: {
      // Handle files here
    },
    options: {
      // Handle your options as you normally would here
      enhanceSVG: true
    }
  }
}

Then, make sure you get the new loader that's produced for you when you run grunt (it should be in the same place as before) and inline that script in the <head>.

Just after the loader, you'll need to call grunticon and pass your 3 CSS file paths to it as usual. Additionally though, you'll want to add a fourth argument to kick off the SVG embedding, which we've pre-defined for you as grunticon.svgLoadedCallback. In all, your call to grunticon will now look something like this:

grunticon(["icons.data.svg.css", "icons.data.png.css", "icons.fallback.css"], grunticon.svgLoadedCallback );

After you've done this, you can have any icon embedded in the page and ready for styling just by adding a data-grunticon-embed attribute.

<div class="icon-burger alt" data-grunticon-embed></div>

Once the loader runs, the SVG will be embedded:

<div style="background-image: none;" class="icon-burger alt">
  <svg class="svg-source" xmlns="http://www.w3.org/2000/svg" width="32" height="30" viewBox="170.6 12.6 32 30" enable-background="new 170.6 12.6 32 30">
    <g class="hamburger">
      <path class="buns" fill="#DDAF6D" d="M188.6 12.6h-4c-5.5 0-13 4.5-13 10v1c0 .6.4 1 1 1h28c.6 0 1-.4 1-1v-1c0-5.5-7.5-10-13-10zm-17 28c0 1.1.9 2 2 2h26c1.1 0 2-.9 2-2v-2h-30v2z">
      </path>
      <path class="burger" fill="#BB6F39" d="M172.6 34.6h28c1.1 0 2 .9 2 2s-.9 2-2 2h-28c-1.1 0-2-.9-2-2s.9-2 2-2z">
      </path>
      <path class="cheese" fill="#EFC75E" d="M172.6 30.6h28v4h-2l-3 3-3-3h-20v-4z">
      </path>
      <path class="lettuce" fill="#3DB39E" d="M200.6 27.6l-28-.1v.1c-1.1.2-2 1.2-2 2.4 0 1.4 1.1 2.5 2.5 2.5 1.2 0 2.2-.9 2.4-2h4.1c0 1.1 1.1 2 2.5 2s2.5-.9 2.5-2h4c0 1.1 1.1 2 2.5 2s2.5-.9 2.5-2h4.1c.2 1.1 1.2 2 2.4 2 1.4 0 2.5-1.1 2.5-2.5 0-1.1-.9-2.1-2-2.4z">
      </path>
      <path class="tomato" fill="#BF392C" d="M172.6 24.6h28v3h-28v-3z"></path>
      <path class="shadows" fill="#C69D63" d="M172.6 24.6h2c-.6 0-1-.4-1-1v-1c0-5.5 7.5-10 13-10h-2c-5.5 0-13 4.5-13 10v1c0 .5.4 1 1 1zm1 16v-2h-2v2c0 1.1.9 2 2 2h2c-1.1 0-2-.9-2-2z">
      </path>
      <path class="burger-shadow" fill="#A86433" d="M172.6 36.6c0-1.1.9-2 2-2h-2c-1.1 0-2 .9-2 2s.9 2 2 2h2c-1.1 0-2-.9-2-2z">
      </path>
      <path fill="#37A18E" d="M172.6 30.1c0-1.2.9-2.2 2-2.4v-.1h-2v.1c-1.1.2-2 1.2-2 2.4 0 1.4 1.1 2.5 2.5 2.5.4 0 .7-.1 1-.2-.9-.4-1.5-1.3-1.5-2.3zm9 .5h-2c0 1.1 1.1 2 2.5 2 .4 0 .7-.1 1-.2-.9-.3-1.5-1-1.5-1.8zm9 0h-2c0 1.1 1.1 2 2.5 2 .4 0 .7-.1 1-.2-.9-.3-1.5-1-1.5-1.8zm9 0h-2c.2 1.1 1.2 2 2.4 2 .4 0 .7-.1 1-.2-.7-.4-1.2-1-1.4-1.8z" class="lettuce-shadow">
      </path>
    </g>
  </svg>
</div>

Now, style appropriately:

  .icon-burger {
    width: 32px;
    height: 30px;
    display: inline-block;
  }
  .icon-burger.alt .cheese {
    fill: red;
  }
  .icon-burger.alt .buns {
    fill: orange;
  }
  .icon-burger.alt .burger {
    fill: yellow;
  }
  .icon-burger.alt .lettuce {
    fill: green;
  }

And voila! Styled SVG icons!

Check out our example at http://filamentgroup.github.io/grunticon/example/output/preview.html

Also: How to use SVG Embedding across domains

If you're hosting your grunticon CSS on a different domain than your HTML, you will need to do a little extra configuration to use SVG Embedding.

Set the corsEmbed option to true in your gruntfile. This adds a little extra scripting to the grunticon loader so that it can make a cross-domain request.
Once that's in, change the callback at the end of your grunticon call to reference svgLoadedCORSCallback instead of the one listed above.
That might be enough, but if not, you'll need to enable cross-domain requests on the server where the CSS is hosted. Here's how that looks in Apache .htaccess for example:

<IfModule mod_headers.c>
    Header add Access-Control-Allow-Origin "*"
</IfModule>

(That "*" can be a particular domain if you want)

Getting Started

This plugin requires Grunt ~0.4.2

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. You might also check out Chris Coyier’s great article, Grunt for People Who Think Things Like Grunt are Weird and Hard.

Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-grunticon --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-grunticon');

The "grunticon" task

For a brief overview of the Grunticon workflow, particularly from a designer's perspective, you might check out Todd Parker's article, A Designer’s Guide to Grumpicon, which covers basic SVG workflow tips for both Grunticon and Grumpicon.

Required configuration properties

grunticon has a files object that needs to be filled in order to run, this files object currently requires that a cwd, and a dest dir are placed, and therefore will blow up without it. This will be fixed to better fit the pattern set by Grunt for this.

These can be set in your Gruntfile.js config file. Grunticon is a multitask, making it easy to create as many export batches as you'd like. Just create one or more custom named objects within the grunticon object, and configure Grunticon options within it, like so:

grunticon: {
	myIcons: {
		files: [{
			expand: true,
			cwd: 'example/source',
			src: ['*.svg', '*.png'],
			dest: "example/output"
		}],
		options: {
		}
	}
}

IMPORTANT NOTE: grunticon will overwrite any files in the dest directory if they are of the same name as a file that grunticon needs to create. For easiest results, you can set dest to a folder that does not yet exist in your directory and grunticon will create that folder, or set it to an existing folder and be sure to configure grunticon to create file names that do not already exist in that folder.

With these configuration properties set, you can add grunticon to your defau

Grunticon

Install / Use

README

Grunticon

A mystical CSS icon solution

Version 2.0 updates

Also: How to use SVG Embedding across domains

Getting Started

The "grunticon" task

Required configuration properties